/sw-build

name: sw-build
description: >-
  TDD implementation of one work unit. Delegates test writing to the tester
  agent and implementation to the executor agent. Commits per task.
argument-hint: "[work-id] [task-id]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
  - TaskCreate
  - TaskUpdate
  - TaskList
  - TaskGet
  - AskUserQuestion

Specwright Build

Goal

Implement the current work unit with TDD. The per-task loop is RED → GREEN → REFACTOR; end-of-unit integration and regression checks live in one optional after-build phase.

Inputs

• `{worktreeStateRoot}/session.json` -- selected work for this worktree
• `{repoStateRoot}/work/{selectedWork.id}/workflow.json`, `{workDir}/spec.md`, `{workDir}/plan.md`
• `{workArtifactsRoot}/{selectedWork.id}/design.md`, `{workDir}/context.md`
• `{workArtifactsRoot}/{selectedWork.id}/approvals.md` -- durable design and unit approval ledger when present
• `{projectArtifactsRoot}/CONSTITUTION.md`, `{projectArtifactsRoot}/config.json`

Outputs

• After each task: failing tests, passing implementation, task commit, workflow progress, updated `{workDir}/implementation-rationale.md`, refreshed `{repoStateRoot}/work/{selectedWork.id}/units/{selectedWork.unitId}/stage-report.md`
• After all tasks: as-built notes in `plan.md`, three-line handoff to `/sw-verify`, ready-to-verify build state; the handoff points at `Artifacts: {repoStateRoot}/work/{selectedWork.id}/units/{selectedWork.unitId}/stage-report.md`

Constraints

**Execution model (LOW freedom):** Run in the foreground in the current turn. "Autonomous" means unattended decisions inside this build, not background execution.

**Stage boundary (LOW freedom):** Follow `protocols/stage-boundary.md`. Implement only the active unit; never create pull requests, run `gh pr create`, or invoke `/sw-ship`. Before the terminal handoff, write `{repoStateRoot}/work/{selectedWork.id}/units/{selectedWork.unitId}/stage-report.md`; the handoff points at it and the Next line is `Next: /sw-verify`.

**Branch setup (LOW freedom):** First action before coding: resolve the session-selected work from the current worktree, verify that no other live top-level worktree owns it, then check out the feature branch from `config.git.branchPrefix` and sync it per `protocols/git.md`. The selected work's recorded `targetRef`, when present, is the first branch-resolution input via `protocols/git.md`; repo config defaults and the `baseBranch` compatibility alias are fallbacks only. Use `{git.branchPrefix}{selectedWork.unitId}` for multi-unit work and never commit to the base branch. If the selected work is already owned elsewhere, STOP with explicit `/sw-adopt` guidance instead of mutating it silently; do not fall back to implicit adopt/takeover behavior.

**Build freshness checkpoint (LOW freedom) — after branch setup:** Evaluate the build checkpoint via `protocols/git-freshness.md` using the selected work's recorded `targetRef` and `freshness`. `require` blocks stale, diverged, and blocked freshness results; `warn` surfaces advisory drift; queue-managed results stay distinct and do not trigger implicit local rewrites. When branch-head validation is blocked and `rebase` or `merge` reconcile is configured, run `protocols/git-reconcile.md` in the owning worktree and continue in the same stage after a successful reconcile. `manual` remains an explicit fallback: stop with manual reconcile guidance, reconcile the current branch against the recorded target in the owning worktree, or run `/sw-adopt` first if a linked-worktree ownership conflict exists, then rerun `/sw-build`. Do not clear the block by silently rewriting `targetRef` or freshness metadata.

**Approval checkpoint (LOW freedom) — before task loop:** Use `protocols/approvals.md` and the shared helper with the current unit artifact set (`spec.md`, `plan.md`, `context.md`). When `sw-pivot` or replanning regenerated the current unit artifacts, that regenerated artifact set becomes the current approval surface. Interactive `/sw-build` runs may record an `APPROVED` `unit-spec` entry in `{workArtifactsRoot}/{selectedWork.id}/approvals.md` with source classification `command`, and they must refresh or record that approval for the regenerated surface before any task executes. Headless runs must validate existing human approval instead. Approval refresh does not replace branch reconciliation and must not be used to clear a separate freshness block. Never move approval truth into `workflow.json`.

**Task loop (MEDIUM freedom):** Work one task at a time. Finish it before starting the next and emit a status card after each task commit.

**Implementation rationale (LOW freedom) — at each task commit boundary:** Maintain `{workDir}/implementation-rationale.md` as an append-only curated artifact with one section per completed task. In `tracked` work-artifact mode, stage the task's rationale content before creating the task commit so the tracked tree stays clean; if the resulting commit SHA is only known after the commit is created, capture that SHA in the next synchronized rationale update instead of leaving tracked artifacts dirty between tasks. Each task entry must record the task ID, relevant AC references, changed files, tests added or updated, why this approach was chosen, any deviation from the approved unit artifacts, the execution path (`executor` or `build-fixer`), and the task commit SHA once it is known. This artifact captures rationale, not transcript excerpts.

**TDD cycle (LOW freedom for sequence):** 1. **RED:** delegate to `specwright-tester`, write hard-to-pass tests, and confirm they fail. 2. **GREEN:** delegate to `specwright-executor`, pass the failing tests, and stop on any plan mismatch or pre-existing type/signature discrepancy. 3. **REFACTOR:** simplify only code written for the current task; keep behavior unchanged. Per-task integration and regression runs do not happen inside this loop.

**Mid-build checks (MEDIUM freedom):