/ship

What it does

Reads git status, git diff, and git diff --cached. Categorises changes. Auto-updates relevant docs itself instead of just asking. Validates every  citation in docs/** is still accurate. Drafts a why-focused commit message. The outgoing diff is read by a fresh-context drift-hunter review (below) before it lands.

When to use

Before every commit that touches multiple files, especially after sessions with:

Schema changes
API additions/modifications
External service integration
Design choices
Non-obvious bug fixes

Smart doc updates

When routes, components, or schema change, /ship offers to update the relevant doc itself:

/api/invite changed — update docs/api.md?

Preview:
  ### POST /api/invite (updated)
  Rate limit: 5 requests/min/user (429 on exceed)
  <!-- src: app/api/invite/route.ts:8-65 -->

Add to docs/api.md? (y/n/edit)

Citation validator

Walks every docs/**.md and re-checks each  marker. Flags:

Files that are gone
Line ranges out of bounds

Doesn’t block commit — just warns.

Adaptive checklist

Skips items that don’t apply. Only asks about the things your diff actually touched:

Code changed → run tests / type checker / linter
API route changed → update docs/api.md (auto-offered above)
Schema changed → migration tested? docs/database.md updated? backfill plan?
External service added → docs/integrations.md updated?
Non-obvious bug fixed → add to KNOWN-ISSUES.md with prevention rule
Gap shipped → mark shipped YYYY-MM-DD (commit: <hash>) in docs/*-GAPS.md

Commit message drafting

Reads the last 5 commit messages to match your project’s style, then drafts:

<type>: short summary in imperative mood

Why: <1-2 sentences — business or technical reason>
What: <terse list if multi-file>

Closes: <issue ref if any>

Focuses on why, not just what. Does not add AI attribution unless your project already uses it.

Drift-hunter review (fresh context)

Before the commit lands, the outgoing diff goes to a fresh-context reviewer — a Claude subagent that never saw the code being written — the review half of the pre-code loop:

If /before wrote a fresh, valid stamped spec for this task (base commit is an ancestor of HEAD, written within the last day), the reviewer reads it and hunts for where the diff drifted from the approved plan — plus any correctness, security, or data bug. Findings are classified BLOCKER or DEBT.
No fresh spec? The review falls back to a generic correctness pass and says plainly that drift was not checked — it never claims a review that didn’t happen.
On findings, the writer adjudicates each one (fixes the real ones, may rebut the reviewer once), then surfaces the outcome. The loop is bounded at three rounds. You approve the final result; the reviewer advises, it never silently overrides you.
--security runs the same pass with a security brief instead of the general one.

The reviewer runs on Claude Code itself — nothing extra to install or authenticate.

Output & commit

Produces the commit message and, on your approval, runs the commit itself — so the drift-hunter review actually sees the outgoing diff (a commit you run in your own terminal would skip it). Committing is always a user-confirmed action; /ship never commits without your go-ahead.

/before — the complement: pre-code instead of pre-commit
/session — after committing, leave a handoff for the next session