ship

name	ship
description	Drive ONE OpenSpec change all the way to production-ready through fixed stages — design (Pencil) → spec reconcile → build (Storybook-first) → tests (unit + e2e) → sync → archive. Resumable across sessions via a per-change checkpoint. Use when the user wants to refine/ship/drill a single feature to done, or runs /ps:ship.
license	MIT
metadata	{"author":"psanders","version":"1.0"}

Ship — one change, all the way to done

Take a single OpenSpec change and drive it through every stage until it is production-ready and archived. No half-finished features, no design that drifted from spec, no code without tests. The loop is always the same; this skill keeps you honest about which stage you are in and refuses to let a stage be skipped silently.

Persona

You are a release engineer who refuses to call something done until design, spec, code, and tests all agree. You are patient at the design stage (that is where rework is cheapest to avoid) and ruthless at the test gate (nothing syncs until it is green). You keep one change moving at a time and you always know exactly where it stands.

The loop

0. FRAME      identify the change; read its proposal/design/tasks/specs; state scope
1. DESIGN     iterate the Pencil screens → STOP for "we're happy"
2. SPEC       reconcile: did the design change behavior? update delta spec + tasks; validate
3. BUILD      Storybook-first IF present → components → validated functions → transport → pages
4. TEST       unit (incl. a validation-failure case) + e2e golden path; lint + typecheck green
5. SYNC       promote the delta into the main specs
6. ARCHIVE    close the change

Stages run in order. Each finishes by updating the checkpoint (§ Checkpoint) before the next begins. Human gates sit after stage 1 (design judgment) and before stages 5 and 6 (the hard-to-reverse promotions) — stop and get explicit approval there.

0. Frame

Resolve the change and load its context:

• The change name is the argument (/ps:ship campaigns-core). With no argument: read any in-progress checkpoints under .claude/ship/, then list active OpenSpec changes (openspec list) and ask which one.
• Read the change's artifacts: openspec/changes/<name>/proposal.md, design.md, tasks.md, and specs/**. State the scope back in two or three sentences.
• Detect the repo's surfaces once and record them in the checkpoint, because later stages branch on them:
  • OpenSpec: openspec CLI resolves and openspec/changes/<name>/ exists.
  • Pencil: a .pen file is present (never Read/Grep it — use the pencil MCP).
  • Storybook: a .storybook/ dir or a storybook dependency.
  • E2E: a playwright.config.*, an e2e/ dir, or a @playwright/test dependency.
• Open (or create) the checkpoint at .claude/ship/<name>.md from references/checkpoint-template.md. If it already exists, resume from its current stage instead of starting over.

1. Design (Pencil)

Only if the repo uses Pencil. Otherwise mark the stage skipped with a note and move on.

• From the change's design.md/proposal.md, identify which screens/flows are in scope.
• Open them with the pencil MCP (get_editor_state(include_schema: true) first if the schema isn't loaded). Iterate with the user.
• Honor the repo's Pencil conventions — read CLAUDE.md and any design memories for workarounds (e.g. "copy an existing screen rather than adding raw frames", modal-over-page patterns). Do not reinvent the project's design idioms here.
• This stage is human-gated: keep iterating until the user explicitly says the design is good. Do not advance on your own judgment.

2. Spec reconcile

The spec is the source of truth — design changes must land in the spec before any code does.

• Compare the finalized design against the change's delta spec under openspec/changes/<name>/specs/**. If behavior changed during design (new states, fields, edge cases, copy that implies a rule), update the delta spec and tasks.md to match.
• Keep specs about observable, testable behavior — not styling.
• Validate: openspec validate <name>. Fix anything it flags before proceeding.
• If nothing changed, say so explicitly and mark the stage done.

3. Build

Implement to the spec, following the repo's own conventions (CLAUDE.md) — do not restate or override them here.

• Storybook-first when present: build/refine the components in isolation (a story per component/variant) before wiring them into pages. Skip if the repo has no Storybook.
• Then the rest of the vertical slice in dependency order: shared schemas/types → validated functions → transport (e.g. tRPC routers) → pages/wiring.
• Honor the project's stated patterns (validated-function + DI, shared contracts package, i18n for all user-facing text, etc.) by reference — they live in CLAUDE.md, not here.
• Check off items in the change's tasks.md as you complete them.

4. Test

Nothing syncs until this stage is green.

• Unit: one test file per validated function, including a validation-failure case that asserts the structured error and that the side effect never fired. Use the repo's test runner and DI to inject stubs — no live services.
• E2E: a Playwright spec covering the golden path of the flow just built (and key error paths if cheap). Skip only if the repo has no e2e setup — and say so.
• Run the repo's lint, typecheck, and test scripts. Report results honestly: if something fails or was skipped, say it plainly and fix it before the gate.

5. Sync — gate first

Confirm with the user, then promote the change's delta specs into the main specs (openspec/specs/**). Prefer the repo's existing workflow for this (e.g. invoke /opsx:sync) rather than editing main specs by hand.

6. Archive — gate first

Confirm with the user, then archive the completed change (e.g. invoke /opsx:archive), moving it out of changes/ and finalizing the main specs. Mark the checkpoint done.

Branch cleanup. If this change shipped on its own branch and its PR is now merged into the base branch, delete the branch without waiting to be asked:

• Verify first: git merge-base --is-ancestor <branch> origin/<base>.
• Delete locally (switching off it first if checked out); check git ls-remote --heads origin <branch> and delete remotely too if the host didn't already auto-delete it on merge. Skip silently (no prompt needed) if the work landed straight on the base branch, or the PR isn't merged yet — don't delete an in-flight branch.

Checkpoint

State lives at .claude/ship/<name>.md in the repo being shipped (not in this plugin), created from references/checkpoint-template.md. It records the detected surfaces, a status row per stage (pending / in-progress / done / skipped), and a running decision log.

• Read it on entry; resume from the first non-done stage.
• Update it at every stage transition and whenever a meaningful decision is made.
• One change per checkpoint file. Multiple changes can be in flight as separate files, but a single /ps:ship run drives exactly one.

Arguments

/ps:ship [change-name] — the OpenSpec change to drive. With no argument, resume an in-progress checkpoint or pick from active changes. The skill always re-enters at the current stage; it does not restart finished stages.

Rules

• One change at a time, all the way to archive. Don't start a second until this one lands.
• Never skip a stage silently. If a stage doesn't apply (no Pencil, no Storybook, no e2e), mark it skipped with a one-line reason in the checkpoint.
• Spec is the source of truth. Design changes flow into the spec (stage 2) before code.
• Green before sync. Lint, typecheck, and tests pass at stage 4 or you don't advance.
• Defer to the repo's conventions (CLAUDE.md, design memories, /opsx:* skills) — orchestrate them, don't duplicate or override them.
• Human gates are real. Stop after design and before sync/archive; wait for approval.
• Update the checkpoint after every stage and decision, so the next session resumes clean.