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).