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

Argument	Required	Description
version	No	Semver string (e.g., 1.7.0). If omitted, suggest based on commit analysis
--check	No	Readiness validation only — don't generate or write anything
--dry-run	No	Show generated changelog + version bumps without writing
--skip-checks	No	Skip pre-flight validation (tests, lint)
--changelog-only	No	Only update CHANGELOG.md — no version bumps, no commit, no tag

---

Modes

Default: Full Release

/release [version] — the complete local release workflow.

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

Check Mode

/release --check — standalone readiness validation.

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

Changelog Only

/release 1.7.0 --changelog-only — just update CHANGELOG.md.

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 MUST run the repo-root ci-local-release.sh gate first. If it fails, stop the release workflow and report the failing checks. The local CI gate writes publishable artifacts to .agents/releases/local-ci/<timestamp>/, including SBOM files, a full security scan report, and release-artifacts.json. Once the target version is known, rerun the gate as ./scripts/ci-local-release.sh --release-version <version> so the artifact manifest matches the final release version. Use ./scripts/resolve-release-artifacts.sh <version> when writing the audit trail.

Checks:

Check	How	Severity
Git repo	git rev-parse --git-dir	Block — cannot proceed
CHANGELOG.md exists	Glob for changelog (case-insensitive)	Offer to create if missing
Has [Unreleased] section	Read CHANGELOG.md	Warn
Working tree clean	git status --porcelain	Warn (show dirty files)
On expected branch	git branch --show-current	Warn if not main/master/release
Local CI parity gate	repo-root ci-local-release.sh	Block — must pass before release
Publishable SBOM	Generated by local CI gate (CycloneDX + SPDX)	Block — required artifact
Security scan report	Generated by local CI gate (full toolchain scan JSON)	Block — required artifact
Tests pass	Detect and run test command	Warn (show failures)
Lint clean	Detect and run lint command	Warn (show issues)
Dependency vulnerabilities	Run /deps vuln to confirm no critical vulnerabilities ship with this release	Warn (show findings)
Version consistency	Compare versions across package files	Warn (show mismatches)
Manifest versions sync	Compare .claude-plugin/plugin.json and marketplace.json versions	Warn (show mismatches)
Commits since last tag	git log --oneline <range>	Block if empty — nothing to release
Unconsumed high-severity findings	Count items in .agents/rpi/next-work.jsonl where consumed=false and severity=high	Warn — not a blocker (see check below)

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:

File	Test Command	Lint Command
go.mod	go test ./...	golangci-lint run (if installed)
package.json	npm test	npm run lint (if script exists)
pyproject.toml	pytest	ruff check . (if installed)
Cargo.toml	cargo test	cargo clippy (if installed)
Makefile with test:	make test	make lint (if target exists)

If --skip-checks is passed, skip ad-hoc test/lint detection only. It does not skip the repo-root ci-local-release.sh gate.

In --check mode, run all checks and output a summary table:

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 mode, stop here. In default mode, continue (warnings don't block).

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 for the summary view and full hashes for detail lookups when a commit message is ambiguous.

Step 4: Classify and group

Classify each commit into one of four categories:

Category	Signal
Added	New features, new files, "add", "create", "implement", "introduce", feat
Changed	Modifications, updates, refactors, "update", "refactor", "rename", "migrate"
Fixed	Bug fixes, corrections, "fix", "correct", "resolve", "patch"
Removed	Deletions, "remove", "delete", "drop", "deprecate"

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:

Condition	Suggestion
Any commit contains "BREAKING", "breaking change", or !: (conventional commits)	Major bump
Any commits classified as Added (new features)	Minor bump
Only Fixed/Changed commits	Patch bump

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 format.

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:

File	Pattern	Example
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" or var version = "X.Y.Z"	const Version = "1.6.0"
version.txt	Plain version string	1.6.0
VERSION	Plain version string	1.6.0
.goreleaser.yml	Version from ldflags (show, don't modify — goreleaser reads from git tags)	—

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 was passed, stop here.

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 for the full release notes format, quality bar, condensing rules, and examples. Key points:

• 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 (see Step 16 format). Stage it alongside the release notes.

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