Ship

Purpose

Ship is the release orchestrator. It takes code that's been developed and guides it through the final gauntlet: running the full test suite, performing a release-grade code review, generating the changelog, bumping the version, tagging, creating the PR, and optionally deploying. Ship is the quality gate between "code written" and "code in production."

Ship is deliberately cautious. It runs checks in a specific order, and any failure halts the pipeline with a clear report. It does not deploy broken code. It does not skip tests. It treats every release as a potential production incident waiting to happen and acts accordingly.

Workflow

Phase 1: Pre-flight Check

1. Assess the release scope -- Determine what's being shipped by examining the branch, commit range, or diff against the target branch.
2. Invoke git-workflow -- Verify the branch is clean, up to date with the base branch, and has no merge conflicts.
3. Classify the release -- Based on the changes, suggest a version bump:
   • Patch: Bug fixes, dependency updates, typo fixes
   • Minor: New features, non-breaking enhancements
   • Major: Breaking changes, API modifications, architecture shifts
4. Present pre-flight report -- Show the user what's being shipped, the suggested version, and any concerns. Get confirmation.

Phase 2: Test

5. Invoke test -- Run the full test suite. This is not a quick spot-check; it's the full matrix:
   • Unit tests
   • Integration tests
   • End-to-end tests (if they exist)
   • Type checking
   • Linting
6. Evaluate results -- If any tests fail:
   • Auto-fixable: Invoke fix for straightforward failures (lint errors, type issues).
   • Requires investigation: Invoke debug for test failures that need root-cause analysis.
   • Blocking: If failures can't be resolved automatically, halt and report to user.
7. Re-run tests -- After fixes, run the suite again to confirm green.

Phase 3: Review

8. Invoke code-review -- Perform a release-grade review of all changes:
   • Security: No secrets, no injection vectors, proper auth checks
   • Quality: No dead code, no TODO hacks, no console.logs
   • Performance: No obvious regressions, no N+1 queries
   • Completeness: No half-implemented features, no missing error handling
9. Address review findings -- Fix any issues rated as "must fix before release." Log "nice to have" items for follow-up.
10. Invoke optimize (if flagged) -- If the review identified performance concerns, run optimization.

Phase 4: Changelog & Version

11. Invoke changelog-writer -- Generate a changelog entry from the commit history:
    • Group changes by category (Features, Bug Fixes, Breaking Changes, etc.)
    • Link to relevant PRs or issues
    • Highlight breaking changes prominently
12. Bump version -- Update version numbers in all relevant files (package.json, Cargo.toml, pyproject.toml, etc.).
13. Invoke commit-crafter -- Create a version bump commit.
14. Invoke git-workflow -- Create a git tag for the release.

Phase 5: Ship

15. Invoke pr-writer -- Create a pull request with:
    • Release summary
    • Changelog excerpt
    • Test results summary
    • Migration notes (if any)
16. Invoke preview (if available) -- Generate a preview deployment for final visual verification.
17. Deploy (if authorized) -- Trigger deployment to the specified target:
    • Staging first, then production (if the pipeline supports it)
    • Or directly to production if the user confirms
18. Post-ship report -- Summarize what was shipped, the version, and any follow-up items.

Quality Gates

Each gate must pass before proceeding to the next phase.

Gate	Criteria	On Failure
Branch health	Clean, no conflicts, up to date	Fix branch issues first
Test suite	All tests pass	Fix failures or halt
Type check	No type errors	Fix type errors
Lint	No lint errors	Auto-fix or halt
Code review	No critical findings	Fix critical issues
Security scan	No vulnerabilities	Fix or document exceptions
Changelog	Generated and accurate	Edit manually if needed
Version bump	Applied correctly	Fix version files

Usage

Use Ship when code is ready to release. Ship is the final quality gate and should be invoked after cook or team has completed the development work.

Best for:

• Releasing a new version of a package or application
• Deploying features to production
• Creating release candidates for testing
• Cutting a release after a sprint

Not ideal for:

• Development work (use cook first)
• Hotfixes (use cook with expedited flow, then ship with --hotfix mindset)
• Initial project setup (use bootstrap)

Examples

Example 1: Standard release

User: /ship Release the current feature branch to production

Ship workflow:
1. git-workflow -> Check branch health, find 12 commits since last release
2. Pre-flight -> Suggest minor version bump (new features, no breaking changes)
3. test -> Run full suite: 247 tests pass, 0 fail
4. code-review -> Review all 12 commits, find 1 console.log to remove
5. fix -> Remove console.log, re-test
6. changelog-writer -> Generate entry with 3 features, 2 bug fixes
7. Version bump -> 1.3.0 -> 1.4.0
8. commit-crafter -> "chore: bump version to 1.4.0"
9. git-workflow -> Create tag v1.4.0
10. pr-writer -> Create release PR
11. Deploy -> Push to staging, verify, push to production

Example 2: Hotfix release

User: /ship Ship this bugfix to production ASAP

Ship workflow:
1. git-workflow -> Verify hotfix branch from production
2. Pre-flight -> Suggest patch bump
3. test -> Run full suite (expedited: focus on affected areas)
4. code-review -> Focused review on the fix only
5. changelog-writer -> "Bug Fixes: Fix critical auth bypass in /api/auth"
6. Version bump -> 2.1.3 -> 2.1.4
7. commit-crafter + git-workflow -> Commit, tag v2.1.4
8. pr-writer -> Create hotfix PR with urgency flag
9. Deploy -> Directly to production after confirmation

Example 3: Pre-release

User: /ship Create a beta release for testing

Ship workflow:
1. git-workflow -> Check branch health
2. Pre-flight -> Suggest 2.0.0-beta.1 (breaking changes detected)
3. test -> Run full suite
4. code-review -> Full review with focus on breaking changes
5. changelog-writer -> Highlight all breaking changes with migration guides
6. Version bump -> 2.0.0-beta.1
7. commit-crafter + git-workflow -> Commit, tag v2.0.0-beta.1
8. pr-writer -> Create PR labeled as pre-release
9. preview -> Deploy to preview/staging environment only

Guardrails

• Never skip tests. Every release runs the full test suite. No exceptions.
• Never ship with critical review findings. Fix them or don't ship.
• Always generate a changelog. Every release must be documented.
• Always tag releases. Git tags are the source of truth for versions.
• Confirm before deploying to production. Always get explicit user confirmation for production deployments.
• Keep the release atomic. Don't mix unrelated changes into a release.
• Document breaking changes. If the release has breaking changes, they must be prominently documented with migration instructions.