/build

description: "Execute plans using fresh subagents with review gates"
disable-model-invocation: true
argument-hint: "[phase-number] [--plan N] [--light]"

/shipyard:build - Plan Execution

You are executing the Shipyard build workflow. Follow these steps precisely.

<prerequisites>

Step 1: Parse Arguments

• If a phase number is provided, use it.
• If `--plan N` is provided, execute only that specific plan (format: W.P).
• If `--light` is provided, skip post-phase auditor and simplifier (Steps 5a and 5b). Use this during early iteration — the full pipeline runs at ship time regardless.
• If no phase number, read `.shipyard/STATE.json` for the current phase.
• Read `.shipyard/config.json` for gate preferences (`security_audit`, `simplification_review`, `iac_validation`, `documentation_generation`).
• Follow **Worktree Protocol** (detect if running in a git worktree; if so, use worktree root for paths and record the branch name; see `docs/PROTOCOLS.md`) -- detect worktree, record working directory and branch.
• Follow **Model Routing Protocol** (select the correct model for each agent role using `model_routing` from config; see `docs/PROTOCOLS.md`) -- read `model_routing` from config for agent model selection.

Step 2: Validate State

1. Verify `.shipyard/` exists. If not, tell the user to run `/shipyard:init` first. 2. Read `.shipyard/ROADMAP.md` and locate the target phase. 3. Read `.shipyard/STATE.json` for current context. 4. Load all plan files from `.shipyard/phases/{N}/plans/`. 5. Check which plans have already been completed (have SUMMARY.md files in `.shipyard/phases/{N}/results/`). 6. If all plans are complete, inform the user and suggest `/shipyard:ship` or next phase.

Step 2b: Team or Agent Dispatch

**Detection:** Check the `SHIPYARD_TEAMS_ENABLED` environment variable (exported by `scripts/team-detect.sh`). This variable is set to `true` when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.

**Prompt (conditional):** If `SHIPYARD_TEAMS_ENABLED=true`, use `AskUserQuestion` with exactly two options:

• "Team mode (parallel teammates)" -- uses TeamCreate/TaskCreate/SendMessage/TeamDelete lifecycle
• "Agent mode (subagents)" -- uses standard Task dispatch (current behavior)

Question text: "Teams available. Use team mode (parallel teammates) or agent mode (subagents)?"

**Silent fallback:** If `SHIPYARD_TEAMS_ENABLED` is `false` or unset, silently set `dispatch_mode` to `agent` with no prompt (zero overhead).

**Variable storage:** Store the result as `dispatch_mode` (value: `team` or `agent`). This variable is referenced by all subsequent dispatch steps.

**Note:** In team mode, single-agent steps (verifier, auditor, simplifier, documenter) still use Task dispatch -- team overhead is not justified for one agent. Team mode applies only to multi-agent steps (builders per wave, reviewers per wave).

</prerequisites>

<execution>

Step 3: Update State

Follow **State Update Protocol** (update `.shipyard/STATE.json` and `.shipyard/HISTORY.md` via state-write.sh; see `docs/PROTOCOLS.md`) -- set:

• **Phase:** {N}
• **Position:** Building phase {N}
• **Status:** building

Step 3a: Create Checkpoint

Follow **Checkpoint Protocol** (create a named git tag for rollback safety at key pipeline stages; see `docs/PROTOCOLS.md`) -- create `pre-build-phase-{N}` checkpoint.

Step 4: Execute by Wave

Group plans by wave number. Execute waves sequentially, plans within a wave in parallel.

For each wave (sequential):

Step 4a: Launch Builders (parallel within wave)

**If dispatch_mode is agent:**

For each incomplete plan in this wave, dispatch a **builder agent** (subagent_type: "shipyard:builder") with context per **Agent Context Protocol** (pass PROJECT.md, config.json, working directory, branch, and worktree status to all agents; see `docs/PROTOCOLS.md`):

• The full plan content (PLAN-{W}.{P}.md)
• Codebase docs per **Codebase Docs Protocol** (resolve configured codebase docs path and load CONVENTIONS.md, STACK.md, ARCHITECTURE.md, etc.; see `docs/PROTOCOLS.md`)
• `.shipyard/phases/{N}/CONTEXT-{N}.md` (if exists) -- user decisions to guide implementation
• Results from previous waves (SUMMARY.md files)

**Builder agent instructions:**

• Execute each task in the plan sequentially
• After each task, verify the acceptance criteria
• Create an atomic git commit for each completed task:

  shipyard(phase-{N}): {task description}

• If a task fails, document the failure and stop (do not proceed to next task)
• When complete, produce `.shipyard/phases/{N}/results/SUMMARY-{W}.{P}.md`:

  # Build Summary: Plan {W}.{P}

  ## Status: {complete|partial|failed}

  ## Tasks Completed
  - Task 1: {title} - {status} - {files changed}
  - Task 2: {title} - {status} - {files changed}

  ## Files Modified
  - {file path}: {what changed}

  ## Decisions Made
  - {any implementation decisions and rationale}

  ## Issues Encountered
  - {any problems and how they were resolved}

  ## Verification Results
  - {results of running acceptance criteria checks}

**Lesson Seeding:** Document all discoveries thoroughly in "Issues Encountered" and "Decisions Made":

• Unexpected behaviors or edge cases found
• Workarounds applied and why
• Assumptions proven wrong during implementation
• Things that were harder or easier than expected

These entries will be used as pre-populated suggestions when capturing lessons at ship time.

**If dispatch_mode is team:**

1. `TeamCreate(name: "shipyard-build-phase-{N}-wave-{W}")` -- create a team scoped to this wave 2. For each incomplete plan in the wave, `TaskCreate` with:

• Subject: "Build Plan {W}.{P}: {plan_title}"
• Description: the full plan content (PLAN-{W}.{P}.md) plus codebase docs, CONTEXT-{N}.md, and results from previous waves

3. `TaskUpdate` to pre-assign each task to a specific teammate name (e.g., `builder-{W}-{P}`) BEFORE spawning 4. For each task, `Task(team_name: "shipyard-build-phase-{N}-wave-{W}", name: