release-tag

Take the repo from "ready" to a clean, tagged, pushed release. Releases are outward-facing and effectively irreversible once published, so every step is gated by pre-flight checks and explicit confirmation.

Hard rules: never break these

• Never release a dirty or unverified tree. Working tree clean, on the correct branch, up to date with the remote, and tests/CI green; all true before tagging.
• Tags are immutable once published. Never move or overwrite a pushed tag; if a release is wrong, cut a new patch version. Force-retagging breaks everyone who already pulled.
• Follow SemVer honestly. The bump must reflect what actually changed (see Step 2), not a convenient number.
• Confirm before the commit, the tag, and the push. These are the irreversible, outward-facing actions.
• No AI/co-author trailers in the release commit or tag message.
• Publishing is downstream. Tagging ≠ publishing to a registry. Don't run npm publish / cargo publish / etc. unless explicitly asked; most pipelines publish from CI on tag.

Step 1: Pre-flight

• git status → clean tree (or stash/commit deliberate changes first).
• On the release branch (usually main/master or a release/* branch) and synced: git fetch && git status shows up to date.
• Latest tag and history since it: git describe --tags --abbrev=0.
• Tests, linters, and build pass locally; CI on the release commit is green.

Step 2: Determine the version

Derive the SemVer bump from the commits since the last tag:

• MAJOR: any breaking change (! marker, BREAKING CHANGE: footer, removed/incompatible API).
• MINOR: new backward-compatible features (feat).
• PATCH: backward-compatible fixes only (fix, perf).
• Pre-1.0: minor/patch carry the instability caveat; respect the project's stated policy.
• Honor pre-release / build identifiers if used (1.4.0-rc.1, +build.5) and any explicit version the user gives.

Step 3: Bump the version files (stack-aware)

Update wherever the canonical version lives; detect by the manifests present:

Keep lockfiles consistent. Monorepos: prefer the configured tool (changesets, Lerna, Nx release, Turborepo) and per-package versioning over hand edits. Use the native bump command when one exists, but suppress its auto-tag/commit so the steps below stay explicit and controlled.

Step 4: Update the changelog

Refresh CHANGELOG.md/release notes for this version (delegate to the changelog skill if available): move [Unreleased] items under the new ## [X.Y.Z] - <date> heading, call out breaking changes and migration steps.

Step 5: Commit, then tag (with confirmation)

1. Stage only the version + changelog files (explicit paths, never git add -A), and confirm.
2. Release commit: chore(release): vX.Y.Z (or the repo's convention).
3. Annotated, optionally signed tag, never lightweight:
   • git tag -a vX.Y.Z -m "Release vX.Y.Z" (add -s to sign if the project signs releases).
   • Match the existing tag prefix style (v1.4.0 vs 1.4.0; check git tag).
4. Sanity-check: git show vX.Y.Z points at the release commit and the message is right.

Step 6: Push (with confirmation)

1. Confirm branch + tag + remote.
2. Push the commit and the tag: git push origin <branch> then git push origin vX.Y.Z (or --follow-tags). Avoid git push --tags (it pushes all tags).
3. If CI builds/publishes/creates the release from the tag, say so and let it run; don't duplicate the publish manually.

Report the released version, the tag, the commit it points to, and what (if anything) downstream automation will now do.