SKILL.md
---
name: build
description: Use when an approved plan exists and needs execution, or when a hotfix/one-sentence scope needs direct TDD implementation — dispatches subagents per task, validates, reports
---
# /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:**
| Plan structure | Agent | Notes |
|---|---|---|
| Separate "write test" + "implement" tasks | `test-writer` (RED) then `implementer` (GREEN) | Sequential within the pair |
| Combined task ("implement X with tests") | `implementer` | Handles TDD internally |
| Docs-only task | `doc-writer` | |
**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:**
| Status | Action |
|---|---|
| DONE | Mark task complete |
| DONE_WITH_CONCERNS | Read concerns — if correctness/scope, address before continuing |
| NEEDS_CONTEXT | Provide missing context, re-dispatch |
| BLOCKED | Assess: more context? more capable model? break smaller? escalate to human? |
| Task touches protected file | Stop immediately — never dispatch |
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:
```bash
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:
```bash
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
| Relation | Skill |
|---|---|
| Called by | `/task` (Step 5) |
| Depends on | `/blueprint` (Step 3) + `/review` plan approval (Step 4) |
| Followed by | `/review` build review (Step 6) |