Release Skill

Purpose: Take a project from "code is ready" to "tagged and ready to push."

Pre-flight validation, changelog from git history, version bumps across package files, release commit, annotated tag, and curated release notes. Everything is local and reversible. Publishing (including the GitHub Release page) is CI's job.

Quick Start

/release 1.7.0                # full release: changelog + bump + commit + tag
/release 1.7.0 --dry-run      # show what would happen, change nothing
/release --check               # readiness validation only (GO/NO-GO)
/release                       # suggest version from commit analysis

Arguments

version

1.7.0

--check

--dry-run

--skip-checks

--changelog-only

Modes

Default: Full Release

/release [version]

Steps: pre-flight → changelog → release notes → version bump → user review → write → release commit → tag → guidance.

Check Mode

/release --check

Runs all pre-flight checks and reports GO/NO-GO. Useful before starting the release, in CI as a gate, or composed with

/vibe

Changelog Only

/release 1.7.0 --changelog-only

Generates the changelog entry and writes it. No version bumps, no commit, no tag.

Workflow

Step 1: Pre-flight

Run these checks before anything else:

./scripts/ci-local-release.sh      # mandatory local CI parity gate (blocking)
git rev-parse --git-dir           # must be in a git repo
git status --porcelain            # warn if dirty
git branch --show-current         # show current branch

/release

ci-local-release.sh

.agents/releases/local-ci/<timestamp>/

release-artifacts.json

./scripts/ci-local-release.sh --release-version <version>

./scripts/resolve-release-artifacts.sh <version>

Checks:

git rev-parse --git-dir

[Unreleased]

git status --porcelain

git branch --show-current

ci-local-release.sh

CycloneDX

SPDX

/deps vuln

.claude-plugin/plugin.json

marketplace.json

git log --oneline <range>

.agents/rpi/next-work.jsonl

consumed=false

severity=high

Unconsumed findings check (soft WARN, non-blocking):

if [ -f .agents/rpi/next-work.jsonl ] && command -v jq &>/dev/null; then
  high_count=$(jq -s '[.[] | select(.consumed == false) | .items[] | select(.severity == "high")] | length' \
    .agents/rpi/next-work.jsonl 2>/dev/null || echo 0)
  if [ "$high_count" -gt 0 ]; then
    echo "[WARN] $high_count unconsumed high-severity item(s) in .agents/rpi/next-work.jsonl"
    echo "       These carry-forward findings have not been addressed. Review before releasing."
    echo "       Run: jq -s '[.[] | select(.consumed==false) | .items[] | select(.severity==\"high\")]' .agents/rpi/next-work.jsonl"
  fi
fi

This is a soft WARN — it does not block the release. It surfaces carry-forward findings from prior retro/post-mortem sessions so the release engineer can make an informed decision.

Test/lint detection:

go.mod

go test ./...

golangci-lint run

package.json

npm test

npm run lint

pyproject.toml

pytest

ruff check .

Cargo.toml

cargo test

cargo clippy

Makefile

test:

make test

make lint

If

--skip-checks

ci-local-release.sh

In

--check

Release Readiness: NO-GO

  [PASS] Git repo
  [PASS] CHANGELOG.md exists
  [PASS] Working tree clean
  [WARN] Branch: feature/foo (expected main)
  [FAIL] Tests: 2 failures in auth_test.go
  [PASS] Lint clean
  [PASS] Version consistency (1.6.0 in all 2 files)
  [PASS] 14 commits since v1.6.0
  [WARN] 2 unconsumed high-severity item(s) in .agents/rpi/next-work.jsonl

In

--check

Step 2: Determine range

Find the last release tag:

git tag --sort=-version:refname -l 'v*' | head -1

• If no

  v*

  tags exist, use the first commit:

  git rev-list --max-parents=0 HEAD

• The range is

  <last-tag>..HEAD

• If range is empty (no new commits), stop and tell the user

Step 3: Read git history

Gather commit data for classification:

git log --oneline --no-merges <range>
git log --format="%H %s" --no-merges <range>
git diff --stat <range>

Use

--oneline

Step 4: Classify and group

Classify each commit into one of four categories:

feat

Grouping rules:

• Group related commits that share a component prefix (e.g.,

  auth:

  ,

  api:

  ,

  feat(users)

  )
• Combine grouped commits into a single bullet with a merged description
• Match the existing CHANGELOG style — read the most recent versioned entry and replicate its bullet format, separator style, and heading structure
• If a commit message is ambiguous, read the diff with

  git show --stat <hash>

  to clarify

Key rules:

• Don't invent — only document what git log shows
• Omit empty sections — don't include

  ### Removed

  if nothing was removed
• Commits, not diffs — classify from commit messages; read diffs only when ambiguous
• Merge-commit subjects are noise — already filtered by

  --no-merges

Step 5: Suggest version

If no version was provided, suggest one based on the commit classification:

!:

Show the suggestion with reasoning:

Suggested version: 1.7.0 (minor)
Reason: 3 new features added, no breaking changes

Current version: 1.6.0 (from package.json, go tags)

Use AskUserQuestion to confirm or let the user provide a different version.

Step 6: Generate changelog entry

Produce a markdown block in Keep a Changelog format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- description of new feature

### Changed
- description of change

### Fixed
- description of fix

Use today's date in

YYYY-MM-DD

Style adaptation: Read the existing CHANGELOG entries and match their conventions:

• Bullet format (plain text vs bold names vs backtick names)
• Separator style (em-dash

  —

  , hyphen

  -

  , colon

  : 

  )
• Grouping patterns (flat list vs sub-sections)
• Level of detail (terse vs verbose)

If no existing entries to reference (first release), use plain Keep a Changelog defaults.

Step 7: Detect and offer version bumps

Scan for files containing version strings:

package.json

"version": "X.Y.Z"

"version": "1.6.0"

pyproject.toml

version = "X.Y.Z"

version = "1.6.0"

Cargo.toml

version = "X.Y.Z"

version = "1.6.0"

*.go

const Version = "X.Y.Z"

var version = "X.Y.Z"

const Version = "1.6.0"

version.txt

1.6.0

VERSION

1.6.0

.goreleaser.yml

Show what was found:

Version strings detected:

  package.json:       "version": "1.6.0"  → "1.7.0"
  src/version.go:     const Version = "1.6.0"  → "1.7.0"
  .goreleaser.yml:    (reads from git tag — no change needed)

Use AskUserQuestion: "Update these version strings?" — "Yes, update all" / "Let me choose" / "Skip version bumps"

Step 8: User review

Present everything that will change:

1. The generated changelog entry (fenced markdown block)
2. The version bumps (file-by-file diff preview)
3. What will happen: "Will write CHANGELOG.md, update 2 version files, create release commit, create tag v1.7.0"

If

--dry-run

Use AskUserQuestion:

• "Proceed with this release?"
• Options: "Yes, do it" / "Let me edit the changelog first" / "Abort"

Step 9: Write changes

After user confirms:

1. Update CHANGELOG.md:
   • Find the

     ## [Unreleased]

     line
   • Find where the unreleased section ends (next

     ## [

     line or EOF)
   • Replace with: fresh empty

     ## [Unreleased]

     + blank line + versioned entry
2. Update version files (if user accepted bumps)

Step 10: Generate release notes

Read

references/release-notes.md

• Release notes are not the changelog — they're user-facing, plain-English, no jargon
• Structure: Highlights → What's New → All Changes (condensed) → link to full CHANGELOG
• Write to

  docs/releases/YYYY-MM-DD-v<version>-notes.md

CRITICAL: Release notes MUST be written and staged BEFORE the release commit. GoReleaser checks out the tagged commit — if notes are committed after the tag, CI won't find them and falls back to raw changelog extraction.

Step 11: Write audit trail

Resolve the full local-CI artifact set that backs this release, then write the internal release audit record to

docs/releases/YYYY-MM-DD-v<version>-audit.md

ARTIFACT_JSON="$(./scripts/resolve-release-artifacts.sh <version>)"
ARTIFACT_DIR="$(echo "$ARTIFACT_JSON" | jq -r '.artifact_dir')"

Step 12: Release commit

Stage and commit all release changes together:

git add CHANGELOG.md <version-files...> docs/releases/YYYY-MM-DD-v<version>-notes.md docs/releases/YYYY-MM-DD-v<version>-audit.md
git commit -m "Release v<version>"

The commit message is intentionally simple. The changelog has the details. The release notes and audit trail are included in this commit so the tagged tree contains them.

Step 13: Tag

Create an annotated tag:

git tag -a v<version> -m "Release v<version>"

Step 14: GitHub Release (CI handles this)

Do NOT create a draft GitHub Release locally. GoReleaser in CI is the sole release creator. A local

gh release create --draft

The curated release notes at

docs/releases/YYYY-MM-DD-v<version>-notes.md

extract-release-notes.sh

--release-notes

• sbom-cyclonedx-go-mod.json

• security-gate-summary.json

Step 15: Post-release guidance

Show the user what to do next:

Release v1.7.0 prepared locally.

Next steps:
  git push origin main --tags     # push commit + tag

CI publisher will handle: release publish, GitHub Release page, SBOM/security assets, provenance
  (detected: .github/workflows/release.yml, .goreleaser.yml)
  Curated release notes: docs/releases/YYYY-MM-DD-v1.7.0-notes.md

If no CI detected:

Next steps:
  git push origin main --tags     # push commit + tag
  gh release create v1.7.0 --title "v1.7.0" --notes-file docs/releases/YYYY-MM-DD-v1.7.0-notes.md

No release CI detected. Consider adding a workflow for automated publishing.

Step 16: Audit trail format

The audit record (written in Step 11, committed in Step 12) uses this format:

mkdir -p docs/releases

Write to

docs/releases/YYYY-MM-DD-v<version>-audit.md

# Release v<version> — Audit

**Date:** YYYY-MM-DD
**Previous:** v<previous-version>
**Commits:** N commits in range
**Local CI Artifacts:** `<artifact_dir>/`

## Version Bumps

<files updated>

## Pre-flight Results

<check summary table>

This is an internal record for the knowledge flywheel. It does NOT go on the GitHub Release page — that's the

-notes.md

Two files, two audiences:

*-notes.md

*-audit.md

New Changelog Template

When no

CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

Then proceed with the normal workflow to populate the first versioned entry.

Boundaries

What this skill does

• Pre-flight validation (tests, lint, clean tree, versions, branch)
• Changelog generation from git history
• Semver suggestion from commit classification
• Version string bumps in package files
• Release commit + annotated tag
• Release notes (highlights + changelog) for GitHub Release page
• Curated release notes for CI to publish on GitHub Release page
• Post-release guidance
• Audit trail

What this skill does NOT do

• No publishing — no

  npm publish

  ,

  cargo publish

  ,

  twine upload

  . CI handles this.
• No building — no

  go build

  ,

  npm pack

  ,

  docker build

  . CI handles this.
• No pushing — no

  git push

  , no

  git push --tags

  . The user decides when to push.
• No CI triggering — the tag push (done by the user) triggers CI.
• No monorepo multi-version — one version, one changelog, one tag. Scope for v2.

Everything this skill does is local and reversible:

• Bad changelog → edit the file
• Wrong version bump →

  git reset HEAD~1

• Bad tag →

  git tag -d v<version>

• Bad release notes → edit

  docs/releases/*-notes.md

  before push

Universal Rules

• Don't invent — only document what git log shows
• No commit hashes in the final output
• No author names in the final output
• Concise — one sentence per bullet, technical but readable
• Adapt, don't impose — match the project's existing style rather than forcing a particular format
• User confirms — never write without showing the draft first
• Local only — never push, publish, or trigger remote actions
• Two audiences — CHANGELOG.md is for contributors (file paths, issue IDs, implementation detail). Release notes are for feed readers (plain English, user-visible impact, no insider jargon). Never copy-paste the changelog into the release notes.

Examples

Full Release Workflow

User says:

/release 1.7.0

What happens:

1. Agent runs pre-flight checks (git status, tests, lint, versions)
2. Agent reads git history since last tag (v1.6.0..HEAD)
3. Agent classifies commits into Added/Changed/Fixed/Removed categories
4. Agent generates changelog entry in Keep a Changelog format
5. Agent detects version files (package.json, version.go) and proposes bumps
6. Agent shows draft changelog and version diffs to user for review
7. User approves. Agent writes CHANGELOG.md, updates version files
8. Agent creates release commit and annotated tag (v1.7.0)
9. Agent generates curated release notes (CI uses them for GitHub Release page)
10. Agent displays post-release guidance (push commands)

Result: Local release fully prepared: changelog updated, versions bumped, tag created, draft release ready.

Readiness Check Only

User says:

/release --check

What happens:

1. Agent runs all pre-flight checks (git, tests, lint, versions, commits)
2. Agent outputs GO/NO-GO summary table with pass/fail/warn for each check
3. Agent stops without generating or writing anything

Result: Release readiness report only, no changes made.

Version Suggestion Mode

User says:

/release

What happens:

1. Agent reads git history and classifies commits
2. Agent suggests version based on classification (major if breaking, minor if features, patch if fixes only)
3. Agent shows suggestion with reasoning: "Suggested version: 1.7.0 (minor). Reason: 3 new features added, no breaking changes."
4. Agent asks user to confirm or provide different version
5. Agent continues with user-selected version

Result: Suggested version based on commit analysis, user confirms or overrides.

Troubleshooting

--skip-checks

gh release create

See Also

• deps — Dependency audit and vulnerability scanning

Reference Documents

• references/release-cadence.md
• references/release-notes.md