feat(ship): add platform publish and GitHub release phases

Extend ship skill from 5 to 7 phases: adds Phase 6 (npm/PyPI/crates publish)
and Phase 7 (git tag + gh release create with structured notes). Phase 5
(PR creation) is now skippable for trunk-based workflows.

Captures the v7.3.7 release workflow (npm publish + tag + GitHub release)
so future releases follow the same protocol.

Author: catlog22

.claude/skills/ship/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: ship
-description: Structured release pipeline with pre-flight checks, AI code review, version bump, changelog, and PR creation. Triggers on "ship", "release", "publish".
+description: Structured release pipeline with pre-flight checks, AI code review, version bump, changelog, PR creation, platform publish, and GitHub release. Triggers on "ship", "release", "publish".
 allowed-tools: Read, Write, Bash, Glob, Grep
 ---
 
 # Ship
 
-Structured release pipeline that guides code from working branch to pull request through 5 gated phases: pre-flight checks, automated code review, version bump, changelog generation, and PR creation.
+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
 
@@ -49,11 +51,24 @@ User: "ship" / "release" / "publish"
 │  → Output: commit SHA                                    │
 │  → Gate: Push successful                                 │
 ├──────────────────────────────────────────────────────────┤
-│  Phase 5: PR Creation                                    │
+│  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                                      │
+│  → 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                            │
 └──────────────────────────────────────────────────────────┘
 ```
 
@@ -65,7 +80,9 @@ Execute phases sequentially. Each phase has a gate condition — if the gate fai
 2. **Phase 2**: [Code Review](phases/02-code-review.md) -- AI-powered diff review with risk assessment
 3. **Phase 3**: [Version Bump](phases/03-version-bump.md) -- Detect and update version across project types
 4. **Phase 4**: [Changelog & Commit](phases/04-changelog-commit.md) -- Generate changelog, create release commit, push
-5. **Phase 5**: [PR Creation](phases/05-pr-creation.md) -- Create PR with structured body and issue links
+5. **Phase 5**: [PR Creation](phases/05-pr-creation.md) -- Create PR with structured body and issue links *(skip for trunk-based)*
+6. **Phase 6**: [Platform Publish](phases/06-platform-publish.md) -- Publish to npm / PyPI / crates.io *(skip for private packages)*
+7. **Phase 7**: [GitHub Release](phases/07-github-release.md) -- Tag release commit and publish GitHub release notes
 
 ## Pre-Flight Checklist (Quick Reference)
 
@@ -84,10 +101,10 @@ Every execution terminates with one of:
 
 | Status | When |
 |--------|------|
-| **DONE** | All 5 phases completed, PR created |
-| **DONE_WITH_CONCERNS** | PR created but with review warnings or non-critical issues |
-| **BLOCKED** | A gate failed (dirty git, tests fail, push rejected) |
-| **NEEDS_CONTEXT** | Cannot determine bump type, ambiguous branch target |
+| **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
 
@@ -101,5 +118,7 @@ Follows the Three-Strike Rule (SKILL-DESIGN-SPEC section 14). On 3 consecutive f
 | [phases/02-code-review.md](phases/02-code-review.md) | AI-powered diff review |
 | [phases/03-version-bump.md](phases/03-version-bump.md) | Version detection and bump |
 | [phases/04-changelog-commit.md](phases/04-changelog-commit.md) | Changelog generation and release commit |
-| [phases/05-pr-creation.md](phases/05-pr-creation.md) | PR creation with issue linking |
+| [phases/05-pr-creation.md](phases/05-pr-creation.md) | PR creation with issue linking (skippable) |
+| [phases/06-platform-publish.md](phases/06-platform-publish.md) | npm / PyPI / crates.io publish (skippable) |
+| [phases/07-github-release.md](phases/07-github-release.md) | Tag and GitHub release notes |
 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill design spec (completion protocol, escalation) |

.claude/skills/ship/phases/05-pr-creation.md

@@ -2,6 +2,16 @@
 
 Create a pull request via GitHub CLI with a structured body, linked issues, and release metadata.
 
+## Skip Conditions
+
+Skip this phase (proceed directly to Phase 6) when:
+
+- Current branch is `main` / `master` and the project uses trunk-based development (release commit was pushed directly to the default branch)
+- User explicitly passes `--no-pr`
+- No remote write access to create PRs (rare — usually a BLOCKED signal instead)
+
+When skipped, record `phase: "pr-creation", overall: "skip", reason: "..."` in the skill output and move on.
+
 ## Objective
 
 - Create a PR using `gh pr create` with structured body
@@ -11,7 +21,7 @@ Create a pull request via GitHub CLI with a structured body, linked issues, and
 
 ## Gate Condition
 
-PR created successfully and URL returned.
+PR created successfully and URL returned — OR skip condition matched.
 
 ## Execution Steps
 
@@ -138,26 +148,8 @@ echo "PR created: $pr_url"
 }
 ```
 
-## Completion
-
-After PR creation, output the final Completion Status:
-
-```
-## STATUS: DONE
-
-**Summary**: Released vX.Y.Z — PR created at {pr_url}
+## Next Phase
 
-### Details
-- Phases completed: 5/5
-- Version: {previous} -> {new} ({bump_type})
-- PR: {pr_url}
-- Key outputs: CHANGELOG.md updated, release commit pushed, PR created
-
-### Outputs
-- CHANGELOG.md (updated)
-- {version_file} (version bumped)
-- Release commit: {sha}
-- PR: {pr_url}
-```
+After PR creation (or skip), proceed to [Phase 6: Platform Publish](06-platform-publish.md).
 
-If there were review warnings, use `DONE_WITH_CONCERNS` and list the warnings in the Details section.
+**Note**: Final completion status is emitted by Phase 7 (the terminal phase), not here. PR URL flows through to the final STATUS output as part of the release record.

.claude/skills/ship/phases/06-platform-publish.md

@@ -0,0 +1,107 @@
+# Phase 6: Platform Publish
+
+Publish the released version to its package registry (npm, PyPI, etc.). Runs after the release commit is merged to the default branch (or immediately after push for trunk-based workflows).
+
+## Objective
+
+- Detect the target registry from the version file type
+- Verify the local working tree is on the release commit
+- Publish to the registry
+- Capture the published artifact metadata (name, version, tarball URL)
+
+## Gate Condition
+
+Publish command exits 0 and registry confirms the new version is live.
+
+## When to Skip
+
+- Project is marked `"private": true` in `package.json` (or equivalent private flag) — **skip and record as N/A**
+- User explicitly passes `--no-publish`
+- Registry is unreachable — report BLOCKED with diagnostic, do not retry blindly
+
+## Execution Steps
+
+### Step 1: Detect Registry
+
+| Version File | Registry | Publish Command |
+|--------------|----------|-----------------|
+| `package.json` (not private) | npm | `npm publish` |
+| `pyproject.toml` | PyPI | `python -m build && twine upload dist/*` |
+| `Cargo.toml` | crates.io | `cargo publish` |
+| `VERSION` / other | — | SKIP (no registry) |
+
+```bash
+if [ -f "package.json" ]; then
+  is_private=$(node -p "require('./package.json').private === true" 2>/dev/null || echo "false")
+  if [ "$is_private" = "true" ]; then
+    echo "SKIP: package.json marked private"
+    exit 0
+  fi
+  pkg_name=$(node -p "require('./package.json').name")
+  pkg_version=$(node -p "require('./package.json').version")
+fi
+```
+
+### Step 2: Verify Working Tree
+
+Before publishing, confirm the local tree matches what was committed:
+
+```bash
+git status --porcelain  # must be empty
+git rev-parse HEAD      # record the commit SHA being published
+```
+
+If the tree is dirty, abort — partial/uncommitted changes must never land in a published artifact.
+
+### Step 3: Publish
+
+**npm**:
+```bash
+# Default — runs the package's own prepublish hooks (build, clean, etc.)
+npm publish 2>&1 | tee /tmp/publish.log
+
+# For scoped packages that need public access:
+# npm publish --access public
+```
+
+Background execution is acceptable for long publish operations (large packages, slow network). Use the Bash tool's `run_in_background: true` and monitor the output file.
+
+**PyPI**:
+```bash
+rm -rf dist/ build/
+python -m build
+twine upload dist/* 2>&1 | tee /tmp/publish.log
+```
+
+### Step 4: Verify Publish
+
+```bash
+# npm — query the registry for the new version
+npm view "$pkg_name@$pkg_version" version
+
+# PyPI — query the simple index
+curl -sfI "https://pypi.org/pypi/$pkg_name/$pkg_version/json" | head -1
+```
+
+If verification fails, check the publish log — a common cause is an `OTP required` prompt for 2FA npm accounts. Surface the prompt to the user.
+
+## Output
+
+```json
+{
+  "phase": "platform-publish",
+  "registry": "npm|pypi|crates|none",
+  "package_name": "claude-code-workflow",
+  "published_version": "7.3.7",
+  "tarball_size": "8.2 MB",
+  "total_files": 2280,
+  "published_sha": "3a0d6d71",
+  "overall": "pass|skip|fail"
+}
+```
+
+## Next Phase
+
+Proceed to [Phase 7: GitHub Release](07-github-release.md).
+
+If publish fails, report BLOCKED — **do not** proceed to GitHub release, since the release notes would point to a version that doesn't exist on the registry.

.claude/skills/ship/phases/07-github-release.md

@@ -0,0 +1,149 @@
+# Phase 7: GitHub Release
+
+Tag the release commit and publish a GitHub release with auto-generated release notes.
+
+## Objective
+
+- Create an annotated git tag `vX.Y.Z` pointing at the release commit
+- Push the tag to origin
+- Create a GitHub release with structured release notes (summary, commit list, migration notes, compare link)
+
+## Gate Condition
+
+`gh release create` returns a release URL.
+
+## Prerequisite
+
+- Phase 6 (Platform Publish) completed with status `pass` or `skip`. **Do not create a release for a version that failed to publish.**
+- `gh` CLI authenticated (`gh auth status`).
+
+## Execution Steps
+
+### Step 1: Create and Push Annotated Tag
+
+```bash
+# Tag the release commit
+git tag -a "v${new_version}" -m "v${new_version}"
+
+# Push to origin
+git push origin "v${new_version}"
+```
+
+**Do NOT** use lightweight tags — annotated tags carry the release metadata and are what `gh release create` expects.
+
+If the tag already exists (e.g. a prior attempt pushed the tag), decide:
+- Same commit → skip tag creation, proceed to release
+- Different commit → BLOCKED, tag must be deleted and recreated deliberately (destructive, require user confirmation)
+
+### Step 2: Compose Release Notes
+
+Release notes have four sections — keep them focused and scannable:
+
+```markdown
+## Summary
+
+- **{highlight 1}**: one-line description of the most impactful change
+- **{highlight 2}**: another key change (feature/fix/perf)
+- **Scope**: rough scale indicator (e.g. "74 files across X, Y, Z")
+
+## What's Changed
+
+- `<commit subject>` (<short SHA>)
+- `<commit subject>` (<short SHA>)
+
+## Migration
+
+{Migration notes if any, or "No action required."}
+
+**Full Changelog**: https://github.com/{owner}/{repo}/compare/v{prev}...v{new}
+```
+
+**Sourcing the content**:
+
+- **Summary bullets**: synthesize 2-4 highlights from the commits since last release. Prefer `feat:` / `refactor:` / breaking changes. Call out compatibility posture explicitly if it's non-trivial.
+- **What's Changed**: one line per commit since `git describe --tags --abbrev=0` (exclude merge commits and the `chore: bump version` commit itself).
+- **Migration**: only include if users need to take action. Default to "No action required."
+- **Compare link**: always include — it's the authoritative diff.
+
+```bash
+prev_tag=$(git describe --tags --abbrev=0 HEAD^)
+commits=$(git log "$prev_tag..v${new_version}^" --pretty=format:"- \`%s\` (%h)" --no-merges)
+compare_url="https://github.com/${owner}/${repo}/compare/${prev_tag}...v${new_version}"
+```
+
+### Step 3: Create GitHub Release
+
+```bash
+gh release create "v${new_version}" \
+  --title "v${new_version} — {short descriptive suffix}" \
+  --notes "$(cat <<'EOF'
+## Summary
+
+- ...
+
+## What's Changed
+
+- ...
+
+## Migration
+
+...
+
+**Full Changelog**: ...
+EOF
+)"
+```
+
+**Title convention**: `v{X.Y.Z} — {Short Theme}` (e.g. `v7.3.7 — Session ID Chronological Sort`). The suffix summarizes the release theme in 2-5 words.
+
+**Flags**:
+- Omit `--draft` unless the user wants to review notes first
+- Omit `--prerelease` for standard releases; use it for `-beta` / `-rc` tags
+- `--latest` is automatic when the tag is the highest semver
+
+### Step 4: Capture Release URL
+
+`gh release create` prints the release URL on stdout — capture and report it:
+
+```bash
+release_url=$(gh release create ... 2>&1 | tail -1)
+echo "Release: $release_url"
+```
+
+## Output
+
+```json
+{
+  "phase": "github-release",
+  "tag": "v7.3.7",
+  "tagged_sha": "3a0d6d71",
+  "release_url": "https://github.com/owner/repo/releases/tag/v7.3.7",
+  "previous_tag": "v7.3.6",
+  "commits_included": 4,
+  "overall": "pass|fail"
+}
+```
+
+## Completion
+
+After the GitHub release is created, emit the final Completion Status:
+
+```
+## STATUS: DONE
+
+**Summary**: Released vX.Y.Z — published to {registry} and GitHub
+
+### Details
+- Version: {previous} -> {new} ({bump_type})
+- npm: https://www.npmjs.com/package/{pkg_name}/v/{new}
+- Release: {release_url}
+- Tag: v{new} -> {commit_sha}
+
+### Outputs
+- CHANGELOG.md (updated)
+- Release commit: {sha}
+- npm tarball: {size}, {files} files
+- GitHub release: {release_url}
+```
+
+Use `DONE_WITH_CONCERNS` if the publish step was skipped (private package) or if the release notes were auto-generated without human review.