ship

/ship — the Shipwright conductor

You conduct one change through the Shipwright Method. Judgment is yours: proposing the tier, invoking executors, recording evidence, applying degradations. The hooks (orient, PR gate, merge gate, recorder, nudge) enforce the deterministic edges — work WITH them, never around them.

Canonical references: The Method spec defines the loop and tiers; tier-rubric.md (this directory) guides classification; degradation.md (this directory) maps missing touchpoints to fallbacks.

State

Per-branch work-state: .claude/shipwright/<branch-slug>.json (slug = branch with / → -). Repo config: .claude/shipwright/config.json. Both are committed — they are the team-visible audit trail.

Work-state schema (create exactly this shape):

{
  "feature": "<short human description>",
  "tier": "trivial | standard | major",
  "issue": "<tracker id or null>",
  "branch": "<git branch>",
  "pr": { "url": null, "merged_at": null },
  "phases": {
    "brainstorm":       { "done": false, "evidence": null },
    "plan":             { "done": false, "evidence": null },
    "plan_gate":        { "done": false, "evidence": null },
    "implement":        { "done": false, "evidence": null },
    "self_verify":      { "done": false, "evidence": null },
    "internal_review":  { "done": false, "evidence": null },
    "open_pr":          { "done": false, "evidence": null },
    "automated_review": { "done": false, "evidence": null },
    "address":          { "done": false, "evidence": null },
    "merge":            { "done": false, "evidence": null }
  },
  "meta": { "created_at": "<ISO8601>", "last_nudge_session": null }
}

Three iron rules:

1. Never trust your memory of phase status over the file.
2. Never trust the file over git/gh — observable reality wins. On every /ship entry, reconcile: branch exists? PR open/merged? Design/plan docs present? Update the file to match reality and say what you fixed.
3. evidence is a pointer, not prose: a file path, a test summary line ("vitest: 42 passed"), a PR URL, a bot verdict line.

Skip convention: phases not required for the tier are recorded {"done": true, "evidence": "skipped — not required for tier"} at classification time, so "first not-done phase" is always the true next step.

Procedure

1. Orient

Read the work-state for the current branch. If none exists, list actives in .claude/shipwright/ and ask: resume one of these, or start new work? Reconcile per iron rule 2 before proceeding.

2. Classify (new work only)

• Clarify what's being built if ambiguous (one or two questions max — the brainstorm phase does the deep exploration).
• Propose a tier using tier-rubric.md. State the tier and what it requires. The user confirms or overrides — their call is final.
• Create the branch if needed (worktree preferred — superpowers:using-git-worktrees), then the work-state file (apply the skip convention).
• First run in a repo: create config.json first. Probe what's probeable; ask only the rest:

{
  "touchpoints": {
    "tracker":        { "kind": "linear | jira | github | none", "detail": "<team key etc>" },
    "second_opinion": { "kind": "codex | none" },
    "arch_gate":      { "kind": "action | none", "detail": "<workflow filename>" },
    "deploy":         { "kind": "compose | k8s | manual | none" }
  }
}

Probes: command -v codex (second_opinion), gh auth status (PR flow sanity), ls .github/workflows/ | grep -i 'architect\|review' (arch_gate). Ask the user about tracker and deploy.

3. Conduct

For each phase in order, skipping ones already done: announce the phase, invoke its executor, then record {done: true, evidence}:

Phase	Executor	Evidence looks like
brainstorm	superpowers:brainstorming	path to the design/spec doc (or "design agreed inline: " for standard tier)
plan	superpowers:writing-plans	path to the plan doc
plan_gate	detect-overengineering, then codex-plan-review (if second_opinion configured)	"overeng: N findings applied; codex: "
implement	superpowers:executing-plans or superpowers:subagent-driven-development, with superpowers:test-driven-development	"plan tasks 1-N complete @ "
self_verify	superpowers:verification-before-completion	the actual check output summary ("tests: X passed; build: clean")
internal_review	/code-review always; on standard/major also superpowers:requesting-code-review + project reviewer roster if present	"code-review: N findings, M fixed"
open_pr	/pr (attach tracker issue if configured: id in branch name / PR body)	PR URL (the recorder hook also captures it)
automated_review	trigger the repo's bots if needed, then reading-bot-pr-reviews	"codex: clean; SAR: severity 2 — addressed"
address	superpowers:receiving-code-review, /pr-fix loop	"all P1/P2 addressed @ " or "no findings"
merge	superpowers:finishing-a-development-branch	merged PR URL (the recorder hook captures merged_at)

Rules of conduct:

• ONE phase at a time; finish and record before starting the next.
• Optional phases for the tier (e.g. plan_gate on standard): propose, let the user skip; if skipped record the skip convention string.
• If a phase's executor skill is unavailable, say so and do the phase manually at the same standard — never silently skip.
• The gates will block gh pr create / gh pr merge if required phases aren't recorded. If a gate blocks you, the fix is to DO the missing phase, not to edit the work-state to true.

4. Degrade gracefully

At each touchpoint phase, consult config.json and degradation.md. State the degradation once when it applies ("no second-opinion reviewer configured — plan_gate = detect-overengineering only"), record evidence accordingly, move on. Never hard-fail on a missing touchpoint.

5. Close

When merge is recorded: archive the work-state to .claude/shipwright/archive/<slug>-<YYYY-MM-DD>.json (move the file), commit it, and report the loop one line per phase with evidence. If deploy/tracker add-ons are configured, prompt: "Deploy & confirm? / Move to Done?" — execute on yes.

Resuming

Sessions die; the file survives. On any /ship entry mid-loop: orient (step 1), state where the work stands ("phase 6/10, internal_review next"), and continue from the first not-done phase. The SessionStart hook will have surfaced active work; trust the file + reality reconciliation, not conversation memory.