buildanything 1.2.1 → 1.5.0

package/commands/build.md

@@ -1,464 +1,460 @@
 ---
-description: "Full product build pipeline: takes a brainstormed idea through architecture, planning, implementation, testing, and hardening using coordinated agent teams — outputs working, tested, reviewed code"
-argument-hint: "Path to brainstorming doc or describe what we're building"
+description: "Full product build pipeline — orchestrates specialist agents through brainstorming, research, architecture, implementation, testing, hardening, and shipping"
+argument-hint: "Describe what to build, or path to a design doc. --autonomous for unattended mode. --resume to continue a previous build."
 ---
 
-# /build — buildanything pipeline
+<HARD-GATE>
+YOU ARE AN ORCHESTRATOR. YOU COORDINATE AGENTS. YOU DO NOT WRITE CODE.
 
-## PROCESS INTEGRITY — READ THIS FIRST
+Every step below tells you to call the Agent tool. DO IT. Do not role-play as the agent. Do not write implementation code yourself. Do not skip the Agent tool call "because it's faster." If you are typing code instead of calling the Agent tool, STOP — you are violating this process.
 
-<HARD-GATE>
-You are an ORCHESTRATOR. You coordinate specialist agents. You do NOT write implementation code yourself.
+"Launch an agent" = call the Agent tool (the actual tool in your toolbar, the one that spawns a subprocess).
 
-If you are about to write implementation code directly — STOP. That is a violation of this process. Dispatch to a specialist agent instead.
+For implementation agents, set mode: "bypassPermissions".
+For parallel work, put multiple Agent tool calls in ONE message.
 
-This gate is non-negotiable. No exceptions. No "just this one quick fix." No "it's faster if I do it myself."
+Exception: Brainstorming (Phase 1, Step 1.1) is a direct conversation with the user — you ask questions and process answers yourself. This is the ONE phase where you work directly, not through agents.
 </HARD-GATE>
 
-**Resuming after context compaction?** If your context was recently compacted or you are continuing a previous session:
-1. Read `docs/plans/.build-state.md` to recover your phase, step, and progress
-2. Re-read THIS file completely — you are reading it now
-3. Check the TodoWrite list for task progress
-4. Resume from the saved state, not from scratch
-5. Do NOT skip ahead or fall back to default coding behavior
-
-### Rationalization Prevention
-
-If you catch yourself thinking any of these, you are drifting from the process:
-
-| Thought | Reality |
-|---------|---------|
-| "It's faster if I just write this myself" | You are an orchestrator. Dispatch to an agent. Speed is not your job — coordination is. |
-| "This is too small for a subagent" | Every implementation task goes through an agent. No exceptions. Small tasks still need the Dev→QA loop. |
-| "I'll skip the code review for this one" | Every task gets reviewed. The code-reviewer agent exists for a reason. |
-| "The quality gate is obvious, I'll just proceed" | Present it to the user. Quality gates require explicit user approval. |
-| "I already know what to build, I'll skip architecture" | Phase 1 is mandatory. The architecture step catches design mistakes before they become code. |
-| "Tests aren't needed for this part" | Every task has acceptance criteria and tests. The Evidence Collector verifies. |
-| "I'll clean this up later" | The Harden phase (Phase 4) exists for this. Don't skip steps — follow the process. |
-| "Context was compacted, I'll just keep coding" | STOP. Re-read this file. Check .build-state.md. Reload the process. |
-
-### Process Flowchart
-
-```dot
-digraph build_pipeline {
-  rankdir=TB;
-  node [shape=box];
-
-  start [label="User invokes /build" shape=ellipse];
-  p1 [label="Phase 1: Architecture & Planning\n(Backend Architect + UX Architect +\nSecurity Engineer + code-architect +\nSprint Prioritizer + Senior PM)"];
-  gate1 [label="Quality Gate 1\nUser approves architecture?" shape=diamond];
-  p2 [label="Phase 2: Foundation\n(DevOps Automator + Frontend Dev\nor Backend Architect)"];
-  gate2 [label="Quality Gate 2\nBuilds? Tests pass? Lint clean?" shape=diamond];
-  p3 [label="Phase 3: Build — Dev↔QA Loops\nFor EACH task:\nAgent implements → Evidence Collector\nverifies → code-reviewer reviews"];
-  retry [label="Retry (max 3)\nFeedback to dev agent" shape=box];
-  escalate [label="Escalate to user\nafter 3 failures" shape=box];
-  p4 [label="Phase 4: Harden\n(API Tester + Perf Benchmarker +\nAccessibility Auditor + Security Engineer +\ncode-simplifier + Reality Checker)"];
-  gate4 [label="Quality Gate 4\nReality Checker: PRODUCTION READY?" shape=diamond];
-  p5 [label="Phase 5: Ship\n(Technical Writer + final commit)"];
-  done [label="BUILD COMPLETE" shape=ellipse];
-
-  start -> p1;
-  p1 -> gate1;
-  gate1 -> p2 [label="approved"];
-  gate1 -> p1 [label="changes requested"];
-  p2 -> gate2;
-  gate2 -> p3 [label="pass"];
-  gate2 -> p2 [label="fix"];
-  p3 -> retry [label="task fails"];
-  retry -> p3 [label="< 3 retries"];
-  retry -> escalate [label="3 retries"];
-  p3 -> p4 [label="all tasks complete"];
-  p4 -> gate4;
-  gate4 -> p5 [label="PRODUCTION READY"];
-  gate4 -> p4 [label="NEEDS WORK"];
-  p5 -> done;
-}
-```
+### Orchestrator Discipline
 
----
+Your context window is precious. Protect it.
 
-You are the **Agents Orchestrator** running the buildanything pipeline. Your job is to take a brainstormed idea and build it into a working, tested, production-quality product — coordinating specialist agents the way a VP of Engineering at Meta or Google would run a product team.
+**You are a DISPATCHER, not a DOER.** Your job is: read state → decide next step → compose agent prompt → dispatch → process result → decide next step.
 
-**This is NOT brainstorming. Brainstorming is done. This is execution.**
+**Two types of agents — handle their results differently:**
 
-Input: $ARGUMENTS
+| Agent Type | Examples | What you keep |
+|-----------|----------|---------------|
+| **Research/analysis** | Market research, tech feasibility, architecture design, audits, measurement | **Full output** — their response IS the deliverable. You need it to synthesize, compare, and make decisions. Save to `docs/plans/` when applicable. |
+| **Implementation** | Code writing, fixes, cleanup, verification, scaffolding | **Summary only** — their work product lives in the codebase. Keep: what was done, files changed, test results, pass/fail. Discard: code snippets, full build logs, lint output. |
 
-## Operating Principles
+**After implementation agents return:**
+1. Extract: what was built, files changed, test pass/fail, any blockers
+2. Record in `docs/plans/.build-state.md` under the current phase
+3. The code is in the repo — you don't need it in your context
 
-- **You are an orchestrator.** You dispatch work to specialist agents. You do NOT write implementation code yourself. Your job is coordination, synthesis, and quality enforcement.
-- **Phase gates are mandatory.** Do not advance to the next phase until the current phase passes its quality gate. Present phase output to the user for approval before advancing.
-- **Dev↔QA loops are mandatory.** Every implementation task gets tested. Failed tasks loop back to the developer agent with specific feedback. Max 3 retries per task before escalation to the user.
-- **Fresh agents per task.** Each task gets a fresh subagent to prevent context pollution from previous tasks. Do not reuse a subagent across multiple implementation tasks.
-- **Parallelism within phases.** Agents within the same step run in parallel via the Agent tool. Phases run sequentially.
-- **Real code, real tests, real commits.** This pipeline writes actual files, runs actual tests, and makes actual git commits. It does not produce documents about code.
-- **Evidence-based quality.** The Reality Checker defaults to NEEDS WORK. The Evidence Collector requires proof. Do not self-approve.
-- **TodoWrite for progress tracking.** Use TodoWrite to create and update a task checklist at the start of Phase 3. This is your primary progress tracker — it survives context compaction better than memory alone.
-- **State persistence.** After completing each step, update `docs/plans/.build-state.md` with your current phase, step, task progress, and agent usage. This file is your recovery point if context is compacted.
+**After research/analysis agents return:**
+1. Read and use the full output — this is your decision-making input
+2. Save the output to the appropriate file in `docs/plans/` (research brief, architecture doc, etc.)
+3. Once saved to disk, you can reference the file later instead of holding it all in context
 
----
+**Never do these yourself:**
+- Read source code files to understand implementation details — spawn an Explore agent
+- Write or edit code — spawn an implementation agent
+- Debug failures — spawn a fix agent with the error message
 
-## Phase 0: Initialize
+If you catch yourself typing code or reading source files: STOP. You are wasting context. Spawn an agent.
 
-Before starting any work:
+**Dispatch Counter:** Track agent dispatches in `docs/plans/.build-state.md` under `## Dispatch Counter`:
+- `dispatches_since_save: [N]`
+- `last_save: [Phase.Step]`
+Increment after each agent returns (parallel dispatch of 4 agents = +4). Reset to 0 after each compaction save.
 
-1. **Create a TodoWrite checklist** with the 5 phases:
-   - [ ] Phase 1: Architecture & Planning
-   - [ ] Phase 2: Foundation
-   - [ ] Phase 3: Build (will expand into per-task items later)
-   - [ ] Phase 4: Harden
-   - [ ] Phase 5: Ship
+Input: $ARGUMENTS
 
-2. **Write initial state** to `docs/plans/.build-state.md`:
-   ```
-   Phase: 0 — Initializing
-   Input: [user's build request]
-   Started: [timestamp]
-   ```
+### Autonomous Mode
 
-3. Proceed to Phase 1.
+If the input contains `--autonomous` or `--auto`, this build runs **unattended**. The user will not be present to approve quality gates. In autonomous mode:
+- Quality gates auto-approve. Do NOT pause and wait for user input.
+- Brainstorming runs in autonomous mode (see protocol).
+- Metric loops that stall accept at >= 60% of target, skip below that.
+- Log every decision to `docs/plans/build-log.md` so the user can review later.
 
----
+If `--autonomous` is NOT present, all quality gates require user approval as described below.
+
+When combining `--resume` with `--autonomous`: the current invocation's flags take precedence over saved state. If you resume a previously interactive build with `--autonomous`, it continues in autonomous mode.
 
-## Phase 1: Architecture & Planning
+### Metric Loop
 
-**Goal**: Define the technical architecture, component structure, UX foundation, and sprint task list. No code yet — just the blueprint.
+Every phase uses a **metric-driven iteration loop** to drive quality. Read the full protocol at `commands/protocols/metric-loop.md`. Critical rules (survive compaction):
+
+1. YOU define a metric for this phase based on context (what you're building, what matters). The metric is NOT predefined.
+2. Spawn a **measurement agent** to score the artifact 0-100. Read its full output — it's analysis.
+3. Pick the ONE highest-impact issue. Spawn a separate **fix agent** with ONLY that issue + file paths.
+4. Re-measure. Repeat until: target met, stalled (2 consecutive delta <= 0), or max iterations.
+5. Track all scores in `docs/plans/.build-state.md` — this is your lifeline across compaction.
 
 <HARD-GATE>
-Quality Gate: User MUST approve the architecture and task list before any code is written. Do not proceed to Phase 2 without explicit user approval. "Looks good" counts. Silence does not.
+METRIC LOOP NON-NEGOTIABLES:
+- Measurement agent and fix agent are SEPARATE Agent tool calls — never share context (author-bias elimination).
+- Fix agent gets ONLY the top issue + file paths + acceptance criteria. NOT the full measurement findings.
+- One fix per iteration. Measure impact before fixing the next thing.
+- Each measurement is fresh — don't accumulate findings across iterations.
 </HARD-GATE>
 
-### Step 1.1 — Codebase Understanding (if existing project)
+### Handoff Documents
 
-If this is being built in an existing codebase, launch 2-3 **code-explorer** agents in parallel to map:
-- Similar features and their implementation patterns
-- Architecture layers and abstractions
-- File organization conventions, testing patterns, build system
+When spawning agents in sequence (e.g., architect → implementer → reviewer), pass **scoped handoffs** — not the full architecture dump. Each agent receives only what it needs:
 
-If this is a greenfield project, skip to Step 1.2.
+1. **Relevant architecture section** — the specific part of architecture.md that applies to this agent's task
+2. **Previous agent's output** — what the upstream agent produced (if any)
+3. **Acceptance criteria** — what "done" looks like for THIS agent
 
-### Step 1.2 — Architecture Design (Parallel)
+For implementation agents (Phase 4+): Do NOT paste the entire Design Document or Architecture Document. Extract the relevant sections only. For research and architecture agents (Phases 1-2): pass the full document — these agents need complete context to do their analysis.
 
-Launch these agents simultaneously:
+### Complexity Routing (Advisory)
 
-1. **Backend Architect** — Design the system architecture: services, data models, API contracts, database schema, external integrations. Define the technical boundaries and data flows. Be specific — name tables, endpoints, data structures.
+When composing agent prompts, prefix with `[COMPLEXITY: S/M/L]` to hint at the appropriate model tier:
 
-2. **UX Architect** — Design the frontend architecture: component hierarchy, layout system, responsive strategy, CSS architecture, state management approach. Produce a component tree with clear responsibilities.
+| Complexity | Task Types | Preferred Tier |
+|-----------|-----------|----------------|
+| S | Build-fix, cleanup, lint fix, single-error fix | Haiku-class (fastest) |
+| M | Measurement, eval, testing, single-feature impl | Sonnet-class (balanced) |
+| L | Architecture, research, multi-file impl, debugging | Opus-class (deepest reasoning) |
 
-3. **Security Engineer** — Review the proposed architecture for security concerns: auth model, data handling, input validation strategy, secrets management, threat model for the top 3 attack vectors.
+For sprint tasks, use the Size field from `docs/plans/sprint-tasks.md`. This is advisory — the tag documents intent for future model routing support.
 
-4. **code-architect** (Claude Code agent) — Analyze the architecture proposals against the existing codebase (if any). Produce a concrete implementation blueprint: specific files to create/modify, build sequence, dependency order.
+---
 
-After all return, synthesize into a single **Architecture Document** that resolves any contradictions between agents.
+## Phase 0: Context & Pre-Flight
 
-### Step 1.3 — Sprint Planning (Sequential, after 1.2)
+**Resuming?** If the input contains `--resume` OR if context was just compacted (SessionStart hook fired with active state):
+1. Read `docs/plans/.build-state.md` — verify it exists and has a Resume Point section.
+   If `docs/plans/.build-state.md` does not exist or has no Resume Point, warn the user: 'No previous build state found. Starting fresh.' Then proceed to Step 0.1 as a new build.
+2. Re-read this file and all protocol files in `commands/protocols/`.
+3. Re-read `docs/plans/sprint-tasks.md`, `docs/plans/architecture.md`, and `CLAUDE.md`.
+4. Rebuild TodoWrite from the state file (TodoWrite does NOT survive compaction or session breaks).
+5. Reset `dispatches_since_save` to 0 (fresh context window).
+6. Resume from the saved phase and step. Skip Phase 0.
 
-Launch **Sprint Prioritizer** with the Architecture Document:
-- Break the build into ordered, atomic tasks
-- Each task should be implementable and testable independently
-- Define acceptance criteria for each task — what "done" looks like, what tests must pass
-- Identify dependencies between tasks — what must be built first
-- Estimate relative complexity (S/M/L) for each task
-- **Include the architectural rationale** — WHY this task exists, which part of the architecture it implements
+### Step 0.1 — Read the Room
 
-Then launch **Senior Project Manager** to validate the task list:
-- Confirm realistic scope — remove anything that isn't in the brainstorming spec
-- Verify no missing tasks — every component from the architecture has implementation tasks
-- Ensure task descriptions are specific enough that a developer agent can execute without ambiguity
+Before doing anything, scan for existing context:
 
-Save the task list to `docs/plans/sprint-tasks.md`. The file MUST include this header:
+- Check if the input is a file path (e.g., `docs/plans/brainstorm.md`). If so, read it.
+- Check if `docs/plans/` or `docs/briefs/` exist with prior brainstorming, design docs, decision briefs, or research. Read them.
+- Check if there's existing code in the project. If so, this is an enhancement, not greenfield.
+- Check the conversation history — has the user been discussing this idea already?
+- Check if `docs/plans/learnings.md` exists from a previous build. If so, read it. Apply relevant PATTERNS to agent prompt design, avoid listed PITFALLs, use HEURISTICS when applicable.
 
-```
-# Sprint Tasks — buildanything pipeline
-# PROCESS: Execute each task using build.md Phase 3 Dev→QA loops.
-# DO NOT implement tasks directly. Dispatch to specialist agents.
-# If you lost context, re-read: commands/build.md
-#
-# Each task MUST go through: Implement (agent) → Verify (Evidence Collector) → Review (code-reviewer)
-```
+**Classify what you found:**
 
-### Quality Gate 1
+| Context Level | What You Have | What Happens |
+|---|---|---|
+| **Full design** | Design doc with decisions, scope, tech stack, data models | Skip Phase 1. Feed design into Phase 2. |
+| **Decision brief** | An idea-sweep brief with verdicts and MVP definition | Phase 1 skips research (Step 1.2). Brainstorming refines the brief into a design. |
+| **Partial context** | Some notes, conversation, rough sketch | Phase 1 runs fully. Feed context into brainstorming + research. |
+| **Raw idea** | One-line build request, no prior work | Phase 1 runs fully from scratch. |
 
-Present to the user:
-1. Architecture Document (system diagram, component tree, data models, API contracts)
-2. Sprint Task List (ordered tasks with acceptance criteria)
-3. Identified risks or decisions that need user input
+### Step 0.2 — Human Prerequisites Checklist
 
-Ask: **"Architecture and sprint plan ready. Approve to start building, or flag changes?"**
+Identify everything that requires HUMAN action before going heads-down:
 
-<HARD-GATE>
-DO NOT PROCEED WITHOUT USER APPROVAL. Wait for explicit confirmation.
-</HARD-GATE>
+- **API keys & secrets** — External services the project integrates with. List each key needed.
+- **Database setup** — Supabase, Postgres, etc. User needs to create it and provide credentials.
+- **Repository** — Git repo on GitHub? Public or private?
+- **Deployment** — Vercel, Railway, Fly.io? User needs to connect.
+- **MCP servers** — Playwright for visual testing, database access, etc.
+- **Local tooling** — Docker, specific runtimes, etc.
+
+Present the checklist:
 
-**Save state:** Write `docs/plans/.build-state.md`:
 ```
-Phase: 1 COMPLETE — awaiting user approval
-Tasks: [total] planned
-Agents used: Backend Architect, UX Architect, Security Engineer, code-architect, Sprint Prioritizer, Senior Project Manager
+BEFORE I GO HEADS-DOWN, please set up:
+
+[ ] [Service] API key → add as [KEY_NAME] to .env
+[ ] [Database] → add connection URL to .env
+[ ] GitHub repo → share the URL
+[ ] [Deployment service] connected (optional)
+
+Once done, say "ready" and I'll start building.
 ```
 
-Update TodoWrite: mark Phase 1 complete.
+<HARD-GATE>
+Interactive mode: DO NOT proceed until the user confirms prerequisites (or says to skip).
+Autonomous mode: Log checklist to `docs/plans/build-log.md`. Create `.env.example` with required keys. Proceed — log missing keys as blockers if hit during build.
+</HARD-GATE>
+
+### Step 0.3 — Initialize
+
+0. Create `docs/plans/` directory if it doesn't exist (greenfield projects won't have it).
+1. Create a TodoWrite checklist with Phases 0-6.
+2. Create `docs/plans/.build-state.md` as a single write with ALL of the following: phase and step (`Phase: 0 — Starting`), input (`[build request]`), context level (`[classification]`), prerequisites (`[status]`), dispatch counter (`dispatches_since_save: 0, last_save: Phase 0`), and a `## Resume Point` section with: phase, step, autonomous mode flag, completed tasks (none), git branch name.
+3. Go to Phase 1 (or Phase 2 if context level is "Full design").
 
 ---
 
-## Phase 2: Foundation
+## Phase 1: Brainstorm & Research
 
-**Goal**: Set up the project skeleton — build system, directory structure, base configuration, CI, design tokens. The scaffolding that every subsequent task builds on.
+**Goal**: Turn the raw idea into a validated Design Document grounded in research. This ensures Phase 2 architects receive a design, not a guess.
 
-### Step 2.1 — Project Scaffolding
+**Skip if** Step 0.1 classified context as "Full design" — go straight to Phase 2.
 
-Based on the Architecture Document, set up:
-- Project directory structure
-- Package manager and dependencies
-- Build/dev tooling configuration
-- Linting, formatting, type checking config
-- Base test framework and first passing test
-- Git initialization and .gitignore
-- Environment configuration (.env.example)
+### Step 1.1 — Brainstorming
 
-Use the **DevOps Automator** to define the infrastructure and CI setup.
-Use the **Frontend Developer** or **Backend Architect** (as appropriate) to scaffold the actual project.
+Follow the Brainstorm Protocol (`commands/protocols/brainstorm.md`).
 
-Commit: `feat: initial project scaffolding`
+In interactive mode: this is a conversation. Ask questions one at a time, propose approaches with trade-offs, let the user decide. Output: Design Document saved to `docs/plans/`.
 
-### Step 2.2 — Design System Foundation (if frontend)
+In autonomous mode: synthesize a design document directly using the build request and available context. Pick pragmatic defaults. Log rationale to `docs/plans/build-log.md`.
 
-Launch **UX Architect** to implement:
-- CSS design tokens (colors, spacing, typography as variables)
-- Base layout components (grid, container, responsive breakpoints)
-- Core UI primitives that other components will build on
+### Step 1.2 — Parallel Research (5 agents, ONE message)
 
-Commit: `feat: design system foundation`
+Skip if context level is "Decision brief" (research already done).
 
-### Quality Gate 2
+Call the Agent tool 5 times in a single message. Pass each agent the build request AND the Design Document draft.
 
-Run these checks:
-- Project builds without errors
-- Test framework runs and the initial test passes
-- Linting passes clean
-- Directory structure matches the Architecture Document
+1. Description: "Market research" — Prompt: "Research market size (TAM/SAM/SOM), competitive landscape (5-10 players), timing, and market structure for: [build request]. Design context: [paste design doc]. Use web search extensively. Report with a Market Verdict: GREEN/AMBER/RED."
 
-If any fail, fix before proceeding. Present status to user.
+2. Description: "Tech feasibility" — Prompt: "Evaluate hard technical problems (Solved/Hard/Unsolved), build-vs-buy decisions, MVP scope, and stack validation for: [build request]. Design context: [paste design doc]. Search for APIs and libraries mentioned in the design to verify they exist and are maintained. Report with a Technical Verdict."
 
-**Save state:** Update `docs/plans/.build-state.md`:
-```
-Phase: 2 COMPLETE
-Foundation: scaffolded, builds clean, tests pass
-Next: Phase 3 — Dev↔QA loops
-```
+3. Description: "User research" — Prompt: "Analyze target persona, jobs-to-be-done, current alternatives, behavioral barriers to adoption for: [build request]. Design context: [paste design doc]. Search for real user complaints and communities discussing this problem. Report with a User Verdict."
+
+4. Description: "Business model" — Prompt: "Evaluate revenue models, unit economics, growth loops, first-1000-users strategy for: [build request]. Design context: [paste design doc]. Search for comparable pricing and growth data. Report with a Business Verdict."
+
+5. Description: "Risk analysis" — Prompt: "Adversarial review: regulatory risk, security concerns, dependency risks, competitive response, top 3 failure modes for: [build request]. Design context: [paste design doc]. Search for enforcement actions and comparable failures. Report with a Risk Verdict."
+
+After all 5 return, synthesize a **Research Brief** with a verdict table. Save to `docs/plans/research-brief.md`.
+
+### Step 1.3 — Design Refinement
+
+Read the Design Document and Research Brief together. Check for contradictions:
+
+- Tech-feasibility flagged "Unsolved" hard problem → simplify or flag as risk
+- Risk-analysis returned RED → add mitigation or descope
+- User-research says "no validated demand" → flag as pivot point
+- Business-model says "no moat" → note for speed-to-market priority
+
+Update the Design Document with corrections. Save final version.
+
+### Step 1.4 — Persist Decisions
+
+Append key decisions to the project's `CLAUDE.md` (create if needed) under `## Build Decisions`:
+
+- Project name and one-line description
+- Primary user and core value prop
+- Tech stack (with rationale)
+- Key constraints or risks
+- MVP scope boundary (in vs. deferred)
 
-Update TodoWrite: mark Phase 2 complete.
+This ensures decisions survive context compaction.
+
+### Quality Gate 1
+
+**Autonomous:** Log design and research paths to `docs/plans/build-log.md`. If 2+ RED verdicts, log warning. Proceed.
+
+**Interactive:** Present Design Document summary + Research Brief verdict table. Ask: "Approve this design, or want to adjust?" <HARD-GATE>DO NOT PROCEED without user approval.</HARD-GATE>
+
+Update TodoWrite and `docs/plans/.build-state.md`.
+
+**Compaction checkpoint:** Check `dispatches_since_save` in `docs/plans/.build-state.md`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.md`. Reset `dispatches_since_save` to 0. TodoWrite does NOT survive compaction — rebuild it from this state file on resume.
 
 ---
 
-## Phase 3: Build — Dev↔QA Loops
+## Phase 2: Architecture & Planning
 
-<HARD-GATE>
-SENTINEL CHECK — Before starting Phase 3, verify ALL of these:
-- Phase 1 quality gate passed (user approved architecture)
-- Phase 2 quality gate passed (project builds, tests pass)
-- You are dispatching to agents, not coding directly
-- `docs/plans/.build-state.md` exists and is current
-- TodoWrite has Phases 1 and 2 marked complete
-
-If ANY check fails, STOP and resolve before continuing.
-</HARD-GATE>
+**Goal**: Convert the validated Design Document into a concrete architecture and ordered task list. Every agent receives the Design Document — not just the build request.
 
-**Goal**: Implement every task from the Sprint Task List. Each task goes through a Dev→Test→Review loop. This is where the actual product gets built.
+### Step 2.1 — Explore (existing codebase only)
 
-**First:** Expand the TodoWrite list — add each task from sprint-tasks.md as a separate todo item under Phase 3.
+If existing code, call the Agent tool — description: "Explore codebase" — prompt: "Explore this codebase. Map architecture layers, file conventions, testing patterns, existing features. Report findings."
 
-**For EACH task in the Sprint Task List, execute this loop:**
+If greenfield, skip to Step 2.2.
 
-### Step 3.1 — Implement
+### Step 2.2 — Architecture Design (4 agents in parallel, ONE message)
 
-Select the right developer agent based on task type:
-- **Frontend Developer** — UI components, pages, client-side logic
-- **Backend Architect** — APIs, database operations, server logic
-- **AI Engineer** — ML features, model integration, data pipelines
-- **Rapid Prototyper** — Quick integrations, glue code, utility functions
+Read the Design Document and Research Brief. Pass both to every agent.
 
-**Launch a FRESH agent for each task.** Do not reuse agents across tasks — this prevents context pollution.
+Call the Agent tool 4 times in a single message:
 
-The developer agent receives:
-- The specific task description and acceptance criteria from the Sprint Task List
-- The Architecture Document for context
-- Access to all existing code via Read/Grep/Glob tools
+1. Description: "Backend architecture" — Prompt: "Design system architecture. DESIGN DOC: [paste]. RESEARCH: [paste tech + risk sections]. Include services, data models, API contracts, database schema. Be specific. Respect tech stack and constraints from the design doc."
 
-The developer implements the task and writes tests that verify the acceptance criteria.
+2. Description: "Frontend architecture" — Prompt: "Design frontend architecture. DESIGN DOC: [paste]. RESEARCH: [paste user research section]. Include component hierarchy, layout, responsive strategy, state management. Align UX with the user persona from research."
 
-Commit after implementation: `feat: [task description]`
+3. Description: "Security architecture" — Prompt: "Security review. DESIGN DOC: [paste]. RESEARCH: [paste risk section]. Cover auth model, input validation, secrets management, threat model. Address any regulatory risks flagged in research."
 
-### Step 3.2 — Test & Verify
+4. Description: "Implementation blueprint" — Prompt: "Implementation blueprint. DESIGN DOC: [paste]. Include specific files to create/modify, build sequence, dependency order. Scope to MVP boundary from design doc."
 
-Launch **Evidence Collector** to verify the implementation:
-- Run the tests the developer wrote — do they pass?
-- Check the acceptance criteria from the Sprint Task List — is each one met?
-- If frontend: take screenshots as visual proof
-- Report: **PASS** (all criteria met with evidence) or **FAIL** (specific failures listed)
+After all 4 return, YOU synthesize into one Architecture Document. Save to `docs/plans/architecture.md`.
 
-### Step 3.3 — Code Review
+### Step 2.3 — Metric Loop: Architecture Quality
 
-Launch **code-reviewer** (Claude Code agent) to review the implementation:
-- Bugs, logic errors, security issues
-- Adherence to project conventions from the Architecture Document
-- Code quality — is it simple, DRY, readable?
+Run the Metric Loop Protocol (`commands/protocols/metric-loop.md`) on the Architecture Document. Define a metric based on this project — coverage of design doc requirements, specificity, consistency between agents. Max 3 iterations.
 
-### Step 3.4 — Loop Decision
+### Step 2.4 — Sprint Planning
 
-**IF Evidence Collector = PASS AND code-reviewer finds no critical issues:**
-- Mark task as complete in TodoWrite
-- Move to next task
-- Reset retry counter
+Follow the Planning Protocol (`commands/protocols/planning.md`). Use 2 sequential Agent tool calls:
 
-**IF Evidence Collector = FAIL OR code-reviewer finds critical issues:**
-- Increment retry counter
-- Send specific feedback to the developer agent: what failed, what the QA/reviewer found
-- Developer fixes and resubmits
-- Repeat Steps 3.2-3.3
+Call the Agent tool — description: "Sprint breakdown" — prompt: "Break this architecture into ordered, atomic tasks. Each task needs: description, acceptance criteria, dependencies, size (S/M/L). ARCHITECTURE: [paste]. DESIGN DOC: [paste]. Scope to MVP only."
 
-**IF retry count reaches 3:**
-- Stop and escalate to the user with:
-  - What the task is trying to do
-  - What keeps failing
-  - The specific error or QA feedback
-  - Ask: "Fix manually, skip for now, or redesign the approach?"
+Then call the Agent tool — description: "Validate task list" — prompt: "Validate this task list: [paste]. Check scope is realistic, no missing tasks, descriptions specific enough for a developer agent to execute, all tasks within MVP boundary."
 
-### Progress Tracking
+Save to `docs/plans/sprint-tasks.md`.
 
-After each task completes:
+### Quality Gate 2
 
-1. Update TodoWrite: mark the task complete.
+**Autonomous:** Log to `docs/plans/build-log.md`. Proceed.
 
-2. Report to user:
-```
-Task [X/total]: [task name] — COMPLETE
-  Tests: [pass count] passing
-  Attempts: [retry count]
-  Next: [next task name]
-```
+**Interactive:** Present Architecture + Sprint Task List. Ask: "Approve to start building, or flag changes?" <HARD-GATE>DO NOT PROCEED without user approval.</HARD-GATE>
 
-3. **Save state** — Update `docs/plans/.build-state.md`:
-```
-Phase: 3 IN PROGRESS
-Current task: [X+1]/[total] — [next task name]
-Completed: [list of completed tasks]
-Retry counter: 0
-Agents used this phase: [list]
-```
+Update TodoWrite and `docs/plans/.build-state.md`.
+
+**Compaction checkpoint:** Check `dispatches_since_save` in `docs/plans/.build-state.md`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.md`. Reset `dispatches_since_save` to 0. TodoWrite does NOT survive compaction — rebuild it from this state file on resume.
 
 ---
 
-## Phase 4: Harden
+## Phase 3: Foundation
+
+### Step 3.1 — Scaffolding
+
+Call the Agent tool — description: "Project scaffolding" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: M] Set up the project from this architecture: [paste]. Create directory structure, dependencies, build tooling, linting config, test framework with one passing test, .gitignore, .env.example. Commit: 'feat: initial scaffolding'."
+
+### Step 3.2 — Design System (frontend only)
+
+Call the Agent tool — description: "Design system setup" — mode: "bypassPermissions" — prompt: "Implement design system foundation from this architecture: [paste frontend section]. Create CSS tokens, base layout components, core UI primitives. Commit: 'feat: design system'."
+
+### Step 3.3 — Metric Loop: Scaffold Health
+
+Run the Metric Loop Protocol. Define a metric: builds clean, tests pass, lint clean, structure matches architecture. Max 3 iterations.
+
+### Step 3.4 — Verification Gate
+
+Run the Verification Protocol (`commands/protocols/verify.md`). Critical rules (survive compaction):
+- ONE agent runs all 6 checks sequentially: Build → Type-Check → Lint → Test → Security → Diff Review. Stop on first FAIL.
+- Agent auto-detects stack from manifest files (package.json → Node, go.mod → Go, etc.).
+- On FAIL: for build/type/lint errors, use the Build-Fix Protocol (`commands/protocols/build-fix.md`) — fixes one error at a time with cascade detection. For test/security/diff failures, spawn a targeted fix agent. Re-verify. Max 3 fix attempts.
+- On PASS: log `VERIFY: PASS (6/6)` to `docs/plans/.build-state.md`. Proceed.
+
+Call the Agent tool — description: "Verify scaffolding" — mode: "bypassPermissions" — prompt: "Run the Verification Protocol. Execute all 6 checks sequentially, stop on first failure. Report: VERIFY: PASS or VERIFY: FAIL with details."
+
+Do not proceed to Phase 4 until verification passes.
 
-**Goal**: The full product is built. Now stress-test it. This phase finds the bugs, performance issues, security holes, and accessibility failures that task-level QA misses.
+Update TodoWrite and state.
+
+**Compaction checkpoint:** Check `dispatches_since_save` in `docs/plans/.build-state.md`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.md`. Reset `dispatches_since_save` to 0. TodoWrite does NOT survive compaction — rebuild it from this state file on resume.
+
+---
+
+## Phase 4: Build — Metric-Driven Dev Loops
 
 <HARD-GATE>
-Quality Gate: Reality Checker must approve before this phase passes. The Reality Checker defaults to NEEDS WORK and requires overwhelming evidence for approval. Do NOT self-approve.
+Before starting: Phase 2 must be approved, Phase 3 must pass. You MUST call the Agent tool for EVERY task. No exceptions.
 </HARD-GATE>
 
-### Step 4.1 — Integration Testing (Parallel)
-
-Launch simultaneously:
+Expand TodoWrite with each sprint task.
 
-1. **API Tester** — Comprehensive API validation: all endpoints, edge cases, error responses, auth flows, rate limiting. Run the full test suite.
+**For EACH task:**
 
-2. **Performance Benchmarker** — Measure response times, identify bottlenecks, test under load if applicable. Flag anything that doesn't meet performance requirements from the Architecture Document.
+### Step 4.1 — Implement
 
-3. **Accessibility Auditor** — WCAG compliance audit on all user-facing interfaces. Screen reader testing. Keyboard navigation. Color contrast. Flag every barrier found.
+Call the Agent tool — description: "[task name]" — mode: "bypassPermissions" — prompt: "TASK: [task description + acceptance criteria]. HANDOFF — Architecture section: [paste ONLY the relevant section from architecture.md]. Design section: [paste ONLY the relevant section from the design doc]. Previous task output: [what the last completed task produced, if relevant]. Implement fully with real code and tests. Commit: 'feat: [task]'. Report what you built, files changed, and test results."
 
-4. **Security Engineer** — Security review of the built system: auth implementation, input validation, data exposure, dependency vulnerabilities. Run security scanning tools.
+Pick the right developer framing: frontend, backend, AI, etc. Set `[COMPLEXITY: S/M/L]` based on the task's Size from sprint-tasks.md.
 
-### Step 4.2 — Fix Critical Issues
+### Step 4.1b — Cleanup (De-Sloppify)
 
-For each critical issue found in 4.1:
-- Route to the appropriate developer agent with the specific finding
-- Developer fixes the issue
-- The agent that found the issue re-validates
-- Dev↔QA loop until the specific issue is resolved
+Follow the Cleanup Protocol (`commands/protocols/cleanup.md`). Critical rules (survive compaction):
+[COMPLEXITY: S]
+- Skip if trivial (< 20 lines, single file).
+- Cleanup agent is a SEPARATE agent from the implementer — no cleaning your own mess.
+- Scope is sacred: ONLY files from the implementation changeset. Zero exceptions.
+- Cleanup fixes: naming, dead code, unused imports, style, DRY. Does NOT: add features, change architecture, touch other files.
+- If cleanup breaks acceptance criteria, revert and skip. Never block the metric loop on cleanup failure.
 
-### Step 4.3 — Code Quality Pass (Parallel)
+Call the Agent tool — description: "Cleanup [task name]" — mode: "bypassPermissions" — with the list of files changed and the task's acceptance criteria.
 
-Launch simultaneously:
+### Step 4.2 — Metric Loop: Task Quality
 
-1. **code-simplifier** (Claude Code) — Simplify any overly complex code while preserving functionality
-2. **type-design-analyzer** (Claude Code) — Review all type definitions for proper encapsulation and invariants
-3. **comment-analyzer** (Claude Code) — Verify all comments are accurate and useful
+Run the Metric Loop Protocol on the task implementation. Define a metric based on the task's acceptance criteria. Max 5 iterations.
 
-Commit any improvements: `refactor: code quality improvements`
+### Step 4.3 — Loop Exit
 
-### Step 4.4 — Final Verdict
+On target met: mark task complete in TodoWrite, report "Task X/N: [name] — COMPLETE (score: [final], iterations: [count])".
 
-Launch **Reality Checker** for the final assessment:
-- Cross-validate all test results
-- Review all QA evidence from Phase 3 and Phase 4
-- Check every acceptance criterion from the Sprint Task List
-- Verdict: **PRODUCTION READY** or **NEEDS WORK** with specific items
+On stall or max iterations:
+- **Interactive:** present score history + top remaining issue to user.
+- **Autonomous:** accept if score >= 60% of target, skip otherwise. Log to `docs/plans/build-log.md`.
 
-### Quality Gate 4
+After each task: update TodoWrite and `docs/plans/.build-state.md`.
 
-Present to the user:
-1. Reality Checker's verdict
-2. Test results summary (pass/fail counts, coverage)
-3. Performance benchmarks
-4. Security findings (resolved and any remaining)
-5. Accessibility audit results
-6. Any items the Reality Checker flagged as NEEDS WORK
+### Step 4.4 — Post-Task Verification
 
-**Save state:** Update `docs/plans/.build-state.md`:
-```
-Phase: 4 COMPLETE
-Reality Checker: [verdict]
-```
+Run the Verification Protocol (`commands/protocols/verify.md`) to catch regressions. If FAIL, fix before starting the next task.
 
-Update TodoWrite: mark Phase 4 complete.
+**Compaction checkpoint:** Check `dispatches_since_save` in `docs/plans/.build-state.md`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.md`. Reset `dispatches_since_save` to 0. TodoWrite does NOT survive compaction — rebuild it from this state file on resume.
 
 ---
 
-## Phase 5: Ship
+## Phase 5: Harden — Metric-Driven Hardening
 
-**Goal**: Final documentation, clean git history, and handoff.
+### Step 5.0 — Pre-Hardening Verification
 
-### Step 5.1 — Documentation
+Run the Verification Protocol (`commands/protocols/verify.md`). ONE agent, 6 sequential checks (Build → Type → Lint → Test → Security → Diff), stop on first FAIL. Max 3 fix attempts. All checks must pass before starting expensive audit agents — do not waste audit agents on code that doesn't build or pass tests.
 
-Launch **Technical Writer**:
-- README with setup instructions, architecture overview, and usage
-- API documentation (if applicable)
-- Any environment/deployment notes
+### Step 5.1 — Initial Audit (4 agents in parallel, ONE message)
 
-Commit: `docs: add project documentation`
+Call the Agent tool 4 times in one message:
 
-### Step 5.2 — Final Commit
+1. Description: "API testing" — Prompt: "Comprehensive API validation: all endpoints, edge cases, error responses, auth flows. Report findings with counts."
 
-Use `/commit` to create a clean final commit with a summary of what was built.
+2. Description: "Performance audit" — Prompt: "Measure response times, identify bottlenecks, flag performance issues. Report benchmarks."
 
-### Completion Report
+3. Description: "Accessibility audit" — Prompt: "WCAG compliance audit on all interfaces. Check screen reader, keyboard nav, contrast. Report issues with counts."
 
-Present to the user:
+4. Description: "Security audit" — Prompt: "Security review: auth, input validation, data exposure, dependency vulnerabilities. Report findings with severity."
 
-```
-BUILD COMPLETE
-==============
+### Step 5.1b — Eval Harness
 
-Project: [name]
-Tasks: [completed]/[total] ([pass rate]%)
-Tests: [count] passing
-Commits: [count]
+Run the Eval Harness Protocol (`commands/protocols/eval-harness.md`). Define 8-15 concrete, executable eval cases from the audit findings and architecture doc. Run the eval agent. Record baseline pass rate. CRITICAL and HIGH failures feed into the metric loop in Step 5.2 as specific issues to fix.
 
-Architecture: [Backend Architect + UX Architect + Security Engineer]
-Implementation: [which developer agents were used]
-QA: [Evidence Collector + code-reviewer findings]
-Hardening: [API Tester + Performance Benchmarker + Accessibility Auditor + Security Engineer]
-Final Verdict: [Reality Checker's assessment]
+### Step 5.2 — Metric Loop: Hardening Quality
 
-Files Created: [count]
-Files Modified: [count]
+Run the Metric Loop Protocol on the full codebase using audit findings as initial input. Define a composite metric based on what this project needs. Max 4 iterations.
 
-Remaining Items: [any NEEDS WORK items from Reality Checker]
-```
+When fixing, dispatch to the RIGHT specialist. Security → security agent. Accessibility → frontend agent. Don't send everything to one agent.
+
+### Step 5.2b — Eval Re-run
 
-Update TodoWrite: mark Phase 5 and all items complete.
+Re-run the Eval Harness after the metric loop exits. All CRITICAL eval cases must now pass. If any CRITICAL case still fails, include it as evidence for the Reality Checker.
+
+### Step 5.3 — Reality Check
+
+Call the Agent tool — description: "Final verdict" — prompt: "You are the Reality Checker. Default: NEEDS WORK. The hardening loop reached score [final_score] after [iterations] iterations. Score history: [paste table]. Review all evidence. Eval harness results: [baseline pass rate] → [final pass rate]. CRITICAL failures remaining: [list or none]. Verdict: PRODUCTION READY or NEEDS WORK with specifics."
+
+<HARD-GATE>Do NOT self-approve. Reality Checker must give the verdict.</HARD-GATE>
+
+**Autonomous:** Log verdict to `docs/plans/build-log.md`. Continue.
+**Interactive:** Present score history + verdict to user. Update state.
+
+**Compaction checkpoint:** Check `dispatches_since_save` in `docs/plans/.build-state.md`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.md`. Reset `dispatches_since_save` to 0. TodoWrite does NOT survive compaction — rebuild it from this state file on resume.
+
+---
+
+## Phase 6: Ship
+
+### Step 6.0 — Pre-Ship Verification
+
+Final verification gate. Run the Verification Protocol (`commands/protocols/verify.md`). ONE agent, 6 sequential checks (Build → Type → Lint → Test → Security → Diff), stop on first FAIL. Max 3 fix attempts. All checks must pass before documenting and shipping. If FAIL persists, return to Phase 5 for targeted fixes.
+
+### Step 6.1 — Documentation
+
+Call the Agent tool — description: "Documentation" — mode: "bypassPermissions" — prompt: "Write project docs: README with setup/architecture/usage, API docs if applicable, deployment notes. Commit: 'docs: project documentation'."
+
+### Step 6.2 — Metric Loop: Documentation Quality
+
+Run the Metric Loop Protocol on documentation. Define a metric based on completeness and whether a new developer could follow the README. Max 3 iterations.
+
+### Step 6.3 — Record Learnings
+
+Append to `docs/plans/learnings.md` (create if it doesn't exist). Review the build and record 3-5 learnings:
+
+- **PATTERN:** [what worked well and should be repeated in future builds]
+- **PITFALL:** [what failed, caused waste, or required excessive iterations]
+- **HEURISTIC:** [project-specific tuning discovered during this build]
+
+Base learnings on: metric loop stall patterns, build-fix frequency, phases that exceeded expected iterations, agent prompts that needed rework.
+
+### Completion Report
+
+Create final commit. Present:
 
-**Save final state:** Update `docs/plans/.build-state.md`:
 ```
-Phase: 5 COMPLETE — BUILD DONE
+BUILD COMPLETE
+Project: [name] | Tasks: [done]/[total] | Tests: [count] passing
+Agents used: [list] | Verdict: [Reality Checker result]
+Metric loops run: [count] | Avg iterations: [N]
+Remaining: [any NEEDS WORK items]
 ```
+
+Mark all TodoWrite items complete. Update `docs/plans/.build-state.md`: "Phase: 6 COMPLETE."