Build

/build

Execute plan tasks via subagents, validate, report.

Announce: "Starting /build — executing plan with subagent dispatch."

Prerequisites

• Plan approved by /review (Step 4), OR one-sentence scope / hotfix (no plan)
• Working in a linked worktree (not primary)

With Plan

1. Load

Read ai-workspace/plans/<name>.md. Extract tasks into ordered batches:

• Tasks under the same step or marked parallel = one batch
• Tasks with dependencies on prior tasks = separate sequential batch
• Note file paths, test expectations, and acceptance criteria per task

2. Execute Batches

Batches run sequentially. Tasks within a batch dispatch in parallel via subagents.

Agent selection per task:

Parallel safety: only dispatch tasks in parallel when they touch different files.

Subagent prompt — provide each agent:

You are implementing Task N: [task name]

## Task Description
[FULL TEXT from plan — paste it, don't make the subagent read the file]

## Context
[Where this fits, what earlier batches produced, architectural decisions]

## Working Directory
[Absolute path to worktree]

## Project Conventions
- TDD: write failing test first, make it pass, refactor
- Commit after task completes (conventional commits) AND ensure your work is on disk before reporting DONE — the inter-batch step commits a batch boundary, but your task-level commits make recovery from inter-batch failures cleaner
- TypeScript strict, ESM, Biome, Vitest, Pino logger, no barrel exports
- Self-review before reporting back

## Report: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT

Handle responses:

Never retry BLOCKED without changing something.

Inter-batch check — after each batch, verify no regressions AND commit the batch's output before starting the next batch:

pnpm typecheck && pnpm test
git -C "$WORKTREE" add -A
git -C "$WORKTREE" commit -m "<type>(<scope>): batch N — <summary>"

Per-task commits inside a batch are best-effort; batch-boundary commits are mandatory (per /task invariant REQUIRE batch.commit BEFORE batch.next). A batch that finishes verify but doesn't commit can lose all its work if the next batch fails or the session ends. The wip-checkpoint Stop hook (ADR-008) captures dirty state at session end as a backstop, but inter-batch commits keep the recovery shape clean — per-batch granularity in branch history rather than a single dirty-state blob on the side ref.

3. Validate (Hard Gate)

After ALL batches complete:

pnpm validate

Read the output. Never claim success without evidence. If it fails: 1. Diagnose the failure 2. Fix (dispatch subagent or fix directly for small issues) 3. Re-run pnpm validate 4. Max 3 fix-validate cycles. If still failing, stop and report.

Step 6 (/review) CANNOT begin until validate passes.

4. Report

Build complete.
Tasks: <completed>/<total>
Validate: PASS
Next step: /review (Step 6)

Include any DONE_WITH_CONCERNS notes. Update .branch-context.md with decisions made during build.

Without Plan (Hotfix / One-Sentence Scope)

Implement directly — no subagent orchestration for small scope.

1. TDD: write failing test (RED), implement fix (GREEN), refactor 2. Minimal change: fix the defect, nothing else (hotfixes) 3. Root cause: document in commit message body (hotfixes) 4. Validate: pnpm validate — same hard gate, same 3-attempt max

Codex / Cursor Fallback

No subagent dispatch. Execute tasks sequentially in main session. Same validation gate applies.

Integration