Menu
Craft something. Claude orchestrates, agents execute.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
Start a Clean Claude agent with optional reactive links. Examples: /agent frontend-engineer, /agent frontend-engineer --link qa-engineer, /agent architect --link frontend-engineer,qa-engineer
Auto-repair with smart routing: test failures → Dev, type errors → Architect, spec gaps → PO. Routes each problem to the right expert.
Re-run stack detection and skill generation. Use when stack evolved or on first run.
Set up the Clean Claude Reactive System in the current project. Configures hooks, shared state, and scripts for the multi-agent feedback loop
Bootstrap a new frontend project with craft principles: React + Vite + TypeScript + Vitest + clean architecture
Add specialized craft skills to agents. Default craft principles always active. Everything MUST respect the craft philosophy.
| name | craft |
| description | Craft something. Claude orchestrates, agents execute. |
| context | conversation |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion |
╭──────────────────────────────────────────────────────────────╮
│ │
│ 🟣 C L E A N C L A U D E │
│ │
│ ══════════════════════════════════════════════════════ │
│ CRAFT MODE │
│ ══════════════════════════════════════════════════════ │
│ │
╰──────────────────────────────────────────────────────────────╯
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🛡️ 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. ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🚫 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". ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🚨 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 ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 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. ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
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]
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🔄 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
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
After each step:
🟢 Step N ─ Name ✓ Complete
Key info · Key info · Key info
┌──────────────────────────────────────────────────────────────┐
│ 🟢 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 │
└──────────────────────────────────────────────────────────────┘
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🔄 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. ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
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
DO NOT spawn any agent. DO NOT use Bash. Claude does this with Read/Glob/Grep only.
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":
status: "iteration" → GO DIRECTLY TO STEP 8 (iteration mode)status: "in_progress" → GO TO the step saved in state.jsonIF "Start fresh (same scope)":
IF "Start fresh (different scope / project)":
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.
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🚨 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. ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 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 ✅
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. ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
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/)
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.
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.
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]
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:
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]
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.
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 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...
| 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 |
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 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. ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
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
"""
)
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🔒 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
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🔪 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 ✅
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 📝 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 ✅
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 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 ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 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
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
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🚫 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)