build

Use when an approved plan exists and needs execution, or when a hotfix/one-sentence scope needs direct TDD implementation — dispatches subagents per task,…

INSTALLATION

npx skills add https://github.com/camacho/ai-skills --skill build

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

/build

Name: build
Author: camacho

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:

pnpm typecheck &#x26;&#x26; 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:

Diagnose the failure

Fix (dispatch subagent or fix directly for small issues)

Re-run pnpm validate

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.

TDD: write failing test (RED), implement fix (GREEN), refactor

Minimal change: fix the defect, nothing else (hotfixes)

Root cause: document in commit message body (hotfixes)

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)