Ship

Core Rule

Block deployment when CHANGELOG, tests, or coverage gates fail. Preserve rollback capability at every step. Never ship from a dirty working tree.

When to Use

Invoke with /ship when:

• Feature is complete and ready for merge
• All local verification has passed
• You want an automated ship pipeline instead of manual steps
• Preparing a clean, bisectable PR from a feature branch

Process

Phase 1: Pre-flight Checks

Before anything else, verify readiness:

1. Working tree clean — no uncommitted changes (stash or commit first)
2. On a feature branch — never ship directly from main/master
3. Base branch up to date — rebase or merge latest main
4. Run full verification suite in order. If .claude/commands.json exists, use the declared commands (typecheck, lint, test, build) verbatim — that file is the project's single source of truth, the same commands the quality gate runs. Only fall back to guessing when a key is absent:
   • Typecheck — declared typecheck, else tsc / mypy / go vet / cargo check
   • Lint — declared lint, else the project's configured linter
   • Tests — declared test (full suite, not just changed files)
   • Build — declared build, else the project's production build

If any check fails, stop and report. Do not proceed with a failing pipeline.

Phase 2: Coverage Audit

Trace new/changed code paths and verify test coverage:

1. Identify changed files — git diff main...HEAD --name-only
2. Trace new code paths — new functions, endpoints, event handlers, UI flows
3. Check each path has tests — search for test files that exercise the new code
4. Report untested paths — ask user whether to write tests or skip

### Coverage Audit
| New Code Path | Test Coverage | Status |
|---------------|--------------|--------|
| POST /api/users | test/api/users.test.ts:45 | Covered |
| handleUpload() | — | UNTESTED |

If critical paths are untested, ask the user: "Write tests now or ship without?"

Phase 3: Commit Hygiene

Ensure commits are clean and bisectable:

1. Review commit history — git log main..HEAD --oneline
2. Check each commit:
   • Does it have a conventional message? (feat:, fix:, refactor:, etc.)
   • Is it atomic? (one logical change per commit)
   • Does each commit build independently?
3. If messy — suggest interactive rebase to squash/reorder (with user approval)
4. Never force-push without explicit user consent

Phase 4: CHANGELOG Generation

Generate or update CHANGELOG from commit history:

1. Read existing CHANGELOG.md (if present)
2. Categorize commits since last release:
   • Features (feat:)
   • Bug Fixes (fix:)
   • Breaking Changes (BREAKING CHANGE:)
   • Other (refactor, perf, docs)
3. Draft entry with human-readable descriptions (not raw commit messages)
4. Present to user for review before writing

## [Unreleased]

### Features
- Add user search with full-text filtering (#45)

### Bug Fixes
- Fix timezone handling in export CSV (#42)

Phase 5: Version Bump (if applicable)

If the project uses semantic versioning:

• PATCH — bug fixes only → auto-suggest
• MINOR — new features, no breaking changes → auto-suggest
• MAJOR — breaking changes → always ask user
• Update VERSION, package.json, pyproject.toml, or equivalent

Phase 6: PR Creation

Create a clean pull request:

1. Push branch to remote (with -u flag)
2. Generate PR title — short, descriptive (<70 chars)
3. Generate PR body:
   • Summary of changes (from CHANGELOG)
   • Test plan (what was verified) — cite the verification ledger via /verification-status: the auto-gate runs, the smoke-test result, and the silent-failure tally (processed/failed/skipped)
   • Coverage audit results
   • Breaking changes (if any)
   • Screenshots (if UI changes, ask user to attach)
4. Create PR via gh pr create
5. Report PR URL to user

Output Format

# Ship Report

## Pre-flight
- [x] Clean working tree
- [x] Feature branch: feat/user-search
- [x] Base branch up to date
- [x] Typecheck: passed
- [x] Lint: passed
- [x] Tests: 142 passed, 0 failed
- [x] Build: succeeded

## Coverage Audit
| Path | Coverage | Status |
|------|----------|--------|
| ... | ... | ... |

## Commits (N total)
1. feat: add search endpoint
2. feat: add search UI component
3. test: add search integration tests

## CHANGELOG
[Draft entry]

## PR
- URL: https://github.com/org/repo/pull/123
- Title: feat: add user search
- Base: main ← feat/user-search

Run Mode

This skill supports interactive (default) and headless modes — see the canonical contract in .claude/skills/_shared/blocks/mode-detection.md.

Headless detection: presence of mode:headless in arguments.

Headless ship is suitable for trusted CI pipelines that have already validated typecheck/lint/test/build outside the skill. It is not suitable for situations where a human should sanity-check the change before publication.

Common Rationalizations

Notes

• This skill automates the ship process but always asks for user confirmation on judgment calls (version bumps, untested paths, commit squashing)
• Auto-fix mechanical issues (commit message typos), ask for judgment calls (MAJOR version bump)
• If the project has CI/CD, this skill prepares the PR — CI handles the rest
• Never force-push or merge without explicit user approval