release

Release Skill

Purpose: Take a project from "code is ready" to "tagged, pushed by the operator, and verified green on the exact tagged SHA."

Pre-flight validation, changelog from git history, version bumps across package files, release commit, annotated tag, curated release notes, and post-push exact-SHA CI verification. Local preparation is 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

| Mode | Invocation | Behavior | |---|---|---| | Full Release | /release [version] | Pre-flight → changelog → release notes → version bump → user review → write → release commit → tag → push guidance → exact-SHA CI verification. | | Check | /release --check | Pre-flight checks only; reports GO/NO-GO. Composable with /vibe. No writes. | | Changelog Only | /release X.Y.Z --changelog-only | Updates CHANGELOG.md only — no version bumps, no commit, no tag. |

Workflow

Read [references/release-workflow-detail.md](references/release-workflow-detail.md) for the full per-step procedure — bash commands, check tables, expected output, audit-record template, and worked examples. The index below is for orientation only; the agent must execute against release-workflow-detail.md for correctness.

1. Pre-flight — run scripts/ci-local-release.sh (blocking) plus version/lint/test/branch/changelog/SBOM/security checks. --check mode stops after this step.
2. Determine range — <last-tag>..HEAD. For non-HEAD cuts, see [references/release-cut-and-bump.md](references/release-cut-and-bump.md).
3. Read git history — git log --oneline --no-merges <range> plus stats for ambiguity resolution.
4. Classify and group — Added / Changed / Fixed / Removed for CHANGELOG.md. Notes prose uses the richer 8-label set per [references/release-notes.md](references/release-notes.md).
5. Suggest version — major if breaking, minor if features, patch if only fixes. Confirm via AskUserQuestion.
6. Generate changelog entry — Keep-a-Changelog format, today's date, style-matched to the most recent existing entry.
7. Detect and offer version bumps — generic patterns (package.json, pyproject.toml, etc.) plus AgentOps-specific manifests per [references/release-cut-and-bump.md](references/release-cut-and-bump.md).
8. User review — show generated changelog and version diffs; AskUserQuestion to proceed. --dry-run stops here.
9. Write changes — CHANGELOG.md update + version file edits.
10. Generate release notes — curated docs/releases/YYYY-MM-DD-v<version>-notes.md per [references/release-notes.md](references/release-notes.md). MUST be staged before the release commit.
11. Write audit trail — docs/releases/YYYY-MM-DD-v<version>-audit.md resolved via scripts/resolve-release-artifacts.sh. Format in workflow-detail Step 16.
12. Release commit — git commit -m "Release v<version>" with all release artifacts staged.
13. Tag — annotated git tag -a v<version> -m "Release v<version>".
14. GitHub Release (CI handles this) — do NOT gh release create locally; GoReleaser is sole creator.
15. Post-push exact-SHA CI verification — after the operator pushes, run scripts/verify-release-ci.sh v<version> and ao reconcile --json; do not declare the release complete until exact-SHA verification prints GO release-ci and reconciliation shows the latest release tag Validate as green or a newer tag explicitly supersedes an older failed tag.
16. Post-release guidance — show push commands and the verification command; do NOT push.
17. Audit trail format — see workflow-detail for the markdown template.

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 plus exact-SHA CI verification instructions
• 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
• Not done at tag — after the user pushes, verify a green validate.yml run for the exact tagged SHA, run ao reconcile --json, and record the run id, conclusion, reconciliation overall status, and release-tag finding state in the handoff or release audit notes.
• Supersede historical red tags deliberately — do not hand-wave an older failed tag Validate run. Either fix/rerun the tag pipeline when appropriate or cut a newer release tag whose ao reconcile release evidence is green.
• 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

User says: /release 1.7.0 Agent runs pre-flight → reads v1.6.0..HEAD git history → classifies commits → drafts CHANGELOG.md entry + curated release notes → detects version files (package.json, version.go, plugin manifests) → presents draft for review → on approval, writes files, creates release commit, creates annotated tag, prints push guidance, then after the user pushes verifies scripts/verify-release-ci.sh v1.7.0, runs ao reconcile --json, and records the run id/conclusion plus reconciliation state.

User says: /release --check Agent runs all pre-flight checks and outputs a GO/NO-GO summary table. No writes.

User says: /release (no version) Agent classifies commits and suggests a version (major if breaking, minor if features, patch if fixes only) with reasoning, then asks the user to confirm or override.

User says: /release 1.7.0 --dry-run Agent shows what the changelog entry + version bumps would look like, then stops without writing.

See references/release-workflow-detail.md for the full per-step example narration.

Troubleshooting

| Problem | Cause |