/build

name: build
user-invocable: true
description: Executes an implementation plan — writes code and tests, runs quality review, and ships a pull request.
when_to_use: Use when user says "build this", "implement the plan", "start coding", "execute the plan", or "ship it".
effort: high
argument-hint: plan file path
allowed-tools: Bash(rm -rf docs/reviews/)
compatibility: Designed for Claude Code (or similar products with agent support)

Execute an implementation plan

Take a plan from `docs/plan/` and turn it into shipped code: implement features, write tests, and validate quality.

Build Progress

Copy this checklist and track your progress:

Build Progress:
- [ ] Phase 0: Load plan and confirm scope (or resume a phased build)
- [ ] Phase 1: Read context for the current implementation phase
- [ ] Phase 2: Loop implementation phases (implement → validate → commit or hand off → checkpoint → clear)
- [ ] Phase 3: Run review agents (5 in parallel), consolidate into one report
- [ ] Phase 4: Drive to green, cleanup, and ship

Plan Input

<plan_path>$ARGUMENTS</plan_path>

Phase 0 — Load Plan

ls docs/plan/

| Plan path | Plans in `docs/plan/` | Action | |-----------|-----------------------|--------| | Provided | — | Read the file. If missing, suggest running `/plan` | | Empty | One | Read it, announce "Found plan: [title]", proceed | | Empty | Multiple | **AskUserQuestion**: list each with summary, ask which to use | | Empty | None | Tell user to run `/plan` first |

Do not proceed without a plan.

**After loading the plan:** parse title, type, the `success-criteria` block, tasks, file paths, and the `## Implementation Phases` section if present.

**Commit autonomy:** decide once how this build commits, and carry the choice through the whole run. Honor a saved preference if one exists (Claude memory or the user's personal settings); otherwise use **AskUserQuestion**:

• **Auto-commit each phase (Recommended)**: commit automatically as each phase completes. Pushing and opening the PR still pause for approval (Phase 4).
• **I'll commit myself**: build one phase, then stop so the user reviews and commits. Nothing is committed or pushed without the user.

Offer to save the choice to Claude memory (a personal preference) so future builds skip this question. Save it as the user's own preference — never write it to the project's CLAUDE.md, since committing this is a per-developer choice, not a repo convention.

**Resuming a phased build:** if the plan has an `## Implementation Phases` section with at least one phase already marked `**Status:** Done`, this is a resumed build. Announce "Resuming at Phase N: [name]" — the first phase whose status is not `Done` — and go straight to Phase 1 for that phase. Skip the scope-confirmation question below.

**Otherwise**, summarize scope to the user, then use **AskUserQuestion** to confirm:

• **Start building (Recommended)**: proceed with implementation
• **Review the plan first**: open the plan file for review
• **Adjust scope**: accept user input on what to change

Do not proceed until the user selects "Start building."

Phase 1 — Setup

**Do not run `codebase-review-agent` here.** The plan was already informed by codebase context from `/brainstorm` and `/plan`.

Instead, use the plan itself as your guide:

1. **Read referenced files**: Read the files for the phase you are about to build (the current phase's **Files touched**, plus their immediate neighbors). For a plan with no `## Implementation Phases` section, read every file listed in the plan's tasks. Reading only the current phase's files keeps context focused so each phase fits in one window. 2. **Extract conventions**: If the plan includes a codebase context or conventions section, use it as your source of truth for patterns and style. 3. **Targeted searches only**: If the plan references a pattern or convention you need a concrete example of, use Grep or Glob to find a single representative example — do not do a broad sweep.

Phase 2 — Execute

Determine the unit of work:

• **Plan has an `## Implementation Phases` section** → build one phase at a time with the phase loop below. Each phase carries the fields defined in the [implementation phases block](references/implementation-phases.md) — Status, Scope, Files touched, Acceptance criteria, and Validation — and is sized to fit a single context window, so `/build` executes one phase per window.
• **No phases** → treat the whole plan as one phase: implement every task, then run the loop once.

Phase loop

Pick the current phase — the first whose `**Status:**` is not `Done` (a plan with no phases has one implicit phase: the whole plan). Run these steps for it:

Step 1: Implement

Write code following VGV conventions, limited to this phase's **Scope** and **Files touched**. Build layers in dependency order (Data → Domain → Presentation). Use the project's state management tool, naming patterns, linter, and formatter. Respect layer boundaries — presentation never imports data directly.

Step 2: Test

Tests are non-negotiable. Write them alongside each implementation unit:

• **State management**: Use VGV testing conventions with the project's testing framework. Cover success, failure, and edge cases. Seed initial states when testing non-initial conditions.
• **UI components**: Follow VGV's UI testing conventions with proper wrappers and providers. Test all rendered states and user interactions. Wait for async state changes before asserting.
• **Repositories/Data**: Unit tests for serialization, API calls, error handling, and edge cases.
• **Utilities**: Pure functions get unit tests.

Every new state management unit, repository, UI component, and data model must have a test file.

Step 3: Validate

Run the phase's **Validation** steps, then follow the [validation and fix procedure](references/validate-and-fix.md). Everything must pass before you record the phase.

Step 4: Record the