ship

Orchestrate the full spec-to-commit pipeline for the feature described in $ARGUMENTS or in .claude/input/.

--dry-run mode: If $ARGUMENTS contains --dry-run, run only Steps 1–2 (questions + spec), then print a scope report and stop. No branch, no implementation, no commits. Use this to preview complexity and scope before committing to a full pipeline run.

--no-finalize mode: If $ARGUMENTS contains --no-finalize, run the full pipeline (spec → implement → review → fix → commit) but skip Step 7 entirely — neither gate nor push nor state change. The feature stays on its branch with all commits applied and checks passing, but is not merged to main and the work item stays in its current state. Used by /fleet to manage merges centrally.

--auto-finalize mode: If $ARGUMENTS contains --auto-finalize, skip the Step 7a finalize gate and go straight to push + state transition. Use only when you trust the pipeline output without a manual smoke-test (doc-only commits, trivial refactors, hotfixes under time pressure). Default is the gated flow — the user sees a summary and must confirm before anything is pushed or the ticket state changes.

Architecture: The main session is a thin orchestrator only — it never reads code files or accumulates implementation context. Each phase runs in a dedicated subagent with a clean context. The spec file, review file, and git diff are the handoff mechanism between phases.

Progress updates: After each subagent returns, print a one-line status update so the user can track progress. Use this format:

✓ Step N — <phase> complete. <key detail from subagent summary>

Examples: ✓ Step 2 — Spec complete. 7 files, 3 new. · ✓ Step 3 — Implementation complete. All checks pass. · ✓ Step 4 — Review: pass with fixes (2 major). · ✓ Step 4 — Fix cycle 1 complete. 2/2 issues resolved.

Main session (orchestrator — reads summaries only)
  ├── Step 0: branch setup              →  creates ticket branch (or stays on current branch)
  ├── Step 0b: ticket resolution        →  loads work item + comments from tracker (if configured), sets state
  ├── Step 1b: historical patterns      →  reads metrics-pipeline.csv → builds spec guidance
  ├── Subagent A: spec          [opus]  →  writes .claude/specs/<name>.md (informed by patterns)
  ├── Step 2b: decision review          →  reads spec "Decisions made by Claude" → user approval
  │
  ├── Subagent B: implement     [opus]  →  single subagent, returns summary
  ├── Subagent C: review        [opus]  →  writes .claude/reviews/<name>-review.md
  ├── Subagent D: fix  [opus if rework, sonnet if fixes]→  loop back to C
  ├── Step 4b: lesson graduation        →  graduates mature lessons → CLAUDE.md
  ├── Step 4c: integration check [opus] →  cross-phase glue review (phased only)
  ├── Step 5: final verify              →  typecheck → lint → tests → build
  ├── Step 5b: changelog entry          →  writes changelog/<branch>.md (per-ticket, merge-conflict-free)
  ├── Subagent E: commit        [sonnet]→  atomic commits on feature branch
  ├── Step 6b: tracker feedback          →  posts non-obvious context to work item (sparingly)
  ├── Step 7a: finalize gate            →  show summary + test hints, wait for user confirm
  └── Step 7b: push + finalize          →  pushes branch to origin, updates ticket state

---

Step 0 — Branch setup (orchestrator)

Skip this step entirely if --dry-run is set — dry-run never creates branches.

Before doing anything else:

1. Read project branch conventions: Check if .claude/rules/branch-management.md exists. If it does, read it and note the branch naming convention. This determines how the branch will be named in step 0.4 below.
2. Check the current branch with git branch --show-current
3. If already on a feature branch (not main or master), stay on it — this is the working branch. Note its name. Try to parse it for a ticket ID (see branch-management.md for the pattern). Do NOT switch to main to create a new branch. Create a checkpoint from the current HEAD: git branch checkpoint/<spec-name>
4. If on main or master and the project requires a ticket-based branch name (from branch-management.md), set branch_pending = true — defer branch creation until after Step 1 where the ticket metadata will be collected. If no project convention exists, run: git checkout -b feat/<spec-name> where <spec-name> is derived from $ARGUMENTS or the most recently modified file in .claude/input/. Then create checkpoint: git branch checkpoint/<spec-name>
5. Confirm the branch (or note that it is pending) — all subsequent subagent commits will land here