Release CLI

A release is a pushed vX.Y.Z tag; CI builds, publishes and signs from it. This skill puts the version discipline, the changelog, the workflow and the registry wiring in place so the tag is the only human action left.

All rules with reasons, and the full per-language workflow/config files: release-patterns.md. Versions: stack-versions.md (verify live first, per version-protocol).

1. Audit current state

Change nothing yet. Read .claude/stack-profile.md (then ~/.claude/stack-profile.md); if absent, detect.

cat .claude/stack-profile.md 2>/dev/null | sed -n '1,30p'
ls .github/workflows 2>/dev/null
ls .goreleaser.y* dist-workspace.toml CHANGELOG.md scripts/release-notes.sh 2>/dev/null   # release machinery
grep -n '"version"' package.json 2>/dev/null
grep -n '^version' pyproject.toml Cargo.toml 2>/dev/null
git tag -l 'v*' | tail -5                          # tags so far and their naming
grep -rn 'homebrew' .goreleaser.y* dist-workspace.toml 2>/dev/null | head -3   # tap wired?

Record: language(s), the current version and whether a tag matches it, which release files exist, and which distribution channels are already wired (npm/PyPI trusted publishing, Homebrew tap, GitHub environments, tag protection).

2. Decide what to do

• No release machinery → full setup (steps 3-7).
• Some pieces exist → apply only the missing ones (steps 5-6). Name each gap you will close.
• Tag-triggered workflow, changelog gate, signing, registry wiring and README verify table all present → say "already in place" and stop.

3. Detect the track

Pick from languages in the profile or from step 1:

A profile with several languages gets one pipeline per package and tags namespaced per package (pkg-v1.2.0).

4. Install only what is missing

Live-version check first (version-protocol); then:

mise use goreleaser                    # Go
mise use aqua:axodotdev/cargo-dist     # Rust; provides the `dist` binary
uvx twine --version                    # Python metadata check; no install
mise use actionlint zizmor             # workflow linting

5. Generate the files

Copy from release-patterns.md; do not retype:

1. CHANGELOG.md — Keep a Changelog format, ## [Unreleased] on top.
2. scripts/release-notes.sh — prints the tag's section, exits 1 when it is empty.
3. The language's workflow/config — release.yml, .goreleaser.yaml, the pyproject.toml publishing fields or dist-workspace.toml (the per-language sections). After changing dist-workspace.toml, re-run dist generate; never hand-edit the generated workflow.
4. README — the install table plus the "Verify a download" table.

6. Wire it

Registry and repository side, once per repo:

• npm: trusted-publisher entry (owner, repository, workflow release.yml, environment npm); repository with the exact GitHub URL, files, engines, bin in package.json.
• PyPI: pending publisher before the first release (same fields, environment pypi); it does not reserve the name.
• Homebrew tap: repository homebrew-<name>; fine-grained PAT (contents: write on the tap repo only) as TAP_GITHUB_TOKEN (Go) or HOMEBREW_TAP_TOKEN (Rust).
• GitHub environments (npm, pypi) on the publish jobs; required reviewers when more than one person can tag.
• Tag protection rule for v*: maintainers only.
• Workflows: permissions: {} at the top level, per-job permissions, persist-credentials: false, cache: false, actions pinned to full SHAs (security-baseline).

7. Verify

goreleaser check && goreleaser release --snapshot --clean --skip=sign,sbom,publish   # archives + checksums built, nothing uploaded
dist plan                                                                            # targets, installers, tap formula listed
npm pack --dry-run                                                                   # tarball holds dist/, bin, README
uv build --no-sources && uvx twine check dist/*                                      # both files PASSED
actionlint && zizmor --offline .github/workflows                                     # no findings; cargo-dist's generated file: the known ones in release-patterns.md
scripts/release-notes.sh v<current>                                                  # prints the section, exit 0

v<current> is the version the changelog entry was written for (package.json, uv version --short, Cargo.toml; Go has no version file). The first real tag is v0.1.0-rc.1, never v1.0.0: it proves every credential and permission on a non-latest channel, and a mistake can be deleted and re-tagged.

References

• release-patterns.md: SemVer over the CLI surface, changelog and tag rules, the full per-language pipelines, signing, README tables.
• ../_shared/stack-versions.md: verified versions.
• ../build-cli/cli-ux.md: the CLI contract a version number promises.
• ../set-up-dev-toolchain/SKILL.md: actionlint/zizmor hooks.
• ../../core/_shared/security-baseline.md, ../../core/_shared/version-protocol.md: least permissions, SHA pins, live version checks.