Skip to content

docs: Epic 5 design spec (validation landing page, business setup checklist) #1004

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
developer-ainative merged 1 commit into from
Oct 6, 2026
Merged

docs: Epic 5 design spec (validation landing page, business setup checklist) #1004

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions docs/superpowers/specs/2026-10-06-epic5-validation-business-setup-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Epic 5 — Validation + Business Setup Design Spec

**Status:** self-approved under the standing autonomous-loop authorization (no human review gate for this spec pass — explicit user instruction this session: proceed through the entire backlog without stopping between epics/waves).

**Scope (per explicit user ruling this session):**
- **E5.1 (reorder phases) — DROPPED.** The investigation fork found no confirmed-wrong phase/act ordering anywhere in the live codebase (`lib/build/acts.ts`'s `APP_ACT_LABELS`/`COMPANY_ACT_LABELS`, `components/build/WorkspaceShell.tsx:93-113`'s `currentActIndex()` — both already carry doc comments citing a real, already-fixed 2026-09-09 bug). The user explicitly chose to skip this story rather than invent a reorder with no confirmed defect behind it.
- **E5.2 (a spike) — DEFERRED.** No topic, question, or probe was ever specified for this story anywhere in this session's record of the original backlog doc. The user indicated they would supply the real spike question; it has not yet arrived as of this spec. This story is excluded from the implementation plan below and should be added in a follow-up spec/plan once scoped.
- **E5.3 (validation landing page) + BLD-18.1 through BLD-18.6 (business setup checklist)** — both confirmed via direct investigation to be genuinely new, unimplemented work with no prior art to reconcile against. This spec covers these two stories.

## Codebase reality (confirmed via direct investigation fork + direct file reads)

- **No validation/demand-check concept exists anywhere.** Grepped broadly for "validation", "validate demand", "smoke test" across `components/build/` and `lib/build/` — every hit (`output-validator.ts`, `ready-gate.ts`, `obedience-gate.ts`) is generic code/output validation, unrelated to pre-build demand validation. `components/build/screens/` has 13 screens today, none resembling a pre-build validation page.
- **No business-setup checklist UI exists anywhere.** Every "checklist" hit in the codebase (`BuildOverlays.tsx`'s `INFRA_ITEMS`, `app-artifacts.tsx:265-269`) is the existing technical-provisioning checklist (ZeroDB/ZeroMemory/Agent Cloud/Identity) — not business-setup concerns (incorporation, domain, payments).
- **Real, already-shipped adjacent infrastructure to reuse, not reinvent:**
- **Domain setup**: `components/build/DomainModal.tsx` — a real, shipped two-tab modal (buy a new domain via search/suggestions with pricing, or bring-your-own with DNS-record verification). `lib/build/danger-zone.ts`, `lib/build/railway-deploy.ts`, `lib/build/app-registry.ts` hold the real provisioning/teardown wiring.
- **Cap table / incorporation**: `lib/build/opencapstack.ts` — a real, working OpenCapStack integration. `loginServiceAccount()` (service-account auth, short-lived token, never cached) + `provisionCapTable()`-shaped calls create a real company record (`POST /api/v1/companies` → `{companyId}`), defaulting `companyType: 'Delaware C-Corp'` (no entity-type choice is surfaced to the founder yet — confirmed by its own doc comment).
- **Payments**: Stripe checkout already exists for the Builder subscription itself (`Pricing.tsx`'s `choose()`) — no existing "set up payments for YOUR business" flow (e.g., Stripe Connect for the founder's own customers) was found; this is a real gap BLD-18's payments module would need to address fresh.
- **Prior art that explored an adjacent but DIFFERENT shape**: closed issue #210 ("Per-project company cockpit dashboard: Tasks/Website/Email/Social/Business panels") — already shipped as a dashboard-panel concept (ongoing operational view), not a step-by-step setup checklist (one-time onboarding flow). BLD-18 is a different UI shape serving a different moment (getting a new company set up, not running an ongoing one) — not a duplicate of #210's shipped work.
- **No existing "setup" or "onboarding checklist" component** exists on `Live.tsx` or `Account.tsx` (only scattered unrelated uses of the word "setup" in comments/other contexts).

## Design

### E5.3 — Validation landing page (new)

A new screen, reachable after idea entry + kickoff (post `KickoffQuestions.tsx`, before the full `START_BUILD` generation sequence begins) for the Company track only (validating demand is a company concept; an App-track build has no "customers" to validate against pre-launch). Purpose: give the founder a real, live, shareable landing page for their idea BEFORE the full multi-artifact build runs, so they can gauge interest (shares, signups) while Cody builds everything else in the background.

Mechanism: reuses the SAME real artifact-generation pipeline every other artifact already uses (`POST /api/build/artifact` via `getClaudeCompletion()`) to generate a single lightweight landing-page artifact (headline, one-paragraph pitch, an email-capture form) — NOT the full `landing` company-track artifact (`ARTIFACT_PROMPTS.landing`, which is part of the generated-company's actual deliverable set and runs later in the normal sequence). This is a distinct, earlier, throwaway-style artifact whose only job is fast validation, served at a real public URL (reusing the existing `{slug}.ainative.studio` wildcard-host pattern already live for every company) immediately, before the rest of the build completes. Email-capture submissions are stored via the same `ensureTable`-then-write ZeroDB pattern every other new storage subsystem this session uses (a new `builder_validation_signups` table).

### BLD-18.1 through BLD-18.6 — Business setup checklist (new)

A new per-company checklist screen (reachable from `Live.tsx`, following the same navigation pattern `DocumentsPanel.tsx`/`AutoModePanel.tsx` already use as sibling panels), presenting a fixed, ordered list of real business-setup steps — distinct from #210's ongoing-operations cockpit, this is a one-time "get your business legally and operationally ready" flow:

1. **BLD-18.1 — Entity formation**: surfaces OpenCapStack's existing `provisionCapTable()` flow, but for the FIRST time exposes the entity-type choice to the founder (`'Delaware C-Corp' | 'LLC' | 'Other'`, OpenCapStack's own real enum, confirmed via `opencapstack.ts`'s doc comment) rather than hard-coding `'Delaware C-Corp'` — a genuinely new input, reusing the entirely real, already-working provisioning call underneath.
2. **BLD-18.2 — Domain**: deep-links to the existing, fully-shipped `DomainModal.tsx` (buy or BYO) — no new domain logic, just a checklist entry point into real existing UI.
3. **BLD-18.3 — Payments setup**: genuinely new — no existing "accept payments for YOUR business" flow exists. Scoped narrowly: a real Stripe Connect onboarding link (Stripe's own hosted onboarding flow, not a custom form) so the founder's OWN business can accept payments, distinct from the Builder subscription's own Stripe checkout.
4. **BLD-18.4 — Business email**: genuinely new — a real DNS-record disclosure step (reusing the SAME DNS-verification UI pattern `DomainModal.tsx`'s BYO-domain tab already has) guiding the founder to set up a business email (e.g., Google Workspace or a forwarding address) at their new domain — informational/checklist-only, no new provisioning call (no existing email-hosting provisioning API exists in this repo to automate this step).
5. **BLD-18.5 — Legal basics disclosure**: a static, informational checklist item (terms of service / privacy policy templates) — explicitly a disclosure-only step, not a generation feature, since no legal-document-generation capability exists or is in scope here.
6. **BLD-18.6 — Completion tracking**: a new ZeroDB table `builder_setup_checklist` (same `ensureTable`-then-write pattern), one row per company, tracking which of items 1-5 the founder has marked complete — persisted so the checklist state survives a page reload, following the same idempotent-create pattern every other new storage subsystem this session uses.

## Review Focus

- **E5.3's validation artifact must never be confused with the real `landing` company-track artifact** that runs later in the normal generation sequence — a founder who validates, then proceeds to full build, should see the FULL `landing` artifact replace the validation page's content at the appropriate point in the real sequence, not a stale validation-only page left live forever. Test: confirm the validation page's content is distinguishable (a different ZeroDB-backed record) from `state.generated.landing`, and that reaching the `landing` view in the normal sequence doesn't silently skip generation because a validation artifact already exists at that slug.
- **BLD-18.1's new entity-type choice must default to the SAME value `opencapstack.ts` already hard-codes** (`'Delaware C-Corp'`) when the founder doesn't make an explicit choice, so existing behavior for a founder who ignores this new checklist is unchanged.
- **BLD-18.3's Stripe Connect link must never be confused with the Builder subscription's own Stripe checkout** (`Pricing.tsx`'s `choose()`) — these are two distinct Stripe integrations (one for AINative's own revenue, one for the founder's business), and mixing their price IDs or redirect URLs would be a real, user-visible billing defect.
- **BLD-18.6's completion state must be per-company**, not per-user — a founder with multiple companies (confirmed real via `MyCompanies`/companies index this session) must see independent checklist progress for each one, keyed by the real company id, not a single global flag.
- **E5.1's drop and E5.2's deferral must be clearly communicated in the implementation plan** so a future executor doesn't mistake their absence for an oversight — both get an explicit "not in this plan" note rather than silent omission.
Loading