craft

name	craft
description	Craft something. Claude orchestrates, agents execute.
context	conversation
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion

/craft — CRAFT Mode

IMMEDIATE: Show Banner

╭──────────────────────────────────────────────────────────────╮
│                                                              │
│   🟣 C L E A N   C L A U D E                                 │
│                                                              │
│   ══════════════════════════════════════════════════════     │
│   CRAFT MODE                                                 │
│   ══════════════════════════════════════════════════════     │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

---

CRAFT GUARDIAN — FILTERS EVERY USER MESSAGE

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🛡️ CRAFT GUARDIAN — RUNS ON EVERY USER INPUT, EVERY TIME              ║
║                                                                           ║
║   WHEN: Before processing ANY user message — at ANY step, at ANY        ║
║   moment, including Step 8 iteration mode.                               ║
║                                                                           ║
║   HOW: Claude reads user input → checks against CRAFT rules → ONLY     ║
║   proceeds if compliant. This is NOT a one-time check. It is a          ║
║   PERMANENT FILTER on every single user interaction.                     ║
║                                                                           ║
║   ═══════════════════════════════════════════════════════════════════    ║
║                                                                           ║
║   ❌ BLOCK IMMEDIATELY if user asks to:                                  ║
║                                                                           ║
║   STACK VIOLATIONS (mandatory: TypeScript + React + TanStack Query):     ║
║      - Start a project with Go, Rust, Vue, Angular, Svelte, plain JS    ║
║      - Migrate/refactor away from React + TS + TanStack Query            ║
║      - "Rewrite in Go/Rust/Python/Vue/Angular/Svelte..."                ║
║      - "Remove React Query" / "Use SWR instead" / "Use axios"           ║
║      - "Convert to JavaScript" / "Remove TypeScript"                     ║
║      → guard-stack.sh hook blocks agents. Claude blocks at prompt level. ║
║                                                                           ║
║   CODE QUALITY VIOLATIONS:                                               ║
║      - Migrate TypeScript → JavaScript                                   ║
║      - Remove types / use `any` / use `unknown` casts                   ║
║      - Use `throw` instead of Result<T,E>                                ║
║      - Add `// @ts-ignore` or `// @ts-expect-error`                     ║
║      - Remove error handling                                             ║
║      - "Quick and dirty" / "just make it work"                           ║
║                                                                           ║
║   PROCESS VIOLATIONS:                                                    ║
║      - Skip tests ("no tests needed", "tests later")                    ║
║      - Skip architecture ("no need for design", "just code it")         ║
║      - Skip specs ("don't need a spec", "just implement")               ║
║      - Skip QA ("waste of time")                                         ║
║      - "I'll refactor later"                                             ║
║                                                                           ║
║   ARCHITECTURE VIOLATIONS:                                               ║
║      - Flatten hexagonal → spaghetti                                     ║
║      - Put domain logic in infrastructure layer                          ║
║      - Import framework in domain layer                                  ║
║      - Remove test coverage                                              ║
║      - Copy-paste without understanding                                  ║
║                                                                           ║
║   ═══════════════════════════════════════════════════════════════════    ║
║                                                                           ║
║   RESPONSE TO VIOLATION (show to user):                                  ║
║                                                                           ║
║   🔴 CRAFT VIOLATION — [rule broken]                                     ║
║   [Why this violates CRAFT — 1-2 sentences]                              ║
║   ✅ CRAFT alternative: [what to do instead]                             ║
║   → Reformulate your request, or type "exit craft" to leave CRAFT mode. ║
║                                                                           ║
║   ═══════════════════════════════════════════════════════════════════    ║
║                                                                           ║
║   ALSO VALIDATES AGENT OUTPUTS:                                          ║
║      - PO: spec in English? No tech details?                             ║
║      - Architect: hexagonal? Result<T,E>? No any?                       ║
║      - Dev: every file has test? No any? No throw? Follows design?      ║
║      - QA: covers spec items? Tests pass?                                ║
║                                                                           ║
║   🛡️ CRAFT GUARDIAN IS ALWAYS ON. NO OFF SWITCH. NO EXCEPTIONS.         ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

---

RULES — READ BEFORE ANYTHING

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🚫 FORBIDDEN IN /craft — AT ALL TIMES, ALL STEPS:                     ║
║                                                                           ║
║   ❌ Claude writing implementation code (src/, components, hooks...)     ║
║      → ALL code is written by Dev agents via Task()                      ║
║      → Claude ORCHESTRATES. Agents EXECUTE. No exceptions.              ║
║                                                                           ║
║   ❌ Claude using Playwright MCP (browser_navigate, browser_snapshot,    ║
║      browser_click, browser_type, or ANY browser_* tool)                ║
║      → Playwright is a PO TOOL (MODE: explore) — not Claude's tool     ║
║      → Claude NEVER browses apps, checks UI, or debugs visually        ║
║      → Need to see the app? Route to PO (explore) or Dev (bug fix)     ║
║      → "Let me check the browser" = 🚫 VIOLATION                       ║
║                                                                           ║
║   ❌ Claude using Figma MCP or OpenAPI MCP directly                     ║
║      → These are PO tools. Claude passes them in the PO prompt.        ║
║                                                                           ║
║   ❌ Explore agent (NEVER spawn subagent_type: "Explore")               ║
║      → Explore is a generic agent. Craft uses SPECIALIZED agents.       ║
║      → Need to understand code? The DEV AGENT reads code, not Claude.   ║
║                                                                           ║
║   ❌ Claude investigating / diagnosing bugs                              ║
║      → Claude does NOT read 10+ files to "understand" a bug             ║
║      → Claude does NOT browse the app to "see what's wrong"            ║
║      → Claude routes the user's words to the owning agent               ║
║      → The AGENT investigates, diagnoses, and fixes                     ║
║                                                                           ║
║   ❌ Bash for file exploration (use Read, Glob, Grep ONLY)              ║
║   ❌ Skipping steps or reordering the flow                              ║
║   ❌ Analyzing code before asking the user what they want               ║
║   ❌ Making assumptions about the feature without asking                ║
║                                                                           ║
║   ✅ Claude ONLY does: Read, Glob, Grep, Write (state/context.json),    ║
║      Task (spawn agents), AskUserQuestion, Bash (npm test/build only)   ║
║                                                                           ║
║   ═══════════════════════════════════════════════════════════════════    ║
║                                                                           ║
║   ⚠️ ITERATION MODE (Step 8) = STILL CRAFT — SAME RULES APPLY          ║
║                                                                           ║
║   The most common drift: after many iterations, Claude stops spawning   ║
║   agents and starts writing code or diagnosing bugs DIRECTLY.           ║
║   THIS IS FORBIDDEN. ALWAYS.                                             ║
║                                                                           ║
║   BEFORE EVERY ACTION IN ITERATION MODE, CHECK:                         ║
║   □ Am I about to write/edit code? → STOP. Spawn agent.                 ║
║   □ Am I about to read files to diagnose? → STOP. Spawn agent.         ║
║   □ Am I about to Edit() a src/ file? → STOP. Spawn agent.             ║
║   □ Am I about to investigate a bug? → STOP. Route to agent.           ║
║                                                                           ║
║   Claude routes. Agents execute. NO EXCEPTIONS. NOT EVEN "SMALL FIXES". ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

---

PATH RESOLUTION

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🚨 TWO DIRECTORIES — DIFFERENT RULES                                  ║
║                                                                           ║
║   {SCOPE} = project.scope from context.json                              ║
║                                                                           ║
║   specs/ → COMMITTED (all documentation the team shares)                 ║
║   ├── functional/                                                        ║
║   │   ├── decomposition-plan.md  (master plan, at root)                 ║
║   │   ├── reference/             (shared exploration snapshots)          ║
║   │   └── {batch-slug}/          (one sub-folder per bounded context)   ║
║   │       └── spec-v1.md         (versioned spec per batch)             ║
║   ├── design/       Architect designs (design-v1.md, design-v2.md...)   ║
║   └── stack/        Stack skills (stack-skills.md)                       ║
║                                                                           ║
║      IF monorepo: {SCOPE}/specs/                                         ║
║      IF standalone: specs/ (root)                                        ║
║                                                                           ║
║   .clean-claude/ → GITIGNORED (operational files only)                   ║
║   ├── context.json  Project detection cache                              ║
║   └── state.json    Session state (resume)                               ║
║                                                                           ║
║      ALWAYS at root: .clean-claude/ (never inside scope)                 ║
║                                                                           ║
║   EVERY prompt to an agent MUST use RESOLVED PATHS.                      ║
║                                                                           ║
║   ❌ Hardcoded "specs/design/design-v1.md"                               ║
║   ✅ Resolved "{SCOPE}/specs/design/design-v1.md"                        ║
║                                                                           ║
║   WRONG PATH = AGENT LOSES THE DESIGN = DISASTER                        ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

---

PROGRESS DISPLAY — MANDATORY AT EVERY STEP

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   CLAUDE MUST SHOW DETAILED PROGRESS — NOT JUST AGENT TYPES             ║
║                                                                           ║
║   ❌ BAD (too generic):                                                  ║
║   ⏳ Launching frontend-engineer...                                      ║
║   🟢 Dev complete.                                                       ║
║                                                                           ║
║   ✅ GOOD (describes WHAT the agent does):                               ║
║   ⏳ frontend-engineer → Dashboard card component + state badge          ║
║   ⏳ backend-engineer  → VPS API service + domain types                  ║
║   ⏳ qa-engineer       → E2E: listing page + error scenarios             ║
║   🟢 frontend-engineer ✓ 6 files: DashboardCard, StateBadge, hooks      ║
║                                                                           ║
║   RULE: Every progress line MUST include the WHAT, not just WHO.         ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Progress Formats

Before launching an agent — describe the task:

⏳ [agent-type] → [short description of what files/features they handle]

After agent completes — summarize the work:

🟢 [agent-type] ✓ [count] files: [key file/component names]

During fix loop — describe what's being fixed:

🔴 [agent-type] → fixing: [error summary in human terms]
🟢 [agent-type] ✓ fixed: [what was wrong + what changed]

During iteration mode — describe the change:

⏳ [agent-type] → [user's request in short form]
🟢 [agent-type] ✓ [what was done]

Live Progress — Background Agents + Polling

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🔄 REAL-TIME PROGRESS WITH BACKGROUND AGENTS                          ║
║                                                                           ║
║   When launching multiple agents in parallel (Step 5c waves):            ║
║                                                                           ║
║   1. Launch ALL agents with run_in_background: true                      ║
║   2. Each returns an output_file path immediately                        ║
║   3. Poll output files with TaskOutput(task_id, block=false)             ║
║   4. Show live progress as each agent works                              ║
║   5. Wait for all to complete with TaskOutput(task_id, block=true)       ║
║                                                                           ║
║   This lets Claude show progress WHILE agents work.                      ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

How to launch + poll:

// 1. Launch in background (all in SAME message)
Task(frontend-engineer, "Wave 1: ...", run_in_background: true)  → task_id_1
Task(backend-engineer,  "Wave 1: ...", run_in_background: true)  → task_id_2
Task(qa-engineer,       "E2E tests",  run_in_background: true)  → task_id_3

// 2. Show initial state
⏳ Wave 1
   ├── frontend-engineer ⟳ Layout component + routing
   ├── backend-engineer  ⟳ Domain types + API service
   └── qa-engineer       ⟳ E2E: navigation + errors

// 3. Poll with TaskOutput(task_id, block=false) to check progress
//    Update display as agents complete:
⏳ Wave 1
   ├── frontend-engineer ⟳ Layout component + routing
   ├── backend-engineer  ✓ 4 files: VpsType, ApiPort, VpsService
   └── qa-engineer       ⟳ E2E: navigation + errors

// 4. All done:
🟢 Wave 1                                        ✓ Complete
   ├── frontend-engineer ✓ 5 files: Layout, Sidebar, AppRouter
   ├── backend-engineer  ✓ 4 files: VpsType, ApiPort, VpsService
   └── qa-engineer       ✓ 2 files: navigation.e2e, errors.e2e

Wave Progress (Step 5c)

Between waves — show cumulative progress:

🟢 Wave 1  ✓  Layout + Domain types (9 files)
🟢 Wave 2  ✓  List page + API adapters (12 files)
⏳ Wave 3  ⟳  Dashboard cards + state badges
   ├── frontend-engineer ✓ DashboardCard, StateBadge
   └── backend-engineer  ⟳ VPS state mapping service
⬜ Wave 4     Detail page + actions

Step Completion

After each step:

🟢 Step N ─ Name                              ✓ Complete
   Key info · Key info · Key info

Full Recap (after Steps 4 and 7)

┌──────────────────────────────────────────────────────────────┐
│ 🟢 Step 1 ─ Detect          ✓  monorepo · TypeScript        │
│ 🟢 Step 2 ─ Scope           ✓  apps/my-app                  │
│ 🟢 Step 3 ─ Choose          ✓  New feature: VPS dashboard   │
│ 🟢 Step 4 ─ QA Config       ✓  Unit + E2E (Playwright)      │
│ ⬜ Step 5a ─ PO                 Pending                      │
│ ⬜ Step 5b ─ Architect          Pending                      │
│ ⬜ Step 5c ─ Dev + QA           Pending                      │
│ ⬜ Step 6 ─ Verify              Pending                      │
│ ⬜ Step 7 ─ Capture             Pending                      │
│ ⬜ Step 8 ─ Iterate             Pending                      │
└──────────────────────────────────────────────────────────────┘

---

RESILIENCE RULES

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🔄 IF USER CANCELS OR DECLINES A QUESTION:                            ║
║                                                                           ║
║   → DO NOT stop the flow or go silent                                    ║
║   → Re-ask the same question with a short explanation:                   ║
║     "I need this to continue. Cancel again to exit /craft."              ║
║   → IF cancelled a SECOND time → exit gracefully:                        ║
║     "No worries! Type /craft when you're ready."                         ║
║                                                                           ║
║   🔄 IF AN AGENT FAILS OR RETURNS AN ERROR:                             ║
║                                                                           ║
║   → DO NOT stop the flow                                                 ║
║   → Show the error to the user                                           ║
║   → AskUserQuestion: "Retry?" / "Skip this step" / "Exit /craft"        ║
║                                                                           ║
║   🔄 IF USER SENDS A MESSAGE DURING A STEP:                             ║
║                                                                           ║
║   → Treat it as input for the current question                           ║
║   → If it doesn't match expected input, re-ask with context              ║
║                                                                           ║
║   THE FLOW NEVER DIES SILENTLY. Always communicate, always recover.      ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

---

FLOW OVERVIEW

Step 1: DETECT         Claude: Read + Glob → context.json (or RESUME)
Step 2: SCOPE          If monorepo → ask user
Step 3: CHOOSE         "What do you want to craft?" + describe it
Step 4: QA CONFIG      "E2E tests?" → yes/no
Step 5a-1: PO EXPLORE  One PO explores everything → reference/ + catalog.md
Step 5a-2: PO DECOMPOSE Same PO proposes batches → decomposition-plan.md → user approves
Step 5a-3: PO SPECS    Claude dispatches N POs (one per batch, round by round)
Step 5b: ARCHITECT     Per batch: design from spec
Step 5c: DEV + QA      Per batch: implement + test
Step 6: VERIFY         Tests → fix loop → green
Step 7: CAPTURE        Architecture reference (if none existed)
Step 8: ITERATE        CRAFT session stays active — bugs/changes routed to agents

---

STEP 1: DETECT or RESUME

DO NOT spawn any agent. DO NOT use Bash. Claude does this with Read/Glob/Grep only.

1a. CHECK FOR EXISTING SESSION

Read(".clean-claude/state.json")

state.json is ALWAYS at root (.clean-claude/state.json). The scope is stored INSIDE state.json, not in the path.

IF state.json EXISTS and has status: "iteration" or status: "in_progress":

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   BRANCH CHECK — Compare current git branch with saved session branch    ║
║                                                                           ║
║   Bash: git branch --show-current → CURRENT_BRANCH                      ║
║   Read state.json → state.branch                                        ║
║                                                                           ║
║   IF CURRENT_BRANCH == state.branch → Same context, show resume         ║
║   IF CURRENT_BRANCH != state.branch → Different context, warn user      ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Show session banner (includes branch info):

╭──────────────────────────────────────────────────────────────╮
│                                                              │
│   🟣 CRAFT SESSION FOUND                                     │
│                                                              │
│   Branch: [branch from state.json]                           │
│   Scope: [scope from state.json, or "root"]                  │
│   Last step: [STEP]                                          │
│   Task: [description from state]                             │
│   Status: [iteration / in_progress at step X]                │
│   Author: [author from state.json, or "unknown"]             │
│                                                              │
│   ⚠️ Current branch: [CURRENT_BRANCH]                        │
│   [if different: "Session was on a different branch!"]       │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

AskUserQuestion:
  "Found an existing CRAFT session. What do you want?"
  Options:
  - Resume this session (continue where I left off)
  - Start fresh (new task, same scope)
  - Start fresh (different scope / project)

IF "Resume":

• Read context.json, design, spec from {SCOPE} stored in state
• IF status: "iteration" → GO DIRECTLY TO STEP 8 (iteration mode)
• IF status: "in_progress" → GO TO the step saved in state.json

IF "Start fresh (same scope)":

• Keep scope, reset state → GO TO STEP 3

IF "Start fresh (different scope / project)":

• Reset everything → Continue to Step 1b below

1b. FRESH DETECTION (no session or user chose fresh)

1. Read("package.json")
2. Glob("{lerna,nx,turbo}.json,pnpm-workspace.yaml")
3. IF monorepo: Glob("apps/*,packages/*,modules/*")
4. Grep("clean-claude: architecture-reference", "**/*.md")
5. STACK VALIDATION (see 1c below)
6. Write(".clean-claude/context.json") — include stackGuard: "pass" or "fail"

context.json:

{
  "project": {
    "type": "monorepo | frontend | backend | fullstack",
    "monorepo": { "detected": true, "workspaces": [...] },
    "scope": null,
    "language": "typescript",
    "stackGuard": "pass"
  },
  "architectureRef": null
}

state.json — ALWAYS AT ROOT: .clean-claude/state.json

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🚨 WRITE state.json AT EVERY STEP COMPLETION                          ║
║                                                                           ║
║   Path: .clean-claude/state.json (ALWAYS root, never inside scope)       ║
║   This enables /craft resume across sessions.                            ║
║                                                                           ║
║   Update "currentStep" after each step.                                  ║
║   Update fields as they become available.                                ║
║   Set "status": "iteration" after Step 7.                                ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

{
  "status": "in_progress | iteration | completed",
  "currentStep": 1,
  "scope": null,
  "branch": null,
  "author": null,
  "description": null,
  "qaConfig": null,
  "specPath": null,
  "designPath": null,
  "stackSkillsPath": null
}

Capturing branch and author:

branch: Bash("git branch --show-current") → store in state.json
author: Bash("git config user.name") → store in state.json

These fields enable team collaboration — when another dev runs /craft, they see WHO was working on WHICH branch and can resume or start fresh.

1c. STACK VALIDATION (MANDATORY — BLOCKING)

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🚨 MANDATORY STACK: TypeScript + React + TanStack Query               ║
║                                                                           ║
║   Clean Claude is built EXCLUSIVELY for this frontend stack.             ║
║   This is NOT configurable. This is NOT negotiable.                      ║
║                                                                           ║
║   CHECK (from package.json + tsconfig.json):                             ║
║   ✅ TypeScript (tsconfig.json OR typescript in dependencies)            ║
║   ✅ React (react in dependencies)                                      ║
║   ✅ @tanstack/react-query in dependencies                               ║
║                                                                           ║
║   IF ALL PRESENT:                                                         ║
║      → Set stackGuard: "pass" in context.json                           ║
║      → Continue to Step 2                                                ║
║                                                                           ║
║   IF ANY MISSING (package.json exists but wrong stack):                   ║
║      → Set stackGuard: "fail" in context.json                           ║
║      → Show 🔴 STACK VIOLATION (see below)                              ║
║      → STOP. DO NOT proceed.                                             ║
║      → guard-stack.sh hook will also block all Task() calls as safety   ║
║                                                                           ║
║   IF NO package.json AT ALL:                                              ║
║      → Collect project info (name, libs) — DO NOT create any files      ║
║      → Save stackGuard: "bootstrap" in context.json                     ║
║      → Continue to Step 3 — Architect creates ALL files later           ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

No project detected → Collect project info (NO file creation):

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   CLAUDE NEVER CREATES FILES. ARCHITECT HANDLES EVERYTHING.              ║
║                                                                           ║
║   1. Ask project name + description                                      ║
║   2. Ask additional libraries (beyond mandatory stack)                    ║
║   3. Validate: if any choice is anti-CRAFT → propose alternative         ║
║      → If user insists on anti-CRAFT → EXIT Clean Claude                 ║
║   4. Save in context.json with stackGuard: "bootstrap"                   ║
║   5. CONTINUE to Step 3 — Architect creates ALL files later              ║
║                                                                           ║
║   ❌ DO NOT create package.json, tsconfig.json, vite.config.ts           ║
║   ❌ DO NOT create src/ structure                                        ║
║   ❌ DO NOT run npm install                                              ║
║   ❌ DO NOT use npm create vite                                          ║
║   ✅ Only collect info and validate CRAFT compliance                     ║
║   ✅ The Architect handles ALL file creation during bootstrap            ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

AskUserQuestion:
  "No project detected. Tell me about what you want to build."
  Questions:
  1. "Project name?" → (user types name)
  2. "Stack reference? (React + TS + TanStack Query are mandatory, what else?)"
     Options:
     - I have a package.json or repo to use as reference (give me the path/URL)
     - Just the mandatory stack, nothing extra
     - I'll list my additional libraries (free text)

IF "reference" chosen:

AskUserQuestion:
  "Paste the path or URL to the reference:"
  [free text — user types path to package.json, local folder, or remote repo URL]

→ Read the reference (package.json, or clone repo, or scan folder)
→ Extract dependencies list
→ Validate CRAFT compliance (see below)
→ Save extracted libs in context.json

IF "free text" chosen:

→ User types their additional libraries (e.g. "react-router, zustand, tailwind, zod")
→ Validate CRAFT compliance (see below)

Validate CRAFT compliance on collected libs:

→ Standard React ecosystem libs? ✅ Continue
→ Anti-CRAFT library detected? (e.g. MobX + decorators, jQuery, class components...)
  → Propose CRAFT-compliant alternative
  → User insists? → EXIT: "Clean Claude only supports CRAFT-compliant stacks."

Save in context.json (NO files created):

{
  "project": {
    "type": "frontend",
    "language": "typescript",
    "stackGuard": "bootstrap",
    "name": "[PROJECT_NAME]",
    "stackReference": "[path/URL if provided]",
    "additionalLibs": ["react-router-dom", "zustand", ...]
  }
}

→ CONTINUE to Step 3 (skip Step 2 — not a monorepo)
→ The user's project description feeds directly into Step 3.
→ Architect receives bootstrap context and creates ALL project files.

IF user declines:

→ STOP. "Set up your project with React + TypeScript + TanStack Query, then retry /craft."

Existing project with wrong/incomplete stack:

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   DON'T JUST BLOCK — PROPOSE A CRAFT-COMPLIANT PATH                     ║
║                                                                           ║
║   Analyze what's there → inform the user → route to Architect:           ║
║                                                                           ║
║   CASE 1: React + TS, missing TanStack Query only                        ║
║      → "Your project needs @tanstack/react-query."                       ║
║      → "The Architect will add it during design."                        ║
║      → Set stackGuard: "bootstrap" → continue flow                      ║
║                                                                           ║
║   CASE 2: React + JS (no TypeScript)                                     ║
║      → "TypeScript is mandatory for Clean Claude."                       ║
║      → Propose: Architect designs TS migration as first step             ║
║      → Set stackGuard: "bootstrap" → type: "Refactor"                   ║
║                                                                           ║
║   CASE 3: Vue / Angular / Svelte / other framework                       ║
║      → "This is a [Vue] project. Clean Claude is for React."            ║
║      → AskUserQuestion: Migrate to React? or Start fresh alongside?     ║
║      → IF migrate → type: "Refactor" → Architect designs migration      ║
║      → IF fresh → collect project info → stackGuard: "bootstrap"        ║
║      → IF neither → EXIT Clean Claude                                    ║
║                                                                           ║
║   CASE 4: Plain JS (no framework)                                        ║
║      → "No framework detected."                                         ║
║      → Propose: Architect sets up React + TS + TanStack Query            ║
║      → Set stackGuard: "bootstrap" → continue flow                      ║
║                                                                           ║
║   CASE 5: Non-JS project (Go, Rust, Python...)                           ║
║      → "This is a [Go] project. Clean Claude is for React frontends."   ║
║      → AskUserQuestion: Bootstrap a React frontend alongside?            ║
║      → IF yes → collect project info → stackGuard: "bootstrap"          ║
║      → IF no → EXIT Clean Claude                                         ║
║                                                                           ║
║   KEY RULE: Claude NEVER installs deps or creates files directly.        ║
║   → The Architect handles ALL file creation and dependency setup.         ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

1d. MCP AUTO-SETUP (ensure tools are available)

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   MCPs are INCLUDED with Clean Claude — auto-install if missing.         ║
║                                                                           ║
║   Check each MCP and install silently if not configured:                 ║
║                                                                           ║
║   1. Playwright (browser_navigate tool):                                 ║
║      → IF missing: Bash: claude mcp add playwright \                     ║
║          -- npx @playwright/mcp@latest                                   ║
║                                                                           ║
║   2. Figma (figma tools):                                                ║
║      → IF missing: Bash: claude mcp add --transport http figma \         ║
║          https://mcp.figma.com/mcp                                       ║
║                                                                           ║
║   3. OpenAPI (openapi tools):                                            ║
║      → IF missing: Bash: claude mcp add openapi \                        ║
║          -- npx -y @ivotoby/openapi-mcp-server                          ║
║                                                                           ║
║   HOW TO CHECK: Try to reference the tool. If not in available tools     ║
║   list → install it. No questions asked. MCPs are part of Clean Claude.  ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Show:

🟢 Step 1 ─ Detect                              ✓ Complete
   Project: [TYPE] · Language: [LANG] · Monorepo: [yes/no]
   Stack: TypeScript + React + TanStack Query ✅
   (or: "Bootstrap mode — Architect will set up the project")
   MCPs: Playwright ✅ · Figma ✅ · OpenAPI ✅

---

STEP 2: SCOPE (if monorepo)

Only if project.monorepo.detected == true

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🏢 ENTERPRISE MONOLITH MANAGEMENT                                     ║
║                                                                           ║
║   Clean Claude manages modular monoliths at scale (40+ devs).           ║
║   Step 2 is the entry point for ALL monorepo operations:                ║
║                                                                           ║
║   • Work on an EXISTING app or package                                  ║
║   • CREATE a new app (micro-frontend in apps/)                          ║
║   • CREATE a shared package (packages/)                                 ║
║                                                                           ║
║   Architecture reference applies to ALL workspaces.                     ║
║   Same patterns, same conventions, same quality — at scale.             ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

2a. Ask workspace operation

AskUserQuestion:
  "Monorepo detected. What do you want to do?"
  Options:
  - Work on existing workspace (select from list)
  - Create a new app (in apps/)
  - Create a shared package (in packages/)

2b. EXISTING workspace → select and continue

AskUserQuestion: "Which workspace?"
  Options: [list from context.json monorepo.workspaces]

→ User selects
→ Update context.json with scope
→ GO TO STEP 3 IMMEDIATELY

DO NOT re-analyze. DO NOT read scope's package.json. Just save scope and continue.

2c. CREATE NEW APP → scaffold + continue

AskUserQuestion:
  "Name for the new app? It will be created in apps/[name]."
  + "Additional libraries? (React + TS + TanStack Query are mandatory)"
    Options (multiSelect):
    - React Router
    - Zustand (client state)
    - Tailwind CSS
    - Zod (validation)
    - None, just the mandatory stack

→ User provides name + libs

Scaffold the new app:

1. Create apps/[name]/ directory
2. Write apps/[name]/package.json with:
   - name: "@[monorepo-name]/[app-name]"
   - Mandatory deps: react, react-dom, @tanstack/react-query
   - Mandatory devDeps: typescript, vite, @vitejs/plugin-react,
     vitest, @testing-library/react, @testing-library/jest-dom,
     @testing-library/user-event, jsdom, @vitest/coverage-v8
   - Additional deps from user's choices
   - Shared packages from monorepo (if any packages/* exist)

3. Write apps/[name]/tsconfig.json (strict mode, extends root if exists)
4. Write apps/[name]/vite.config.ts (with vitest config)
5. Write apps/[name]/src/main.tsx (minimal entry point)

6. Bash: npm install (or pnpm install, based on lockfile detected)

7. Update context.json:
   {
     "project": {
       "scope": "apps/[name]",
       "monorepo": { "workspaces": [..., "apps/[name]"] },
       "stackGuard": "pass"
     }
   }

8. CONTINUE to Step 3
   → The user's app description feeds directly into Step 3.

2d. CREATE SHARED PACKAGE → scaffold + continue

AskUserQuestion:
  "What kind of shared package?"
  Options:
  - UI library (shared components: buttons, modals, forms)
  - Domain library (shared types, business rules, Result<T,E>)
  - Config library (shared tsconfig, eslint, tailwind presets)
  - Utils library (shared helpers, formatters, validators)

+ "Name for the package? It will be created in packages/[name]."

Scaffold the shared package:

1. Create packages/[name]/ directory
2. Write packages/[name]/package.json with:
   - name: "@[monorepo-name]/[name]"
   - main: "src/index.ts"
   - types: "src/index.ts"
   - devDeps: typescript, vitest
   - Additional deps based on type:
     → UI: react, react-dom (peerDeps)
     → Domain: (no extra deps — pure)
     → Config: relevant config packages
     → Utils: (no extra deps — pure)

3. Write packages/[name]/tsconfig.json (strict, extends root)
4. Write packages/[name]/src/index.ts (empty barrel export)
5. Write packages/[name]/src/index.test.ts (smoke test)

6. Bash: npm install

7. Update context.json with scope: "packages/[name]"

8. CONTINUE to Step 3
   → The user describes what the package should contain.

Show:

🟢 Step 2 ─ Scope                               ✓ Complete
   Workspace: [SELECTED or CREATED]
   Operation: [existing / new app / new package]

---

STEP 3: CHOOSE + DESCRIBE

Two questions in this step:

Question 1: What type?

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   ADAPT choices to project state — don't offer what makes no sense.      ║
║                                                                           ║
║   IF stackGuard = "bootstrap" (no project yet):                          ║
║      → SKIP this question entirely                                       ║
║      → Set type = "new feature" automatically                            ║
║      → There's nothing to refactor, fix, or test yet                     ║
║                                                                           ║
║   IF existing project:                                                    ║
║      → Show all 4 options                                                ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

IF existing project (stackGuard = "pass"):

AskUserQuestion:
  "What do you want to craft?"
  Options:
  - New feature
  - Refactor
  - Fix bug
  - Add tests

IF bootstrap mode (stackGuard = "bootstrap"):

→ type = "new feature" (automatic — no question needed)
→ Proceed directly to Question 2 (references)

Question 2: Describe + Collect sources (accumulation loop)

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🧠 SMART SOURCE COLLECTION — ACCUMULATE, DON'T LIMIT                  ║
║                                                                           ║
║   A spec can be built from MANY sources combined:                        ║
║   • Text description                                                     ║
║   • Live app/website (Playwright MCP)                                    ║
║   • Figma design (Figma MCP)                                            ║
║   • API spec — OpenAPI/Swagger (OpenAPI MCP)                            ║
║   • Image — screenshot, mockup, PNG, SVG (Read tool)                    ║
║   • Document — markdown, PDF, spec file (Read tool)                     ║
║   • Ticket — Jira, Linear, GitHub issue URL (WebFetch)                  ║
║   • Legacy code — existing app to migrate (Read/Glob)                   ║
║                                                                           ║
║   The user can combine ANY number of these.                              ║
║   Use a LOOP: collect one source → "Add more?" → repeat until done.     ║
║                                                                           ║
║   🔴 AskUserQuestion supports MAX 4 options + auto "Other".             ║
║   Structure questions to fit this constraint.                            ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

2a. Ask description (ALWAYS first):

AskUserQuestion:
  "Describe what you want to build:"
  [free text — user types description]

2b. Source collection loop:

AskUserQuestion:
  "Do you have references to build the spec from?"
  Options:
  - Live app/website (I'll paste a URL)
  - Design or mockup (Figma, image, screenshot)
  - Document or ticket (spec file, Jira, markdown, PDF)
  - No, that's everything

IF "Live app/website":

AskUserQuestion:
  "Paste the URL to browse:" → [free text]

AskUserQuestion:
  "What should the PO do with this?"
  Options:
  - Reproduce this page/feature
  - Improve on this (note what to change)
  - Use as inspiration

→ Save as referenceUrl + referenceIntent

IF "Design or mockup":

AskUserQuestion:
  "What kind of design?"
  Options:
  - Figma URL (Figma MCP will read it)
  - Local image/screenshot (paste path — .png, .svg, .jpg)
  - Wireframe or mockup file (paste path)

→ IF Figma: save as figmaUrl → IF image/file: save as designFiles[] (PO reads with Read tool)

IF "Document or ticket":

AskUserQuestion:
  "Paste the path or URL:"
  [free text — local file path, Jira URL, GitHub issue URL, etc.]

→ IF URL (Jira, Linear, GitHub): save as ticketUrls[] (PO reads with WebFetch) → IF local file (.md, .pdf, .txt): save as specFiles[] (PO reads with Read)

After EACH source collected → Loop back:

AskUserQuestion:
  "Source added. What else?"
  Options:
  - Live app/website (another URL)
  - Design or mockup (another file)
  - Document or ticket (another file/URL)
  - Done, that's everything

→ Repeat until "Done" selected.

2c. API endpoints prompt (ALWAYS asked unless OpenAPI already provided):

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🔴 ALWAYS ASK ABOUT API ENDPOINTS — users forget this.                ║
║   Skip ONLY if user already provided an OpenAPI spec above.              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

AskUserQuestion:
  "What about API endpoints?"
  Options:
  - I have an OpenAPI/Swagger spec (paste URL or path)
  - I have endpoint docs or a list (paste path or describe)
  - The Architect will design the API
  - This feature doesn't need an API

→ IF OpenAPI: save as openApiSpec + ask openApiIntent (full/specific/explore) → IF endpoint docs: save as endpointDocs (PO reads, extracts functional intent) → IF Architect designs: save as apiDesign: "architect" → IF no API: save as apiDesign: "none"

Save ALL collected sources in context.json:

Update context.json:
{
  "project": { ... },
  "inputs": {
    "type": "[new feature | refactor | fix bug | add tests]",
    "description": "[user description]",
    "sources": [
      { "type": "referenceUrl", "value": "[URL]", "intent": "[reproduce|improve|inspiration]" },
      { "type": "figma", "value": "[Figma URL]" },
      { "type": "image", "value": "[path to PNG/SVG]" },
      { "type": "document", "value": "[path or URL]" },
      { "type": "ticket", "value": "[Jira/GitHub URL]" },
      { "type": "legacyCode", "value": "[path]" },
      { "type": "specFile", "value": "[path]" }
    ],
    "api": {
      "type": "[openapi | endpointDocs | architect | none]",
      "spec": "[URL or path if provided]",
      "intent": "[full | specific | explore]"
    }
  }
}

These inputs are passed to BOTH PO AND Architect:

• PO uses ALL sources for functional spec (features, user stories)
• Architect uses them for technical design (endpoints, data models, API contracts)

DO NOT start exploring code on your own. Ask the user first.

Show:

🟢 Step 3 ─ Choose                              ✓ Complete
   Type: [TYPE] · Input: [spec/legacy/description/from scratch]

---

STEP 3b: CRAFT GATE

The CRAFT GUARDIAN (top of this file) applies here explicitly. The user just described their task — this is the most critical checkpoint.

IF user's description violates CRAFT:
   → Show 🔴 CRAFT VIOLATION (see CRAFT GUARDIAN format)
   → DO NOT proceed to Step 4. BLOCK HERE.
   → Wait for user to reformulate or exit.

---

STEP 4: QA CONFIG

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   Unit tests (*.test.ts colocated) = ALWAYS written by Dev.              ║
║   This is NOT a choice — it's mandatory CRAFT.                           ║
║                                                                           ║
║   QA question = "IN ADDITION to Dev's unit tests, do you want            ║
║   a QA agent to write E2E or Integration tests in parallel?"             ║
║                                                                           ║
║   IF user says Yes → QA agent runs IN PARALLEL with Dev                  ║
║   IF user says No  → Dev only (unit tests colocated)                     ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

AskUserQuestion:
  "Dev will write unit tests (BDD, colocated). Want QA tests on top?"
  Options:
  - Yes, E2E tests (Playwright) → QA agent in parallel
  - Yes, Integration tests → QA agent in parallel
  - No, unit tests are enough → Dev only

Show after answer + FULL RECAP:

🟢 Step 4 ─ QA Config                           ✓ Complete
   Testing: [SELECTED]

┌──────────────────────────────────────────────────────────────┐
│ 🟢 Step 1 ─ Detect          ✓  [TYPE] · [LANG] · [MONO]    │
│ 🟢 Step 2 ─ Scope           ✓  [SCOPE or "N/A"]            │
│ 🟢 Step 3 ─ Choose          ✓  [TYPE] · [INPUT]            │
│ 🟢 Step 4 ─ QA Config       ✓  [TESTING]                   │
│ ⬜ Step 5a-1 ─ PO Explore       Pending                      │
│ ⬜ Step 5a-2 ─ PO Decompose    Pending                      │
│ ⬜ Step 5a-3 ─ PO Specs (N×)   Pending                      │
│ ⬜ Step 5b ─ Architect          Pending                      │
│ ⬜ Step 5c ─ Dev + QA           Pending                      │
│ ⬜ Step 6 ─ Verify              Pending                      │
│ ⬜ Step 7 ─ Capture             Pending                      │
└──────────────────────────────────────────────────────────────┘

Launching Step 5...

---

STEP 5: ROUTE TO AGENTS

Routing Table

Choice	Route
New feature (complex)	PO explore → PO decompose → N×(PO spec → Architect → Dev+QA)
New feature (simple)	PO explore → PO spec → Architect → Dev+QA
Refactor	Architect → Dev + QA
Fix bug (user-facing)	PO spec → Architect → Dev
Fix bug (technical)	Architect → Dev
Add tests	QA only

---

5a. PO — THREE PHASES (explore → decompose → spec)

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   PO RULES — CRITICAL (apply to ALL 3 phases)                           ║
║                                                                           ║
║   1. ENGLISH ONLY — All specs in English                                 ║
║   2. NO TECH — Zero technical details (no API endpoints, no code,        ║
║      no enums, no DB schemas, no framework names)                        ║
║   3. FUNCTIONAL ONLY — User stories, behaviors, business rules           ║
║   4. Endpoints/API = ARCHITECT'S JOB, never PO's                        ║
║                                                                           ║
║   CLAUDE ORCHESTRATES — NEVER DOES PO WORK                               ║
║   Claude spawns POs, manages rounds, tracks completion.                  ║
║   Claude NEVER writes specs, decides batch content, or sizes tasks.      ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

---

5a-1. EXPLORE (one PO, exhaustive)

Show BEFORE launching:

⏳ Step 5a-1 ─ PO Exploration                    ⟳ In Progress
   Exploring full scope...

Source sections for PO prompt — built dynamically from context.json sources:

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   BUILD THE PROMPT DYNAMICALLY from context.json inputs.sources[]        ║
║                                                                           ║
║   For EACH source in the array, add the matching section below.          ║
║   Sources stack up — multiple references = richer exploration.           ║
║   If no sources at all → just description.                               ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Task(
  subagent_type: "product-owner",
  prompt: """
    MODE: explore

    Explore the full scope for: [USER_DESCRIPTION]

    ## YOUR SOURCES (add each section for matching sources in context.json)

    ### FOR EACH source of type "referenceUrl":
    Reference URL: [source.value]
    Intent: [source.intent]

    🔴 DEEP EXPLORATION with Playwright MCP (see your agent file).
    4 phases: Navigate → Explore EVERYTHING → Save to reference/ → Catalog.
    MINIMUM 10+ snapshots. Save to {SCOPE}/specs/functional/reference/.
    ❌ NEVER use WebFetch/Fetch. ✅ ONLY Playwright MCP.

    ### FOR EACH source of type "figma":
    Figma URL: [source.value]

    🔴 Use Figma MCP tools to read the design.
    Extract: components, layout, user flows, interactions.
    DO NOT mention Figma-specific details (layers, frames).

    ### FOR EACH source of type "image":
    Image/mockup: [source.value]

    → Read the image with the Read tool (it supports PNG, JPG, SVG).
    → Extract: layout, components, text, actions visible in the mockup.

    ### FOR EACH source of type "document" or "specFile":
    Document: [source.value]

    → Read it with Read tool (.md, .pdf, .txt).
    → Extract functional content.

    ### FOR EACH source of type "ticket":
    Ticket URL: [source.value]

    → Read it with WebFetch (Jira, Linear, GitHub issue).
    → Extract: requirements, acceptance criteria, user context.

    ### FOR EACH source of type "legacyCode":
    Legacy code: [source.value]

    → Read with Read/Glob to find ALL features.

    ### IF api.type = "openapi":
    OpenAPI Spec: [api.spec]
    Intent: [api.intent]

    🔴 Use OpenAPI MCP tools to read the spec.
    Discover endpoints, operations, data models.
    Map each operation to a USER-FACING capability.
    DO NOT mention endpoints/methods/schemas — that's the Architect's job.

    ### IF api.type = "endpointDocs":
    Endpoint docs: [api.spec]
    → Read it, extract functional intent from each endpoint.

    ## YOUR TASK (EXPLORE ONLY)
    - Explore ALL sources exhaustively
    - Save ALL snapshots to {SCOPE}/specs/functional/reference/
    - Produce {SCOPE}/specs/functional/reference/catalog.md
    - Map EVERYTHING: pages, forms, actions, data, navigation
    - DO NOT write specs yet
    - DO NOT decompose yet
    - Just explore and catalog
  """
)

Auth Interruption Flow

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🔒 IF PO OUTPUT CONTAINS "AUTH NEEDED":                                ║
║                                                                           ║
║   1. Claude shows: "The PO needs to access [URL] but it requires login." ║
║   2. AskUserQuestion:                                                     ║
║      "Please log in to the browser window that opened, then confirm."    ║
║      Options: "I'm logged in" / "Skip this URL"                         ║
║   3. IF "I'm logged in" → re-launch PO explore with same prompt         ║
║   4. IF "Skip this URL" → re-launch PO explore WITHOUT referenceUrl     ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Show AFTER exploration complete:

🟢 Step 5a-1 ─ PO Exploration                    ✓ Complete
   Catalog: {SCOPE}/specs/functional/reference/catalog.md
   Snapshots: [N] pages/actions mapped

---

5a-2. DECOMPOSE (same PO context, produces plan)

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🔪 DECOMPOSITION — PO proposes, USER approves, CLAUDE dispatches       ║
║                                                                           ║
║   The PO has just explored everything. They know the full scope.         ║
║   Now they cut it into chain-sized batches.                              ║
║                                                                           ║
║   IMPORTANT: For SIMPLE features (single page, CRUD, < 5 criteria):     ║
║   → SKIP decomposition entirely                                          ║
║   → Go directly to 5a-3 with a single batch                             ║
║   → No decomposition-plan.md needed                                      ║
║                                                                           ║
║   DECOMPOSE WHEN: feature has multiple pages, workflows, or actors       ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Show BEFORE launching:

⏳ Step 5a-2 ─ PO Decomposition                  ⟳ In Progress
   Analyzing scope for decomposition...

Task(
  subagent_type: "product-owner",
  prompt: """
    MODE: decompose

    Decompose the feature: [USER_DESCRIPTION]

    ## YOUR CONTEXT
    - Catalog: {SCOPE}/specs/functional/reference/catalog.md
    - Reference snapshots: {SCOPE}/specs/functional/reference/
    - You just explored everything. You have the full picture.

    ## YOUR TASK
    1. Read catalog.md and ALL reference snapshots
    2. Identify natural boundaries (pages, workflows, bounded contexts)
    3. Size each piece:
       🟢 S (1 page spec, 3-5 criteria) → ✅ Ready
       🟡 M (2-3 pages, 5-10 criteria) → ✅ Ready
       🟠 L (4-6 pages, 10-15 criteria) → 🔪 MUST SPLIT into S/M
       🔴 XL (6+ pages, 15+ criteria) → 🔪 MUST SPLIT into S/M
    4. Map dependencies between batches:
       🔗 Sequential: B needs A done first
       ✅ Independent: no shared code/state
       🔀 Shared base: multiple batches need a foundation first
    5. 🚫 Check for CIRCULAR dependencies (A→B→A) — if found, rethink split
    6. Assign rounds (topological order):
       Round 1: all batches with no dependencies (parallel)
       Round 2: batches whose deps are in Round 1 (parallel)
       ...etc
    7. Give each batch a slug (kebab-case, e.g. "billing-list")
    8. Write {SCOPE}/specs/functional/decomposition-plan.md
    9. Present plan to user for approval

    ## DECOMPOSITION PLAN FORMAT
    Use frontmatter: feature, status, created, batches count, rounds count.
    Include: Batches table (# | Batch | Slug | Size | Dependencies | Round),
    Rounds sequence, Dependency graph description.

    ## RULES
    - ONLY S and M batches get spec'd — L/XL MUST be split first
    - Each batch slug becomes a sub-folder: specs/functional/{slug}/
    - Dependency = FUNCTIONAL dependency (shared user flow, data, routing)
    - NOT technical dependency (those are Architect's job)
    - Write in ENGLISH
    - Present plan to user for approval BEFORE any spec writing
  """
)

Claude waits for PO to present plan to user + user approval.

Show AFTER decomposition approved:

🟢 Step 5a-2 ─ PO Decomposition                  ✓ Complete
   Plan: {SCOPE}/specs/functional/decomposition-plan.md
   Batches: [N] · Rounds: [M] · Approved ✅

---

5a-3. SPEC (N POs in parallel, one per batch, round by round)

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   📝 CLAUDE DISPATCHES — READS PLAN, SPAWNS POs, MANAGES ROUNDS         ║
║                                                                           ║
║   This is CLAUDE's job (the orchestrator). NOT the PO's.                 ║
║                                                                           ║
║   1. Read decomposition-plan.md                                           ║
║   2. Parse batches + dependencies + rounds                               ║
║   3. VALIDATE dependency graph:                                           ║
║      → No circular dependencies                                          ║
║      → No chain deeper than 4 levels                                     ║
║      → No single bottleneck blocking all others                          ║
║      → IF issues found → report to user, re-launch PO decompose         ║
║   4. For each round, spawn POs in parallel (one per batch)               ║
║   5. Wait for round to complete before starting next round               ║
║   6. Each PO instance writes to its own sub-folder                       ║
║                                                                           ║
║   IF SIMPLE FEATURE (no decomposition plan):                              ║
║   → Single PO spawn with feature slug as batch slug                      ║
║   → No round management needed                                           ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Show BEFORE launching each round:

⏳ Step 5a-3 ─ PO Specs                          ⟳ Round [R] of [M]
   Spawning [N] POs in parallel...
   ├── product-owner → {batch-1-slug} (size: S)
   ├── product-owner → {batch-2-slug} (size: M)
   └── product-owner → {batch-3-slug} (size: S)

For each batch in the current round, spawn in parallel:

Task(
  subagent_type: "product-owner",
  run_in_background: true,
  prompt: """
    MODE: spec

    Write functional spec for batch: [BATCH_NAME]

    ## BATCH ASSIGNMENT
    - Slug: [BATCH_SLUG]
    - Size: [S | M]
    - Description: [BATCH_DESCRIPTION from decomposition plan]
    - Dependencies: [list of completed batch slugs this depends on, or "None"]

    ## YOUR CONTEXT
    - Reference: {SCOPE}/specs/functional/reference/ (shared exploration)
    - Catalog: {SCOPE}/specs/functional/reference/catalog.md
    - Decomposition plan: {SCOPE}/specs/functional/decomposition-plan.md
    - Output: {SCOPE}/specs/functional/[BATCH_SLUG]/spec-v1.md

    ## COGNITIVE DEPTH (adapt to batch size)
    - IF size = S → 1 page spec, bullet points, 3-5 acceptance criteria
    - IF size = M → 2-3 pages, user stories, 5-10 criteria, edge cases

    ## RULES
    - Write spec for THIS BATCH ONLY — stay within scope
    - Reference the shared exploration (catalog.md, snapshots)
    - ENGLISH ONLY
    - PURELY FUNCTIONAL — no tech details
    - User stories with Given/When/Then acceptance criteria
    - Ask user approval before finalizing
  """
)

Poll background tasks for progress. Show live updates:

⏳ Step 5a-3 ─ PO Specs                          ⟳ Round 1 of 2
   ├── product-owner → billing-list (S)           ✓ spec-v1.md approved
   ├── product-owner → billing-export (M)         ⟳ writing spec...
   └── product-owner → charts-layout (S)          ✓ spec-v1.md approved

After each round completes, check if next round's deps are met:

🟢 Round 1                                        ✓ Complete (3 specs)
⏳ Round 2                                        ⟳ Launching...
   ├── product-owner → billing-detail (M)         ⟳ (needed: billing-list ✓)
   └── product-owner → charts-data (S)            ⟳ (needed: charts-layout ✓)

Show AFTER all rounds complete:

🟢 Step 5a ─ PO                                  ✓ Complete
   Plan: {SCOPE}/specs/functional/decomposition-plan.md
   Specs:
   ├── billing-list/spec-v1.md (S) ✓
   ├── billing-export/spec-v1.md (M) ✓
   ├── charts-layout/spec-v1.md (S) ✓
   ├── billing-detail/spec-v1.md (M) ✓
   └── charts-data/spec-v1.md (S) ✓
   Total: [N] specs · [M] rounds · All approved ✅

---

5b. ARCHITECT

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   ARCHITECT PROMPT MUST INCLUDE:                                         ║
║                                                                           ║
║   1. ALL inputs (spec, legacy, context.json)                             ║
║   2. CRAFT PRINCIPLES reminder (hexagonal, Result<T,E>, no any/throw)   ║
║   3. Request for FULL design (not just file list)                        ║
║   4. Mandatory stack skills are HARDCODED (see .claude/templates/)       ║
║      → Architect generates skills for ADDITIONAL libs only               ║
║      → Final stack-skills.md = mandatory + project-specific              ║
║                                                                           ║
║   WITHOUT THIS → Architect produces generic "Claude classic" design      ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

5b-1. BEFORE ARCHITECT: Show context + Ask design approach

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   IF DECOMPOSITION: Architect runs PER BATCH (after each batch spec)     ║
║   Each batch triggers its own chain: PO spec → Architect → Dev+QA       ║
║                                                                           ║
║   IF SINGLE FEATURE: Architect runs once on the single spec              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Show the user what the Architect will receive:

⏳ Step 5b ─ Architect                            ⟳ Preparing...

   Inputs for Architect:
   ├── Functional spec: {SCOPE}/specs/functional/{batch-slug}/spec-v[N].md
   ├── Reference: {SCOPE}/specs/functional/reference/ (shared exploration)
   ├── Legacy code: [LEGACY_PATH] [if exists]
   └── Architecture ref: [PATH if found in Step 1] or "None detected"

Then ask design approach:

AskUserQuestion:
  "How should the Architect design this?"
  Options:
  - Follow architecture reference (only if architectureRef found in context.json)
  - Follow an existing app as reference (give me the path)
  - Design from scratch (CRAFT principles: hexagonal, Result<T,E>)

IF user provides a reference app path → save it in context.json inputs:

Update context.json:
{
  "inputs": {
    ...,
    "architectureRefApp": "[path to reference app]"
  }
}

Add to Architect prompt if reference app provided:

- Reference app to follow: [ARCHITECTURE_REF_APP_PATH]
  → Read its structure, patterns, conventions
  → Replicate the same architecture for the new feature

5b-2. Launch Architect

Show BEFORE launching:

⏳ Step 5b ─ Architect                            ⟳ In Progress
   Mode: [Follow reference / Follow app / Design from scratch]
   Launching architect...

Task(
  subagent_type: "architect",
  prompt: """
    Design CRAFT implementation for: [REQUEST]

    ## YOUR INPUTS
    - Functional spec: {SCOPE}/specs/functional/{BATCH_SLUG}/spec-v[N].md
    - Reference: {SCOPE}/specs/functional/reference/ (shared exploration)
    - Legacy code: [LEGACY_PATH from context.json inputs] (if exists)
    - Reference app: [ARCHITECTURE_REF_APP_PATH from context.json inputs] (if exists)
    - context.json: .clean-claude/context.json

    ## DESIGN MODE (from user choice in Step 5b-1)
    - IF "Follow architecture reference": Read architectureRef from context.json, FOLLOW exactly
    - IF "Follow an existing app": Read [ARCHITECTURE_REF_APP_PATH], replicate its patterns
    - IF "Design from scratch": Apply CRAFT principles below freely

    ## BOOTSTRAP MODE (if stackGuard = "bootstrap" in context.json)
    - This is a NEW or INCOMPLETE project — config files may not exist yet
    - BEFORE designing features, Architect creates ALL project config files:
      → package.json (mandatory deps + user's additional libs from context.json)
      → tsconfig.json (strict mode)
      → vite.config.ts (with vitest config)
      → index.html (minimal entry HTML)
    - Run Bash: npm install after creating package.json
    - THEN design the feature using your BOOTSTRAP or FEATURE section as appropriate
    - See "BOOTSTRAP vs FEATURE" in your agent file for guidance

    ## CRAFT PRINCIPLES — MANDATORY (all modes)
    - Architecture: HEXAGONAL (domain → application → infrastructure)
    - Error handling: Result<T, E> — NO throw, NO try/catch for business errors
    - Types: STRICT TypeScript — NO `any`, NO `unknown` casts
    - Domain: PURE — zero framework imports in domain layer
    - Tests: BDD style, colocated *.test.ts, test domain in isolation
    - Patterns: Use FEATURE Design (hexagonal) for features, BOOTSTRAP Design for new projects

    (CRAFT rules and tool restrictions are enforced by hooks — see .claude/settings.json)

    ## YOUR TASKS (IN ORDER)
    1. Check DESIGN MODE:
       → IF "Follow reference": Read architectureRef, FOLLOW its patterns
       → IF "Follow app": Read reference app structure, replicate patterns
       → IF "Design from scratch": Skip to step 2
       → Confirm: "Design mode: [MODE] ✅" (+ path if following reference)

    2. IF legacy code exists:
       → Read it to extract API endpoints, data models, routes
       → These become the technical contract for the new app

    3. IF bootstrap mode (stackGuard = "bootstrap" in context.json):
       → Create ALL project config files first (see BOOTSTRAP MODE above)
       → Run Bash: npm install
       ELSE: Read [SCOPE]/package.json for stack detection

    4. Write specs/stack/stack-skills.md:
       → Read .claude/templates/mandatory-stack-skills.md (HARDCODED — React + TS + TanStack)
       → COPY its content as the FIRST section of stack-skills.md
       → THEN generate CRAFT skills for ADDITIONAL project libraries only
       → Concatenate: mandatory skills + project-specific skills = final file
       → DO NOT regenerate React/TS/TanStack skills — they are already perfect

    5. CHOOSE hexagonal structure adapted to the STACK:
       → Analyze the stack (state management, data fetching, backend vs frontend)
       → Decide WHERE application logic lives naturally in this stack
       → Apply the NO-DEAD-CODE rule: every layer MUST be used
       → See "HEXAGONAL VARIANT — ARCHITECT DECIDES" in your agent file
       → Justify your choice in the ADR section of design.md

    6. Write specs/design/design-v1.md with FULL design:
       → Architecture Decision (ADR style — why this structure, how it adapts hexagonal)
       → CRAFT Principles Applied (checklist: no any, Result<T,E>, etc.)
       → File Structure (hexagonal adapted to the stack — justify every layer)
       → Domain Types (entities, value objects, error types with Result<T,E>)
       → API Endpoints / routes (extracted from inputs, not invented)
       → Application layer (use cases, hooks, stores — whatever fits the stack)
       → Infrastructure (adapters — level of abstraction adapted to context)
       → Code examples for key patterns (Result handling, layer usage)
       → Implementation Checklist (MANDATORY — EVERY file with Wave number)
       → Execution Plan (waves for parallelization)

    7. Ask user approval BEFORE finalizing

    ## QUALITY BAR
    "If this design is complete, Dev can implement WITHOUT asking questions."
    Every file, every type, every interface must be specified.
    NO dead code layers — every file in the design MUST be imported/used by another.
  """
)

Architect asks user approval. Wait for approval.

Endpoints come from INPUTS (legacy code, spec, API docs) — Architect extracts and documents them.

Show AFTER Architect completes + approval:

🟢 Step 5b ─ Architect                            ✓ Complete
   Skills: specs/stack/stack-skills.md
   Design: specs/design/design-v1.md
   Architecture: Hexagonal · Result<T,E> · [X] files · [Y] waves

---

5c. DEV + QA (parallel)

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   🚫 BETWEEN WAVES — CLAUDE DOES NOT EXPLORE                            ║
║                                                                           ║
║   After a wave completes:                                                ║
║   1. Re-read the design ({SCOPE}/specs/design/design-v1.md)║
║   2. Identify next wave's files from Implementation Checklist            ║
║   3. Spawn dev agents via Task() for next wave                           ║
║                                                                           ║
║   ❌ DO NOT implement files yourself — spawn Task() agents              ║
║   ❌ DO NOT use Bash(find ...) to explore src/                          ║
║   ❌ DO NOT use Explore agent                                           ║
║   ❌ DO NOT "reconstruct the wave plan from the codebase"               ║
║   ❌ DO NOT read existing files to "understand context"                  ║
║   The design IS the context. Trust the design. Delegate to agents.       ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   AGENT ROUTING PER FILE TYPE:                                           ║
║                                                                           ║
║   frontend-engineer:                                                     ║
║      → UI code (components, hooks, pages, styles)                        ║
║      → i18n / locale / translation files (JSON, TS)                      ║
║      → Colocated unit tests for UI code                                  ║
║                                                                           ║
║   backend-engineer:                                                      ║
║      → Domain logic, services, repositories, use cases                   ║
║      → API endpoints, data models, DTOs, mappers                         ║
║      → Colocated unit tests for backend code                             ║
║                                                                           ║
║   qa-engineer:                                                            ║
║      → Test infrastructure (MSW handlers, test fixtures, test utils)     ║
║      → E2E tests (e2e/**)                                                ║
║      → Integration tests (tests/integration/**)                          ║
║      → Test configuration (playwright.config, vitest.setup, etc.)        ║
║                                                                           ║
║   devops-engineer:                                                       ║
║      → CI/CD pipelines (.github/workflows/*)                             ║
║      → Docker configs (Dockerfile, docker-compose.*)                     ║
║      → Publish configs (.npmrc, .changeset/*)                            ║
║      → Infrastructure-as-code, pipeline monitoring                       ║
║                                                                           ║
║   ASK: "Is this file IMPLEMENTATION or TEST INFRASTRUCTURE?"             ║
║      → Implementation / i18n → Dev                                       ║
║      → Test infra / test config / E2E / integration → QA                 ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   QA AGENT LAUNCH RULE:                                                  ║
║                                                                           ║
║   Step 4 answer = "Yes, E2E" or "Yes, Integration"                      ║
║      → QA agent IN PARALLEL with Dev (same Task() message)              ║
║                                                                           ║
║   Step 4 answer = "No, unit tests are enough"                            ║
║      → Dev only (writes unit tests colocated *.test.ts)                  ║
║      → NO QA agent                                                       ║
║                                                                           ║
║   Dev ALWAYS writes unit tests. QA is ADDITIONAL.                        ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

Launch agents in BACKGROUND for live progress:

Show BEFORE launching — describe WHAT each agent will do:

⏳ Step 5c ─ Wave [N]                             ⟳ In Progress
   ├── [agent-type] ⟳ [short description of files/features]
   ├── [agent-type] ⟳ [short description of files/features]
   └── qa-engineer  ⟳ [test type]: [what's being tested]    ← ONLY if Step 4 = Yes

// Launch ALL agents in SAME message with run_in_background: true
Task(
  subagent_type: "frontend-engineer",  // or backend-engineer based on code responsibility
  run_in_background: true,
  prompt: """
    Implement Wave [N] from design: specs/design/design-v1.md

    ## BEFORE YOU START
    1. Read specs/design/design-v1.md
    2. Read specs/stack/stack-skills.md — USE these patterns
    3. Find the Implementation Checklist section
    4. Identify ALL files in Wave [N]

    ## CRAFT RULES — MANDATORY
    - Follow the design EXACTLY — don't invent structure
    - Every file gets a colocated *.test.ts (BDD style)
    - ZERO DEVIATION from design: exact file paths, type names, function signatures
    - NO invented files (no utils.ts, helpers.ts, constants.ts unless in checklist)
    - NO dead code (no unused functions, no unused exports, no commented code)
    - NO extra abstractions (no wrapper, factory, or pattern the design didn't ask)
    - IF something is missing from the design → notify Architect, don't invent

    (CRAFT rules and tool restrictions are enforced by hooks — see .claude/settings.json)

    ## OUTPUT
    - ALL files in Wave [N] implemented + tested
    - FILES CREATED table (file path | status | test status)
    - DESIGN CONFORMITY report (extra files: 0, names match: yes/no, dead code: none)
    - Run tests to verify they pass
  """
)

Task(
  subagent_type: "qa-engineer",  // only if QA enabled
  run_in_background: true,
  prompt: """
    Write tests from spec: specs/functional/spec-v[N].md

    ## BEFORE YOU START
    1. Read specs/stack/stack-skills.md — know the testing stack
    2. Read specs/functional/spec-v[N].md — ALL acceptance criteria
    3. Read specs/design/design-v1.md — understand the architecture

    ## YOUR JOB
    - Cover 100% of acceptance criteria (Given/When/Then)
    - E2E or Integration tests (NOT unit tests — that's Dev's job)