---
name: ship
description: Use when executing implementation plans with independent tasks in the current session
---

# Subagent-Driven Development

Audience: AI coding agents first.

Canonical `/ship` behavior lives in `/home/user/.codex/skills/ship/SKILL.md`.

Execute plan via deterministic Codex wrapper:

```bash
node ~/.claude/workflows/run-plan-codex.js --slug <PLAN_SLUG> --repo <PROJECT_ROOT> --concurrency <N>
```

Do NOT hand-orchestrate waves/subagents from this legacy copy unless diagnosing wrapper HALT output. Default `N`: `4`.

**Why subagents:** Fresh context per task → stay focused. Never inherit session history — provide exactly what's needed.

**Core principle:** wrapper owns worktree setup, task dispatch, review, gate0, commits, integration, and stop conditions.

## When to Use

```dot
digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "ship" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "ship" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
}
```

## The Process

```dot
digraph process {
    rankdir=TB;

    "Create worktree (using-git-worktrees)" [shape=box];
    "Check plan not already implemented" [shape=box];
    "Read plan: extract waves + tasks, create TodoWrite" [shape=box];
    "More waves remain?" [shape=diamond];
    "Wave has 1 task?" [shape=diamond];
    "Dispatch final code reviewer subagent" [shape=box];
    "Determine verification type" [shape=box];
    "Dispatch verification subagent" [shape=box];
    "Verification passes?" [shape=diamond];
    "Dispatch fix subagent, re-verify" [shape=box];
    "Determine push/deploy target" [shape=box];
    "Dispatch push/deploy subagent" [shape=box style=filled fillcolor=lightgreen];
    "Finish branch (finishing-a-development-branch)" [shape=box];
    "Run learn-from-mistakes" [shape=doublecircle];

    subgraph cluster_single {
        label="Single-task wave";
        "Dispatch implementer (commits own work)" [shape=box];
        "Verify commit SHA in git log" [shape=box];
        "Spec review" [shape=box];
        "Quality review" [shape=box];
        "Diff scan" [shape=box];
    }

    subgraph cluster_parallel {
        label="Multi-task wave (parallel)";
        "Verify zero file overlap across wave tasks" [shape=box];
        "Dispatch all implementers in parallel (NO COMMIT)" [shape=box];
        "Wait for all; check files exist" [shape=box];
        "Per-task: spec review → quality review" [shape=box];
        "Controller commits wave" [shape=box];
        "Wave diff scan" [shape=box];
    }

    "Create worktree (using-git-worktrees)" -> "Check plan not already implemented";
    "Check plan not already implemented" -> "Read plan: extract waves + tasks, create TodoWrite";
    "Read plan: extract waves + tasks, create TodoWrite" -> "More waves remain?";
    "More waves remain?" -> "Wave has 1 task?" [label="yes"];
    "Wave has 1 task?" -> "Dispatch implementer (commits own work)" [label="yes"];
    "Dispatch implementer (commits own work)" -> "Verify commit SHA in git log";
    "Verify commit SHA in git log" -> "Spec review";
    "Spec review" -> "Quality review";
    "Quality review" -> "Diff scan";
    "Diff scan" -> "More waves remain?" [label="wave done"];
    "Wave has 1 task?" -> "Verify zero file overlap across wave tasks" [label="no"];
    "Verify zero file overlap across wave tasks" -> "Dispatch all implementers in parallel (NO COMMIT)";
    "Dispatch all implementers in parallel (NO COMMIT)" -> "Wait for all; check files exist";
    "Wait for all; check files exist" -> "Per-task: spec review → quality review";
    "Per-task: spec review → quality review" -> "Controller commits wave";
    "Controller commits wave" -> "Wave diff scan";
    "Wave diff scan" -> "More waves remain?" [label="wave done"];
    "More waves remain?" -> "Dispatch final code reviewer subagent" [label="no"];
    "Dispatch final code reviewer subagent" -> "Determine verification type";
    "Determine verification type" -> "Dispatch verification subagent";
    "Dispatch verification subagent" -> "Verification passes?";
    "Verification passes?" -> "Dispatch fix subagent, re-verify" [label="no"];
    "Dispatch fix subagent, re-verify" -> "Dispatch verification subagent";
    "Verification passes?" -> "Determine push/deploy target" [label="yes"];
    "Determine push/deploy target" -> "Dispatch push/deploy subagent";
    "Dispatch push/deploy subagent" -> "Finish branch (finishing-a-development-branch)";
    "Finish branch (finishing-a-development-branch)" -> "Run learn-from-mistakes";
}
```

## Wave-Based Execution

Plans define waves (see `plan` skill). Each wave is a group of tasks safe to parallelize.

### Reading waves from plan

Extract from the plan's "Wave Plan" table. Group tasks by wave number. Process waves in order.

### Single-task wave

Current sequential flow: implementer commits own work → verify SHA → spec review → quality review → diff scan.

### Multi-task wave (parallel)

**Before dispatching:**
1. Confirm zero file overlap across all tasks in wave. If overlap found → **STOP**, report conflict to user, fix plan before continuing.

**Dispatching:**
2. Dispatch all implementers simultaneously (foreground, `subagent_type: "claude"`, `run_in_background: false`)
3. Each implementer prompt MUST include:
   ```
   PARALLEL WAVE: Do NOT commit. Write files, run tests, return status.
   Return: list of files you modified.
   ```

**After all complete:**
4. Verify all expected files exist on disk
5. For each task sequentially: spec review → quality review (fix loops as normal)
6. Controller commits entire wave:
   ```bash
   git add <all files from all wave tasks>
   git commit -m "feat: wave N — task A, task B, task C"
   ```
7. Diff scan across all wave files together

### Asking implementers questions (parallel wave)

If any implementer in a parallel wave asks a question, pause that agent, answer, re-dispatch. Other agents in wave may continue. Don't commit wave until ALL agents complete and pass review.

## Worktree Setup

Before the pre-flight check, invoke `using-git-worktrees` to create `.worktrees/<branch-name>/`.

Record the `WORKTREE_PATH`. Pass it in every implementer subagent prompt:

```
WORKTREE_PATH: .worktrees/<branch-name>/
All file edits must happen inside this path. cd to it before any work.
```

Spec reviewer and code quality reviewer also receive `WORKTREE_PATH` so they read the right files.

## Pre-Flight: Plan Already Implemented?

Before first dispatch, run:
```bash
git log --oneline HEAD ^main | grep -i "<plan-keywords>"
```
Commits found → tasks already done → mark complete, skip dispatch.

## Model Selection

Use the least powerful model that can handle each role to conserve cost and increase speed.

**Haiku** — docs, i18n, string extraction, localization, boilerplate generation, purely mechanical text tasks.

**Sonnet** — default for implementation. Scaffold, argparse, fixtures, isolated functions, clear specs, 1-2 files. Most tasks are mechanical when the plan is well-specified — use Sonnet.

**Opus** — reasoning-heavy work only: codec correctness, allocator logic, cache-safety invariants, multi-file integration with pattern-matching judgment, debugging complex failures, architecture decisions, and all review tasks.

**Task complexity signals:**
- Docs / i18n / boilerplate → Haiku
- Touches 1-2 files, complete spec, mechanical → Sonnet
- Multi-file with integration concerns → Sonnet (escalate to Opus if blocked)
- Correctness guarantees, invariant reasoning, broad codebase judgment → Opus
- Any review (spec compliance, code quality, final) → Opus

## Verification

After all tasks complete and final reviewer approves, determine verification type from the work done:

**Playwright** — UI/frontend changes, visual components, user flows, form interactions.

**E2E / integration tests** — API endpoints, CLI commands, backend logic, data pipeline changes. Run existing test suite + smoke tests.

**Both** — full-stack changes touching frontend and backend.

Dispatch verification subagent with the appropriate type and specific areas to test based on what was implemented. If verification fails → dispatch fix subagent with specific failures, then re-verify.

## Push / Deploy

After verification passes, determine push/deploy target:

1. Check `wrangler.toml` → Cloudflare Worker → `wrangler deploy`
2. Check `package.json` for `deploy` or `publish` script → run it
3. Check `.github/workflows/` → CI handles deploy → just `git push`
4. Check `Dockerfile` + `docker-compose.yml` → manual process → just `git push`
5. No clear target or ambiguous → `git push` only

**Default: `git push` to GitHub.** Only deploy if target is unambiguous. Never ask user about deploy if unclear — just push.

## After Push/Deploy: Finish Branch + Learn From Mistakes

After push/deploy completes:
1. Invoke `finishing-a-development-branch` inline — auto-merges to main, cleans up worktree (no user prompt)
2. After branch is finished, invoke `Skill("learn-from-mistakes")` inline (not as subagent)

## Handling Implementer Status

**DONE (single-task wave):** Run `git log --oneline -3` to verify commit SHA exists, then proceed to spec reviewer.

**DONE (parallel wave):** Verify expected files exist on disk. No SHA check (controller commits). Proceed to spec review for this task.

**DONE_WITH_CONCERNS:** Read concerns before proceeding. Correctness/scope issues → address before review. Observations (e.g., "file getting large") → note and proceed.

**NEEDS_CONTEXT:** Provide missing context, re-dispatch.

**BLOCKED:**
1. Context problem → provide context, re-dispatch same model
2. Needs more reasoning → re-dispatch with Opus
3. Task too large → break into smaller pieces
4. Plan is wrong → escalate to user

**Never** ignore escalation or retry without changes.

## Per-Wave Controller Checks

**Single-task wave — after implementer commits:**
```bash
git log --oneline -3   # confirm SHA exists before dispatching reviewer
```

**Any wave — after code quality reviewer(s) approve:**
```bash
git diff HEAD~1..HEAD -- <changed-src-files>   # scan for dead vars, unused imports, dead blocks
```
If issues found → dispatch fix subagent with specific findings.

**Multi-task wave — file overlap check before dispatch:**
```bash
# Compare file lists from plan tasks in this wave — any duplicates = conflict
```
Hard stop on overlap. Never dispatch parallel agents to same file.

## Prompt Templates

- `./implementer-prompt.md` — dispatch implementer subagent
- `./spec-reviewer-prompt.md` — dispatch spec compliance reviewer subagent
- **code-quality-reviewer** skill — dispatch subagent, invoke `/code-quality-reviewer` first, pass `WORKTREE_PATH`, `BASE_SHA`, `HEAD_SHA`, `WHAT_WAS_IMPLEMENTED`, `TASK`
- `./verification-prompt.md` — dispatch pw-testing or e2e verification subagent
- `./push-deploy-prompt.md` — dispatch push/deploy subagent

## Red Flags

**Never:**
- Start on main/master without explicit user consent
- Skip reviews (spec compliance OR code quality)
- Proceed with unfixed issues
- Dispatch parallel implementers without verifying zero file overlap first
- Dispatch parallel implementers without telling them "NO COMMIT"
- Commit a parallel wave before all tasks in that wave pass spec + quality review
- Process waves out of order (wave N before wave N-1 is fully done)
- Make subagent read plan file (provide full text instead)
- Skip scene-setting context
- Ignore subagent questions
- Accept "close enough" on spec compliance
- Skip review loops
- Let implementer self-review replace actual review
- **Start code quality review before spec compliance is ✅**
- Move to next task while either review has open issues
- Mark task complete without verifying commit SHA exists in `git log`
- Deploy without a confirmed unambiguous deploy target — just push
- Skip worktree setup — all implementation must happen in the worktree
- Skip finishing-a-development-branch — never leave feature branch unmerged/unresolved
- Skip learn-from-mistakes after push/deploy

**If reviewer finds issues:** implementer fixes → reviewer reviews again → repeat until approved.

**If subagent fails task:** dispatch fix subagent with specific instructions, don't fix manually.

## Integration

**Required workflow skills:**
- **plan** — creates the plan this skill executes
- **using-git-worktrees** — sets up isolated worktree before first task
- **finishing-a-development-branch** — merges into main and cleans up after verification

**Subagents should use:**
- **tdd** — subagents follow TDD for each task
- **code-quality-reviewer** — quality review subagents invoke this skill for the review protocol

**Optional:**
- **executing-plans** — alternative for parallel session execution