Cut a Release — claude-code-trace

Turns "we should release this" into a tagged, pushed, pipeline-triggered, publicly published release with a curated CHANGELOG, in a way that survives the project's strict pre-commit hook chain and stays honest about what's actually shipping.

The skill is project-local because the steps depend on this repo's specific shape (three version files, two lockfiles, GH Actions release on v* tag, the spec-drift + test-reflection pre-commit hook pair).

Operating mode

The skill is fully automated end-to-end and fully synchronous. It never calls AskUserQuestion, never waits for "yes", never branches on user preference, and never runs any command in the background. Every Bash invocation runs in the foreground so the session holds continuously from Phase 1 through Phase 9 — no run_in_background: true, no trailing &, no nohup, no disown. This includes long-running steps like gh run watch in Phase 7; set the Bash timeout parameter to match the expected duration (e.g. 1800000 ms for the release pipeline) rather than detaching.

Defaults are deterministic:

• Scope — always linear: every commit since git describe --tags --abbrev=0 ships.
• Bump tier — highest conventional-commit tier in the subset (see

${CLAUDE_SKILL_DIR}/references/conventional-commits.md). BREAKING CHANGE: or !: produces a minor bump while the version is 0.X.Y (pre-1.0 caveat) and a major bump otherwise; the skill never silently promotes to 1.0.0.

• CHANGELOG — every Added/Fixed bullet is written from commit subjects + diff reads;

chore: / docs: / test: / ci: are always skipped.

• Push order — tag first, then main (so CI sees the tag immediately; main catches up

after).

The skill aborts (loudly) only on hard preconditions that would corrupt the release:

• Duplicate version — the proposed vX.Y.Z tag already exists on origin. Abort

with Error: vX.Y.Z already exists on origin (commit <sha>). Refusing to release the same version twice. The user must delete the remote tag intentionally if they want a re-release, or bump again.

• Dirty working tree — uncommitted changes the skill didn't create. Abort with a

list of dirty files.

• npm run check fails — abort and surface the failure verbatim.

Before you start

Read these references on the first invocation in a session — they describe constants the phase files refer to.

• ${CLAUDE_SKILL_DIR}/references/project-shape.md — version files, lockfiles, pre-commit

hooks, release pipeline wiring.

• ${CLAUDE_SKILL_DIR}/references/conventional-commits.md — how commit prefixes map to

semver bump level.

${CLAUDE_SKILL_DIR}/references/changelog-template.md is loaded when you reach Phase 4.

Execution

Phase 1 — Inspect and decide

Read ${CLAUDE_SKILL_DIR}/steps/phase1-inspect-and-scope.md and follow all instructions.

Phase 2 — Build the release branch

Read ${CLAUDE_SKILL_DIR}/steps/phase2-build-release-branch.md and follow all instructions.

Phase 3 — Bump version files

Read ${CLAUDE_SKILL_DIR}/steps/phase3-bump-versions.md and follow all instructions.

Phase 4 — Write the CHANGELOG entry

Read ${CLAUDE_SKILL_DIR}/steps/phase4-changelog.md and follow all instructions.

Phase 5 — Verify, commit, tag

Read ${CLAUDE_SKILL_DIR}/steps/phase5-verify-commit-tag.md and follow all instructions.

Phase 6 — Push the tag (with duplicate-version preflight)

Read ${CLAUDE_SKILL_DIR}/steps/phase6-push-tag.md and follow all instructions.

Phase 7 — Watch the pipeline and verify the release is public

Read ${CLAUDE_SKILL_DIR}/steps/phase7-publish-github-release.md and follow all instructions.

Phase 8 — Push the release commit to main

Read ${CLAUDE_SKILL_DIR}/steps/phase8-back-to-main.md and follow all instructions.

Phase 9 — Clean up

Read ${CLAUDE_SKILL_DIR}/steps/phase9-cleanup.md and follow all instructions.

What the skill will NOT do automatically

• Bypass pre-commit hooks with --no-verify — always fix the underlying issue.
• Force-push (git push -f) to main, the release tag, or any shared branch.
• Delete a remote tag or remote branch.
• Cut a major bump (X.0.0) while the version is still 0.X.Y — pre-1.0 the skill

caps at minor even when a breaking change is detected.

• Re-tag an existing version — the duplicate-version preflight in Phase 6 aborts first.

The harness's auto-mode classifier may still intercept pushes to shared branches (e.g. git push origin main) — that is out of skill scope. When it does, surface the error and continue with the remaining phases; the user resolves the push themselves.