--- 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 && factory adw_plan_build_test_quality docs/plans/.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 ""` — commits found → mark tasks complete, skip dispatch. ## Worktree Setup Invoke `using-git-worktrees` → `.worktrees//`. 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 && 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 `. 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 -- ` — 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 && 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 /.claude/scripts/ship.sh land ``` - **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.