ship

Structured release pipeline that guides code from working branch to a published release through 7 gated phases: pre-flight checks, automated code review, version bump, changelog generation, PR creation, platform publish (npm/PyPI/etc.), and GitHub release.

Phases 5 (PR) and 6 (Publish) are conditionally skippable — trunk-based workflows that commit directly to main skip Phase 5; private packages skip Phase 6. Phase 7 (GitHub release) is the terminal phase and always runs unless the publish step failed.

Key Design Principles

1. Phase Gates: Each phase must pass before the next begins — no shipping broken code
2. Multi-Project Support: Detects npm (package.json), Python (pyproject.toml), and generic (VERSION) projects
3. AI-Powered Review: Uses CCW CLI to run automated code review before release
4. Audit Trail: Each phase produces structured output for traceability
5. Safe Defaults: Warns on risky operations (direct push to main, major version bumps)

Architecture Overview

User: "ship" / "release" / "publish"
         |
         v
┌──────────────────────────────────────────────────────────┐
│  Phase 1: Pre-Flight Checks                              │
│  → git clean? branch ok? tests pass? build ok?           │
│  → Output: preflight-report.json                         │
│  → Gate: ALL checks must pass                            │
├──────────────────────────────────────────────────────────┤
│  Phase 2: Code Review                                    │
│  → detect merge base, diff against base                  │
│  → ccw cli --tool gemini --mode analysis                 │
│  → flag high-risk changes                                │
│  → Output: review-summary                                │
│  → Gate: No critical issues flagged                      │
├──────────────────────────────────────────────────────────┤
│  Phase 3: Version Bump                                   │
│  → detect version file (package.json/pyproject.toml/VERSION)
│  → determine bump type from commits or user input        │
│  → update version file                                   │
│  → Output: version change record                         │
│  → Gate: Version updated successfully                    │
├──────────────────────────────────────────────────────────┤
│  Phase 4: Changelog & Commit                             │
│  → generate changelog from git log since last tag        │
│  → update CHANGELOG.md                                   │
│  → create release commit, push to remote                 │
│  → Output: commit SHA                                    │
│  → Gate: Push successful                                 │
├──────────────────────────────────────────────────────────┤
│  Phase 5: PR Creation (skippable for trunk-based)        │
│  → gh pr create with structured body                     │
│  → auto-link issues from commits                         │
│  → Output: PR URL                                        │
│  → Gate: PR created OR skipped (direct-to-main)          │
├──────────────────────────────────────────────────────────┤
│  Phase 6: Platform Publish (skippable if private)        │
│  → detect registry (npm / PyPI / crates.io)              │
│  → npm publish / twine upload / cargo publish            │
│  → verify new version is live on registry                │
│  → Output: published artifact metadata                   │
│  → Gate: registry confirms version OR skipped (private)  │
├──────────────────────────────────────────────────────────┤
│  Phase 7: GitHub Release                                 │
│  → git tag -a vX.Y.Z + push tag                          │
│  → gh release create with structured notes               │
│  → Output: release URL                                   │
│  → Gate: release URL returned                            │
└──────────────────────────────────────────────────────────┘

Execution Flow

Execute phases sequentially. Each phase has a gate condition — if the gate fails, stop and report status.

1. Phase 1: Pre-Flight Checks -- Validate git state, branch, tests, build
2. Phase 2: Code Review -- AI-powered diff review with risk assessment
3. Phase 3: Version Bump -- Detect and update version across project types
4. Phase 4: Changelog & Commit -- Generate changelog, create release commit, push
5. Phase 5: PR Creation -- Create PR with structured body and issue links (skip for trunk-based)
6. Phase 6: Platform Publish -- Publish to npm / PyPI / crates.io (skip for private packages)
7. Phase 7: GitHub Release -- Tag release commit and publish GitHub release notes

Pre-Flight Checklist (Quick Reference)

Check	Command	Pass Condition
Git clean	git status --porcelain	Empty output
Branch	git branch --show-current	Not main/master
Tests	npm test / pytest	Exit code 0
Build	npm run build / python -m build	Exit code 0

Completion Status Protocol

This skill follows the Completion Status Protocol defined in SKILL-DESIGN-SPEC.md sections 13-14.

Every execution terminates with one of:

Status	When
DONE	All applicable phases completed, GitHub release published
DONE_WITH_CONCERNS	Release published but with review warnings, skipped publish (private pkg), or non-critical issues
BLOCKED	A gate failed (dirty git, tests fail, push rejected, publish failed, tag conflict)
NEEDS_CONTEXT	Cannot determine bump type, ambiguous branch target, unclear registry target

Escalation

Follows the Three-Strike Rule (SKILL-DESIGN-SPEC section 14). On 3 consecutive failures at the same step, stop and output diagnostic dump.

Reference Documents

Document	Purpose
phases/01-preflight-checks.md	Git, branch, test, build validation
phases/02-code-review.md	AI-powered diff review
phases/03-version-bump.md	Version detection and bump
phases/04-changelog-commit.md	Changelog generation and release commit
phases/05-pr-creation.md	PR creation with issue linking (skippable)
phases/06-platform-publish.md	npm / PyPI / crates.io publish (skippable)
phases/07-github-release.md	Tag and GitHub release notes
../_shared/SKILL-DESIGN-SPEC.md	Skill design spec (completion protocol, escalation)