---
name: ship
description: Use when the user invokes /ship or asks to execute an implementation plan in-session with subagents — wave-based dispatch (fresh implementer per task), two-stage review (spec compliance then code quality), automated verification, then land via the project's frozen ship.sh.
---

# Ship — In-Session Wave Execution (Subagent-Driven)

audience: AI coding agents first. Ladders are the tool; follow them in order.

MUST follow `/home/user/Projects/0 DOCS/GIT_FATIGUE.md` §12. Valid current-tree receipt/log = proof; NEVER rerun broad checks. Delivery controller owns validation, publication, deploy, and cleanup. User surface MUST be only `Preview ready` or `Needs product decision`.

Fresh subagent per task + two-stage review + verification + land = autonomous quality delivery. Fresh context per task → implementers stay focused; never inherit session history — provide exactly what's needed in the prompt.

**Multi-spec / multi-task batches:** a directive containing multiple specs to ship sequentially ("ship #1 then #2 then #3", "do all three", a numbered list) = consent for the WHOLE batch. Proceed through all specs WITHOUT pausing for user review between them — re-asking forces the user to repeat consent. Pause mid-batch ONLY on a hard blocker: BLOCKED status, parity/correctness failure, cache-safety risk, advisor ship-stopper, or user interrupt. Spec-internal decision gates (measured threshold not met) still apply — spec logic, not user review.

## When to Use

1. Have an implementation plan with mostly independent tasks → ship.
2. No in-session implementation plan → `brainstorm` first.
3. Tightly coupled tasks or work that should run through the factory → author a request spec stating the goal, constraints, affected files or seams, required behavior, and executable acceptance commands; then run `cd <repoRoot> && factory adw_plan_build_test_quality docs/plans/<file>.md`.

## Process (top-level ladder)

1. Pre-flight: dirty-tree check (below) → worktree via `using-git-worktrees` → plan-already-implemented check.
2. Read plan → extract waves + tasks (plan's "Wave Plan" table, group by wave number) → TodoWrite.
3. Per wave IN ORDER: single-task flow or parallel flow (below). Never start wave N+1 before wave N is fully done and committed.
4. All waves done → final code review (advisor) → verification (type by work done) → fix subagent + re-verify until pass.
5. Land via the project's frozen `ship.sh` → run `learn-from-mistakes`.

## Pre-Flight

**Dirty tree** (before worktree creation): `git status` on main dirty → ALWAYS inspect first, then recommend a path (user pre-selected this flow 2026-05-22 — never ask upfront which option):
1. `git diff --stat` + `git ls-files --others --exclude-standard` — scope.
2. Read current-tree validation receipt/log. Missing or invalid receipt → defer authoritative broad check to designated executor; NEVER run typecheck "just to verify."
3. Per-file diff on files the spec touches → collisions?
Recommend ONE: **commit WIP** (coherent + tsc-clean; supply message) / **stash** (incomplete; `git stash -u`, restore after) / **abort ship** (WIP and spec collide). Proceed only after user confirms.

**Already implemented?** `git log --oneline HEAD ^main | grep -i "<plan-keywords>"` — commits found → mark tasks complete, skip dispatch.

## Worktree Setup

Invoke `using-git-worktrees` → `.worktrees/<branch-name>/`. Record `WORKTREE_PATH`; pass it in EVERY implementer AND reviewer prompt: "All file edits inside this path. cd to it before any work."

- Pre-commit hook depends on gitignored files (e.g. `eslint.config.js`) → put `SKIP_SIMPLE_GIT_HOOKS=1` directly on `git commit` (`git add <files> && SKIP_SIMPLE_GIT_HOOKS=1 git commit -m "..."`). NEVER prefix `git add` with it — env var scoped to the wrong command does nothing. (fired 3×)
- Before writing any test file in a worktree: `git check-ignore -q <spec-path>`. Gitignored → write to MAIN repo working tree instead (worktree copy evaporates at cleanup); already in worktree → `cp` to main repo before landing. (fired 2×)
- More worktree/build-env failure modes → `references/learned-rules.md` (consult the index before builds, merges, deploys).

## Single-Task Wave

1. Dispatch implementer (commits own work) — `./implementer-prompt.md`.
2. Verify commit SHA exists: `git log --oneline -3`.
3. Spec-compliance review, then quality review — advisor() in controller, NOT subagents. Never start quality review before spec review is ✅.
4. Diff scan: `git diff HEAD~1..HEAD -- <changed-src-files>` — dead vars, unused imports, dead blocks → fix subagent.

## Multi-Task Wave (parallel)

1. **Before dispatch:** confirm ZERO file overlap across wave tasks. Overlap → STOP, report conflict, fix plan first.
2. Dispatch all implementers simultaneously (foreground, `subagent_type: "claude"`). Every prompt MUST include: `PARALLEL WAVE: Do NOT commit. Write files, run minimal task tests, return status. Return: list of files you modified.` Remove per-subagent broad checks; controller consumes valid candidate receipt or runs ONE authoritative gate after assembled changes.
3. All complete → verify expected files exist on disk.
4. Per task sequentially: spec review → quality review (fix loops as normal).
5. Controller commits the wave FROM THE WORKTREE (`cd <worktree> && git add ... && commit`), staging from `git status --short` reality, not the plan's file list. MUST commit before dispatching the next wave.
6. Wave diff scan across all wave files together.

Implementer asks a question → pause that agent, answer, re-dispatch; siblings continue. Don't commit until ALL pass review.

## Prompt-Building Rules (fired ≥2×, promoted)

- Plan widens/extends a shared interface → prompt MUST include `grep -rn 'InterfaceName' src/` output listing ALL consumer files (demo/mock data counts). Never just the files the spec names.
- Prompt embeds exact JSX / component APIs → Read the target component source first; never guess APIs from memory.
- More prompt-authoring failure modes → `references/learned-rules.md` (Prompt authoring index).

## Model Selection

Least powerful model per role:
- **Haiku** — docs, i18n, string extraction, boilerplate, purely mechanical text. NEVER as verifier for multi-file symbol checks — false FAILs from bad grep (fired 2×); verifiers are Sonnet minimum, and any FAIL on a symbol-existence check gets controller double-check via direct `grep -rn 'symbol' WORKTREE_PATH/src/` before dispatching a fix.
- **Sonnet** — default implementation: scaffolds, clear specs, 1-2 files, multi-file integration, invariant reasoning.
- **Reviews** (spec, quality, final) — advisor() in controller, not a subagent.

## Verification

Read current-tree receipt first. Valid receipt → use its logs; NEVER re-run. Missing/invalid receipt → designated executor runs affected Playwright/E2E lane once. Mass failures → capture full set, cluster, repair ALL, ONE replacement run. Verification gotchas → `references/learned-rules.md`.

## Land + Deploy + Finish

Land ONLY via the project's frozen wrapper — never hand-type merge/push/deploy, never re-sniff the target:

```bash
bash <PROJECT_ROOT>/.claude/scripts/ship.sh land <branch> <worktree>
```

- **exit 0** → published, cleaned. Emit only `Preview ready`.
- **exit 20** → agent action (conflict/blocker/failed gate) → follow `finishing-a-development-branch` rubric, re-run. NEVER escalate git to the user.
- **No wrapper yet?** Initialize project delivery controller per `finishing-a-development-branch`. Resolve internal PR/merge mechanism without asking owner.

After land → `Skill("learn-from-mistakes")` inline (not a subagent).

## Handling Implementer Status

- **DONE** (single) → verify SHA in git log → spec review. **DONE** (parallel) → verify files on disk (no SHA — controller commits).
- **DONE_WITH_CONCERNS** → read concerns; correctness/scope → address before review; observations → note, proceed.
- **NEEDS_CONTEXT** → provide, re-dispatch.
- **BLOCKED** → context problem → provide + re-dispatch; needs reasoning → advisor() then re-dispatch; too large → split; plan wrong → escalate to user. NEVER ignore escalation or retry unchanged.

## Red Flags — NEVER

- Start on main/master without explicit user consent; skip worktree setup.
- Skip either review stage, accept "close enough" on spec, let implementer self-review substitute, or proceed with open issues.
- Dispatch parallel implementers without the overlap check or without "NO COMMIT".
- Process waves out of order; commit a wave before all its tasks pass both reviews.
- Make a subagent read the plan file (provide full text), skip scene-setting, or ignore subagent questions.
- Mark a task complete without the commit SHA in `git log`.
- Hand-type the merge/push/deploy cascade instead of `ship.sh land`; skip `finishing-a-development-branch`; skip `learn-from-mistakes`.
- Pause between specs in a multi-spec batch (see batch rule above).

Reviewer finds issues → implementer fixes → re-review until approved. Subagent fails → fix subagent with specific instructions, never fix manually.

## Prompt Templates

- `./implementer-prompt.md` — implementer dispatch.
- `./spec-reviewer-prompt.md` — spec-compliance reviewer dispatch.
- **code-quality-reviewer** skill — quality reviewer invokes `/code-quality-reviewer` with `WORKTREE_PATH`, `BASE_SHA`, `HEAD_SHA`, `WHAT_WAS_IMPLEMENTED`, `TASK`.
- Verification dispatch: describe type + areas inline (no template file).

## Integration

- **plan** — authors request specs for the factory. **using-git-worktrees** — isolation. **finishing-a-development-branch** — landing brain. **tdd** — implementers follow it per task. **factory** — runs a request spec through planning, build, verification, and commit.
- `references/learned-rules.md` — fired-once failure archive, indexed by phase; `learn-from-mistakes` appends there, and any rule reaching fired ≥2 gets promoted into this file's process steps.
