Phase 5 — AI assistance (overlay)

AI is not its own phase — it overlays every other phase. You meet it in three distinct places:

Decompose Wizard — fires after Phase 3 when you check “Use AI scaffold”. Idea → modules → features → criteria in ~90 seconds.
Persona Critique — right pane in Phase 4. 5 default personas review the active block; 3 specialty personas behind the picker.
Pattern D — Layer 2 suggestions in the Six-tab editor’s Behavior tab. AI generates structured action chains / view trees / scenarios.

This page covers all three.

Decompose Wizard

A 4-step modal that turns a 1-2 sentence project idea into a full project tree.

Step 1 — Archetype + idea text

┌──────────────────────────────────────┐
│ Pick the archetype:                  │
│ ◉ SaaS B2B    ○ SaaS B2C             │
│ ○ Mobile      ○ Internal             │
│ ○ API         ○ CLI                  │
│ ○ Other                              │
│                                      │
│ Describe your idea (≥ 20 chars):     │
│ ┌────────────────────────────────┐  │
│ │ A mobile habit tracker (iOS …) │  │
│ │                                │  │
│ └────────────────────────────────┘  │
│                                      │
│       [ Suggest modules → ]          │
└──────────────────────────────────────┘

7 archetypes seed the prompt with archetype-specific module patterns:

Archetype	Typical modules suggested
`saas-b2b`	Auth · Billing · Tenancy · Integrations · Admin
`saas-b2c`	Auth · Profile · Notifications · Discovery · Subscription
`mobile`	Onboarding · Habit list · Streak engine · Notifications · Settings
`internal`	Roles · Forms · Reports · Workflow · Admin
`api`	Auth · Resources · Webhooks · Idempotency · Docs
`cli`	Commands · Config · Output · Plugins · Update
`other`	(open-ended; LLM picks)

Click Suggest modules → posts to POST /ai/decompose/modules with { archetype, ideaText }. Server returns 5-7 modules. Cached at sha256(archetype + ideaText + model).

If cached: a small toast “Cached AI response (free)” — repeated tries on the same idea are instant + free.

Step 2 — Keep / drop modules

The wizard shows the suggested modules as a checklist:

☑ Habit list      — Add, edit, archive habits with frequency rules.
☑ Streak engine   — Compute current/longest streaks, handle timezones.
☑ Notifications   — Daily reminders, AI-timed nudges.
☐ Social          — Friends, leaderboards (out of scope per spec).
☑ Settings        — Profile, theme, notification prefs.

[ ← Back ]   [ Suggest features → ]

Uncheck what you don’t want. Need ≥ 1 kept to proceed.

Step 3 — Suggest features per kept module

Parallel calls to POST /ai/decompose/features, one per kept module. Each returns 4-7 feature suggestions:

Habit list
☑ Add new habit       — User can add a habit with name + frequency.
☑ Edit habit          — Change name / frequency / archive.
☑ Daily check-in      — Tap to log today's completion.
☐ Bulk import         — Defer to v2.
☑ Search & filter     — Filter by tag, frequency.

Streak engine
☑ Compute current streak  — From last consecutive checked days.
☑ Compute longest streak  — All-time max.
☐ Streak freeze power-up  — Premium feature.
☑ Timezone handling       — Anchor to user's local midnight.

[ ← Back ]   [ Suggest criteria → ]

Per-feature checkboxes; uncheck per-module. Same caching strategy.

Step 4 — Suggest criteria per kept feature

Parallel calls to POST /ai/decompose/criteria, one per kept feature. Each returns 3-5 EARS-structured criteria:

Add new habit
☑ WHEN user submits valid name → habit appears in list within 200ms
☑ IF name is empty → form shows "Name required" inline
☑ IF user has 50 habits (free tier limit) → upgrade modal appears

This is the only step where you cannot uncheck partial criteria for a single feature — keep the feature or drop it. Granular criteria editing happens later in the workspace.

Final — Bulk install

Click Install → the wizard mutes UI and fires:

For each kept module:
  POST /api/projects/:projectId/blocks  { atomKind: "module", title, metadata }
  For each kept feature in module:
    POST /api/projects/:projectId/blocks  { atomKind: "feature", title, parentId, metadata }
    For each kept criterion in feature:
      POST /api/projects/:projectId/blocks  { atomKind: "criterion", title, parentId, metadata }

Bulk endpoint coming in W12. For now sequential POSTs. ~5-10 seconds for a typical 5-module / 20-feature / 60-criterion seed.

On success the wizard closes; the workspace tree pane refreshes; the user lands inside the first kept module + first kept feature, ring at ~30%.

When the wizard auto-opens

/projects/:id/workspace?wizard=1 → the wizard renders open by default. Triggered by:

“Use AI scaffold” checked at project creation.
Dashboard’s ”✨ AI Decompose” quick action.
Sample gallery click.

?wizard=0 (or no param) → the workspace renders normally; user opens wizard manually from the right pane.

Persona Critique

Right-pane sub-tab. 5 personas visible by default + 3 in the picker overflow:

ID	Persona	Emoji	Specialty
`coach`	Coach	🎓	Gap-finder. What’s missing? Edge cases, error paths, untested criteria.
`pm-critic`	PM Critic	📋	Tightens user stories, value props, scope.
`architect`	Architect	🏗	Architectural concerns, ADRs, dependencies.
`qa`	QA	🔍	Test holes, suggests EARS criteria for skipped paths.
`ux`	UX	🎨	Interaction, copy, accessibility.
`security`	Security	🔒	OWASP, STRIDE, secrets, RBAC.
`performance`	Performance	⚡	Bottlenecks, p99, caching, payload size.
`accessibility`	Accessibility	♿	WCAG 2.2, screen reader, keyboard.

The 5 default cover most reviews; the 3 specialty personas (Security / Performance / Accessibility) appear behind the picker for targeted critiques.

How a critique runs

Click a persona button → mutate setPersona(id) + clear current critique.

Click Critique this block → POST /ai/critique with:

{ persona, blockKind, blockTitle, blockMetadata, contextFeatureName, contextModuleName }

Server checks cache (sha256 of all 6 inputs + model). On hit returns instantly with cacheHit: true.
On miss runs the LLM (default: claude-sonnet-4.6 via OpenRouter). Cost recorded.
Returns { critique: string, cost: number, cacheHit: boolean }.
UI renders the critique in a card with the persona avatar + a small cached indicator if cacheHit.

A single block can be critiqued by multiple personas; each persona renders its own critique card. Each critique is plain markdown — typically 3-5 numbered concerns, severity badges (🔴 / 🟡 / 🟢), and suggested next blocks at the bottom.

When the cache is your friend

A critique on an unchanged block is free — re-clicking doesn’t burn tokens.
A critique on a patched block (any metadata change) cache-misses → fresh LLM call.
Patterns: edit block → re-critique to see how concerns shifted; the diff between the two critiques is the qualitative reviewer view.

Pattern D — Layer 2 suggestions

Inside the Six-tab editor’s Behavior tab (Tab 4), for the 5 atom kinds that carry Layer 2 (feature, ui_view, rule, criterion, fixture):

Button	Pattern	What it does
🟡 Re-infer	C	Deterministic synthesis from related atoms (free).
⚪ Suggest with AI	D	LLM call returns structured Layer 2 (~$0.001-0.01/call).

Both open a Diff modal before applying: current vs suggested side-by-side, with the locked fields (🔒) preserved. Click Apply to merge; Cancel to discard.

Pattern D’s prompt includes:

Atom kind + current top-level fields (kind-specific).
Layer 1 prose (intent.userStory, intent.notes).
Linked atoms (via relations) and their existing Layer 2 — the model has surrounding context.
A kind-specific system prompt instructing it to emit JSON matching the Layer 2 Zod schema.

The validator rejects shapes that don’t fit before they reach the diff modal. A failed suggestion shows an error toast + the raw response in dev mode; the user can re-run.

See Concepts → Four patterns for the full provenance model and the merge logic, and Spec → Layer 2 schemas for the structures the LLM emits.

Cost + caching at a glance

Surface	Per-call cost (claude-sonnet-4.6)	Cache key	Free re-runs?
Decompose Wizard step 1 (modules)	~$0.005	`archetype + ideaText + model`	Yes — same idea, same archetype.
Decompose Wizard step 2 (features × N modules)	~$0.005 × N	per-module key	Yes — per-module.
Decompose Wizard step 3 (criteria × N features)	~$0.003 × N	per-feature key	Yes — per-feature.
Persona Critique	~$0.003	persona + block + metadata + model	Yes — unchanged block.
Pattern D suggestion	~$0.001-0.01	atom kind + Layer 1 + Layer 2 current + linked atoms + model	Yes — exact-match cache.

Plan limits (Phase 1): FREE = 50 calls/day across all surfaces; SOLO = 500/day; TEAM = unlimited (rate-limited to ~10 req/min/user).