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 <!-- src: --> citation in docs/** is still accurate. Drafts a why-focused commit message. When a second model is available, the outgoing diff is reviewed by the drift-hunter gate (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 <!-- src: path:range --> 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.mdupdated? backfill plan? - External service added →
docs/integrations.mdupdated? - Non-obvious bug fixed → add to
KNOWN-ISSUES.mdwith prevention rule - Gap shipped → mark
shipped YYYY-MM-DD (commit: <hash>)indocs/*-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 gate (two-brain review)
When a second model (Codex CLI) is installed, the commit is routed through an adversarial review gate before it lands — the review half of the two-brain workflow:
- If
/beforewrote a fresh, valid stamped spec for this task (base commit is an ancestor ofHEAD, written within the last day), the gate reads it and hunts for where the diff drifted from the approved plan — plus any correctness, security, or data bug. Findings are tagged[DRIFT]/[BUG]. - No fresh spec? The gate falls back to a generic correctness review and says plainly that drift was not checked — it never claims a review that didn’t happen.
- On a deny, Claude adjudicates each finding (fixes the real ones, may rebut the reviewer once), then surfaces the outcome. You approve the final result; the reviewer advises, it never silently overrides you.
No reviewer installed? /ship runs its checklist exactly as above, single-agent.
Output & commit
Produces the commit message and, on your approval, runs the commit itself — so the drift-hunter gate actually fires on the outgoing diff (a commit you run in your own terminal would bypass it). Committing is always a user-confirmed action; /ship never commits without your go-ahead.