# Dev Ship

> Use with /dev-ship to run define→build→verify→refactor unattended.

- Skill: `airmile/dev-ship` (Agent Skill, multi-file: 56 files)
- Install (CLI): `npx skillmds@latest add airmile/dev-ship`
- Raw SKILL.md: https://api.skillmd.com/api/skills/airmile/dev-ship/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AirMile (https://skillmd.com/u/airmile)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/airmile/dev-ship

---


# Ship (auto-mode pipeline)

Runs the full dev pipeline — **define → build → verify → refactor** — in one chat. Heavy work
runs in isolated inline agents (context stays clean); only human interaction (define choices,
manual tests) happens in the main chat; the autonomous PHASE 1–4 stretch runs as background
Workflows launched by the main chat, which wakes on their task-notifications. `dev-ship` is the
**standalone** dev pipeline: it carries
its own vendored copies of the four phase workflows under `references/dev-{define,build,verify,refactor}/`
and drives them internally — there are no separate `/dev-define`…`/dev-refactor` skills anymore.

**Trigger**: `/dev-ship` or `/dev-ship {feature-name}`

## When not to use this

- **1-3 files, no net-new surface** — `/dev-tweak`. The plan-approval gate (PHASE 0 Step 4b) checks
  this itself against the completed define draft and offers the handoff when nothing escalates — see
  § Design's de-escalation-gate note below — but catching it before define opens the interview is
  cheaper still.
- **`PAGE` / `COMPONENT` type** — `/design-ship` (`phase-0-define-classify.md § Step 1` already skips
  these on no-arg resolution).
- **A parked run with manual items still open** — resume via `/dev-manual`, not a fresh `/dev-ship`.

## Design

- **One human touchpoint** (PHASE 0 define + plan-approval gate); then hands-off except the
  conditional PHASE 3 manual round **and its fix-plan gate**. Merge happens at the end of PHASE 4.
  `verificationProfile` is advisory; AGENT 2's `remainingManualItems` is authoritative for PHASE 3.
- **De-escalation gate** — the plan-approval gate (Step 4b) runs the size-gate criteria from
  `shared/TWEAK-DISCIPLINE.md § Size gate` against the completed draft; none firing offers a fourth
  gate outcome, handoff to `/dev-tweak`, alongside Accept/Reject/Abort. See
  `references/phase-0-fresh-define.md § Step 4b` and `shared/TWEAK-DISCIPLINE.md § De-escalation gate`.
- **Difficulty escalation** — any main-chat decision point that turns out genuinely hard (triggers
  in `shared/PLAN-MODE.md § Difficulty escalation`: multi-approach architecture calls, twice-failed
  fixes, plan-invalidating surprises — e.g. choosing recovery after a `"failed"` workflow return)
  enters plan mode for the thinking, exits with the decision, and continues execution. Backstop
  only — the catalogued PHASE 0/3/4 gates keep their own entries.
- **Build and verify are separate agents/contexts** (fresh verify = adversarial). **`.project/` is
  shared on disk, context isolated** — sequential, one writer, re-read `.project/` after every agent
  return. See `references/agent-verify.md` / `references/non-interactive-contract.md`.
- **Agents run via the Workflow tool** (PHASE 1+2, PHASE 4), launched directly by the main chat;
  prompts passed **by pointer, never inline**; results schema-validated. Both workflow scripts
  **normalize `args`** at the top (`typeof args === "string" ? JSON.parse(args) : args`) — a runtime
  may deliver `args` as a JSON string. The Agent-tool path in each `agent-*.md` is the **fallback**
  (model override only there — it cannot set effort) — a background subagent cannot call the
  Workflow tool (not reachable even via `ToolSearch`), so the fallback is run by the main chat
  itself, never by an intermediate orchestrator agent.
- **Cross-Agent Execution (Antigravity / Cursor / Copilot)**: When running in an environment without background text-agent tools (e.g. missing `Workflow` or `invoke_subagent`):
  - **Orchestration Degradation**: You MUST fall back to "Inline Execution Mode" per `shared/SKILL-PATTERNS.md`. Execute the phases sequentially in the active session, assuming the personas of AGENT 1 (build) and AGENT 2 (verify) yourself. Do not block or crash waiting for a background tool.

  | Agent                 | Model    | Effort   | Why                                                                   |
  | --------------------- | -------- | -------- | --------------------------------------------------------------------- |
  | AGENT 1 build         | `sonnet` | `high`   | contract-driven TDD — feature.json + tests bound the work             |
  | AGENT 2 verify        | `sonnet` | `high`   | one independent adversarial judgment; fresh context is the backstop   |
  | AGENT 3 refactor      | `sonnet` | `medium` | test-guarded (revert-on-red), low risk                                |
  | AGENT S scanners      | `sonnet` | `medium` | pattern-driven read-only fan-out                                      |
  | Security triage       | `sonnet` | `high`   | judgment over scanner findings, no test backstop                      |
  | AGENT F fix (PHASE 3) | `sonnet` | `high`   | plan-bound fixes; the round gate did the thinking (Opus in plan mode) |

  Every dev-ship agent and workflow runs on `sonnet`. The only `opus` in the pipeline is the
  independent **second-opinion consult** (`shared/SECOND-OPINION.md`) — a separate authorization
  class, not part of this matrix.

> Full rationale (the 85/15 one-flow design, why fresh verify contexts, checkpoint durability,
> `.project/` sharing, prompt-by-pointer): `references/design-rationale.md`.

## Workflow

**Phase tracking** — first action of the skill: call `TaskCreate` (or native task tool / progress signal) with these 6 items
(status `pending`), then use `TaskUpdate` (or progress output) to set each phase to `in_progress` at the start and
`completed` at the end. During context compaction the task list remains visible.

**Durable checkpoint (pause/resume across sessions)** — beyond the compaction-safe `TaskCreate` list,
the run is mirrored to `.project/session/ship-{feature}.json` at every phase boundary via
`ship-checkpoint.js`. **The main chat is the single writer throughout** (worker subagents never
touch it — contract rule 1). Schema, write points 0–5, and the board's **parked** row:
`shared/SHIP-CHECKPOINT.md`; resume detection, fast-path direct-resume, and orphan-cleanup:
`shared/SHIP-RESUME.md`. This skill follows both — the per-phase field patches below are the only
checkpoint detail restated here. Note the PHASE 2→3 boundary is a **deliberate handoff stop**: park,
then a fresh-session resume when manual items remain.

1. PHASE 0: Define + Classify + Auto-derive technique plan
2. PHASE 1: Build (AGENT 1)
3. PHASE 2: Auto-verify (AGENT 2)
4. PHASE 3: Manual tests + Completion
5. PHASE 4: Refactor (AGENT 3) [+ optional security AGENT S] + Finalize/merge
6. PHASE 5: Report

### PHASE 0: Define + Classify + Auto-derive technique plan

> **Todo**: Track phase progress with native task tools if available, or print one line at every PHASE N → PHASE N+1 transition below
> (e.g. "PHASE 1 → PHASE 2: build done, auto-verify starting") so progress remains visible across phases.
> **Check for a resumable run before seeding tasks** (the resume path is deliberately cheap — it
> skips the fresh-run PHASE 0 file entirely):
>
> 1. **Resume check first.** If `/dev-ship` was called with an **explicit** `{feature}` arg and an
>    open checkpoint exists — `main_root=$(git worktree list --porcelain | head -1 | awk '{print
$2}'); test -f "$main_root/.project/session/ship-{feature}.json"` succeeds (**always resolve
>    `main_root` first**: cwd is commonly already inside the feature worktree, where
>    `.project/session/` is deliberately not shared, so a bare relative `test -f` silently misses
>    an existing checkpoint) → Read `.claude/skills/shared/SHIP-RESUME.md` and follow it. The fast
>    path jumps straight to the
>    checkpoint's recorded phase (no prompt when explicit arg + matching pipeline + running + ≤ 24h)
>    — so on the common parked-resume you land in PHASE 3 **without** loading
>    `phase-0-define-classify.md`. **Seed `TaskCreate` per its § 3 re-seed step**: every phase in
>    `completedPhases` created `completed`, the rest `pending` — never create all 6 as `pending`
>    first and then flip the already-done ones. (Only a "Restart fresh" choice falls through to
>    step 2.)
> 2. **Fresh / no-arg / no checkpoint** → call `TaskCreate` with the 6 phase items (see above), mark
>    PHASE 0 → `in_progress` via `TaskUpdate`, then Read
>    `.claude/skills/dev-ship/references/phase-0-define-classify.md` and follow it from Step 0 (it
>    resolves the feature name — needed before a no-arg resume check — then delegates resume
>    detection to `SHIP-RESUME.md` and runs preflight + define for a genuine fresh run).

Resolves the feature, runs `dev-define` inline (interactive, main chat) when it is not yet
DEFINED, then computes the advisory `verificationProfile` and **auto-derives** the technique plan
(refactor lenses + relevant OWASP scanners) from the feature's signals — **no technique menu, no
policy prompt**. define is the only human touchpoint; the derived `refactorLenses`/`securityDeep`
become parameters for AGENT 3 / the trigger for AGENT S and are stored in memory for the later phases.

**A genuine approval gate.** The entire define thinking-block (interview → requirements → architecture →
classify → technique-derivation) runs **inside plan mode** — bookkeeping is hoisted before it, all
durable writes after it (gate-accept). This is not a model-routing device: the session model is `opus`
throughout; the value is the write-stop and the reviewable plan artefact, not a model switch.
Confirmations are **not** asked twice — the interview keeps only genuine
decision prompts (feature pick, design forks, split), and everything else (scope, design sketch,
seed/backlog impact, pages) is reviewed **once** at the gate, where reject loops back to revise.

PHASE 0 ends with the **plan-approval gate** (Step 4b of the reference): define is **already** in plan
mode, so the gate just writes the plan file (its appendix holds the complete feature.json draft) and
`ExitPlanMode` presents it — on **accept** the draft is extracted to `feature.json` (it is not written
before this) and the sync runs; **reject** stays in plan mode and loops
back to revise. A re-invoked feature that is already `DEFINED` means a prior run already accepted the
gate, so it skips define, plan mode, and the gate, flowing straight to build (the resume-recovery path).

PHASE 3 has a **second, conditional** plan-mode block (the fix-plan gate, `references/fix-round.md`)
with the same hoisted-bookkeeping shape — findings are collected and checkpointed first, the round's
fix design runs in plan mode (Opus), then `ExitPlanMode` gates dispatch. Unlike define, its input (the
findings ledger) is already durable before entry, so a cross-session death during the gate re-enters
the gate without re-running the walkthrough.

It also assembles **`SHIP_CONTEXT`** (Step 6 of the reference) — one project-context block built
here from the external `shared/PROJECT-CONTEXT-LOAD.md` (build profile) + `shared/LEARNINGS-LOAD.md`
(scoped). This block is passed as a **per-agent slice** (see the reference's Per-agent slices table) into
each PHASE 1/2/4 agent's **pointer file** — AGENT S gets `OWASP_CONTEXT` instead — so no agent
re-bootstraps its own context; the main chat is the context-hub. Each `agent-*.md` § Spawn documents
the pointer-file template that carries this slice.

### PHASE 1–4: Orchestration (main chat, background workflows)

> **Todo**: mark PHASE 0 → `completed`, PHASE 1 → `in_progress`. Rewrite the board live-signal:
> `echo '{"skill":"build"}' | node ~/.claude/scripts/ship-checkpoint.js signal {feature}`,
> and **update the checkpoint** (`shared/SHIP-CHECKPOINT.md` atomic write): `phase: "PHASE 1"`,
> `completedPhases: ["PHASE 0"]`.
> Read `.claude/skills/dev-ship/references/agent-build.md` and
> `.claude/skills/dev-ship/references/agent-verify.md` (their **§ Spawn → Pointer file** templates
> only — do **not** read `non-interactive-contract.md` or the `references/prompts/*` bodies). **Write
> each pointer + SHIP_CONTEXT-slice file** — `.project/session/ship-prompts/{feature}-build.txt` and
> `-verify.txt` — keeping the literal `{worktreePath}` placeholder in the verify file, and pass the
> **paths** (never inline). This stays main-chat work: the main chat holds `SHIP_CONTEXT` in memory
> from PHASE 0.
>
> Read `.claude/skills/dev-ship/references/orchestration.md` and follow it — launch the PHASE 1+2
> workflow (§3) with the two pointer paths above. **End the turn** with a one-liner ("Shipping
> `{feature}` in the background — I'll report when it returns.") — no further tool calls.
>
> **On workflow notification**, branch on the returned `status`:
>
> - **`"complete"`** → proceed to PHASE 5.
> - **`"parked"`** (manual items remain) → Read `references/orchestration.md § 3` for the exact
>   handoff template and print it verbatim (translated per LANGUAGE.md) — no further tool calls.
>   PHASE 3/4/5 run in a fresh session.
>   **Same-session escape hatch**: if the user replies "continue here" (or equivalent), continue
>   with `orchestration.md § 4` (PHASE 3 completion) inline in this chat instead of parking.
> - **`"failed"`** → **one bounded silent auto-retry**: if `{build|verify}.failedAt` names
>   infrastructure death before any worktree/test ran (e.g. "agent died (null return)", an
>   API/stream error) — never a test failure or a code error — relaunch the same Workflow once
>   without asking. A second failure of any kind (including a second infra death) always falls
>   through below; never retry more than once per phase12/phase4 launch. Otherwise, or after the
>   bounded retry also fails, print, depending on `failedPhase`, then proceed to PHASE 5's failure
>   path:
>   - `"build"`: "Build failed at `{build.failedAt}`, worktree intact at `{build.worktreePath}` —
>     re-run `/dev-ship {feature}` to retry, or go straight to root-cause analysis via
>     `references/debug-round-heavy.md` (non-ledger entry)."
>   - `"verify"`: "Auto-verify failed at `{verify.failedAt}`, worktree intact — re-run
>     `/dev-ship {feature}` to retry, or go straight to root-cause analysis via
>     `references/debug-round-heavy.md` (non-ledger entry)."

You run both agents sequentially in isolated contexts (model/effort matrix in § Design), launch
PHASE 4's refactor/security/finalize when no manual items remain, and continue to PHASE 5. Full
mechanics: `references/orchestration.md`. Full agent behaviour:
`agent-build.md` / `agent-verify.md` / `agent-refactor.md` / `agent-security.md`.

### PHASE 3: Manual tests + Completion (MAIN CHAT — fresh-session manual round)

> **Todo**: mark PHASE 3 → `in_progress` (PHASE 1+2 were already flipped on the workflow return).
> Rewrite the board live-signal: `echo '{"skill":"verify"}' | node ~/.claude/scripts/ship-checkpoint.js signal {feature}`
> (cwd-in-worktree safe — the script resolves main-root itself, same as the checkpoint write), and
> update the checkpoint `phase: "PHASE 3"`.
> You arrive here with non-empty `remainingManualItems`, normally **from a fresh session** (the
> `"parked"` handoff above) via the reference's **Resume entry** note — re-enter the worktree +
> relaunch the app first — or from the same-session **escape hatch** (the user chose to continue
> here instead of parking). Either way re-arm the live signal, then proceed: Read
> `.claude/skills/dev-ship/references/phase-3-manual-finalize.md` and run the manual walkthrough
> then the completion (DONE write).

Manual tests run in the main chat so `AskUserQuestion` reaches the real user. The reference owns the
full routing — item-by-item walkthrough + interview close → findings ledger (checkpoint) →
conditional round-level fix-plan gate (mirrors PHASE 0's gate) → fix dispatch via
`references/workflows/ship-fix.js` + inline mix → re-check round → regression re-check. On all-green
complete the feature (DONE write) and **stay on the feature branch — do not merge yet** (§ 5 leaves
the worktree itself, right before refactor); finalize/merge runs at the end of
PHASE 4 so refactor commits land on the feature branch. **No refactor/finalize until failed items
pass.** Once complete, continue per `references/orchestration.md` (the checkpoint's `route`
subcommand sends you straight to PHASE 4) and handle its notification as described in § PHASE 1–4
above.

### PHASE 5: Report

> **Todo**: Read `.claude/skills/dev-ship/references/phase-5-report.md` and follow it — shared with
> `/dev-manual`'s MANUAL 3, the only difference being which phase-tracking unit gets marked
> `in_progress`/`completed` (PHASE 5 here).