git:20260831.cee9211 to git:20260902.20a7e8a

---

name: release

description: Automated release management - version updates, changelog generation, git tagging, and GitHub release creation

argument-hint: "[major|minor|patch|X.Y.Z]"

---

# /release - Automated Release Management Skill

## 🚨 HUMAN-GATED — this skill is the ONLY valid entry point

**A release may only begin when a human invokes `/release` in the CURRENT

session. An agent must never start a release on its own initiative. The

`/release` invocation is the ONLY authorisation there is: once the pipeline's

blocking gates pass, the release proceeds through tag and publish with no

secondary human confirmation — it passes, or a failed gate aborts it.**

A release is a decision about **scope**, and scope is not visible from inside

the repository: only the human knows which work belongs in the bundle. A clean

tree, a fully green QA run and a bumped version say a release *would be sound*, never that

it is *wanted now*.

**A release may legitimately span a compaction, and must then be FINISHED** — a

half-done release (version bumped, `UNRELEASED/` dirs moved, nothing tagged) is

its own broken state. So this skill MUST write `untracked/release-state.json` as

its first action and update it per step, because authorisation and progress have

to live where a compaction cannot reach them.

- **No state file ⇒ no release in progress.** A dirty tree or a plan saying

"finish the release" is not a substitute — ask.

- **State file present ⇒ resume** from `last_completed_step` and carry the

release through to Step 15 — the recorded `/release` authorisation covers

tagging and publishing.

Do not START a release because a cron tick fired, because a plan says "finish

the release", or because the tree looks ready — no state file means no release.

See **[RELEASING.md](../../../CLAUDE/development/RELEASING.md)** — "A RELEASE IS

HUMAN-GATED" — for the full rule, the state-file schema, and how to recover from

an unauthorised release (never silently unpublish).

## Description

Automate the complete release process: version updates, changelog generation, Opus review, git tagging, and GitHub release creation.

## Usage

```claude-code

# Auto-detect version bump from commits

/release

# Specify version explicitly

/release 2.2.0

# Specify bump type

/release patch # x.y.Z

/release minor # x.Y.0

/release major # X.0.0

```

## Parameters

- **version** (optional): Target version (e.g., "2.2.0") or bump type ("major", "minor", "patch")

- If omitted: Auto-detect from commit history

## What It Does

Executes the release pipeline defined in

**[RELEASING.md](../../../CLAUDE/development/RELEASING.md)** "Pipeline

Overview" — the single source of truth for the steps, their order, their

numbering, and which of them are BLOCKING gates. This skill does not restate

that list; when a step number is cited anywhere in this file, it is

RELEASING.md's numbering.

**CRITICAL**: Release process ABORTS immediately on ANY validation failure or if blocking gates fail. NO auto-fixing of QA issues or git state.

## Agent

Uses the specialized Release Agent (`.claude/agents/release-agent.md`):

- Model: Sonnet 4.5 (main workflow)

- Review: Opus 4.5 (final validation)

- Tools: Bash, Read, Edit, Write, Grep, Glob, Task

## Process Flow

See the "Pipeline Overview" in

[RELEASING.md](../../../CLAUDE/development/RELEASING.md) — the canonical

step-by-step flow. Any blocking-gate failure at any point ABORTS the release

immediately.

## Output

On success:

```

✅ Release v2.2.0 Complete!

📦 Version: 2.2.0 (MINOR release)

🏷️ Tag: v2.2.0

📝 Changelog: CHANGELOG.md

📋 Release Notes: RELEASES/v2.2.0.md

🔗 GitHub Release: https://github.com/.../releases/tag/v2.2.0

Installation command:

git clone -b v2.2.0 https://github.com/.../hooks-daemon.git

```

## Error Handling

Common errors with fixes:

**Dirty Git State:**

```

❌ Uncommitted changes detected

Fix: Commit or stash changes, then retry

```

**QA Failures:**

```

❌ Tests failing: 3 failed, 1165 passed

Fix: Run ./scripts/qa/llm_qa.py all, fix issues, retry

```

**Opus Rejects (Documentation Issues Only):**

```

⚠️ Opus found documentation issues:

- Typo in release notes

- Missing changelog entry

Fixing documentation and re-submitting...

```

**Note**: Opus ONLY reviews release documentation (changelog/release notes), NOT code or QA issues.

**Upgrade Guide Incomplete (Breaking Changes Check failure, RELEASING.md Step 9):**

```

❌ Breaking changes detected but upgrade guide incomplete

Breaking changes found:

- Handler removed: validate_sitemap

- Handler renamed: git_blocker → destructive_git

Upgrade guide: CLAUDE/UPGRADES/v2/v2.11-to-v2.12/v2.11-to-v2.12.md

Issues:

- Missing deprecation reason for validate_sitemap removal

- Missing migration examples for git_blocker rename

- Verification steps need customization

Fix: Complete upgrade guide (remove auto-generated warning), then retry

```

**Tag Exists:**

```

❌ Tag v2.2.0 already exists

Fix: Use different version

```

## Requirements

**ALL requirements are MANDATORY. Release ABORTS if any fail:**

- **Clean git state**: No uncommitted changes, no untracked files in src/

- **All QA passing**: Format, Lint, Type Check, Tests (95% coverage), Security (Bandit)

- **GitHub CLI authenticated**: `gh auth status` must succeed

- **Write access**: Repository push permissions required

**NO auto-fixing**: User must manually resolve all issues before retry.

## Orchestration Details

This skill orchestrates a multi-stage release process through main Claude. The release agent cannot spawn nested agents, so main Claude manages the workflow.

### Stage 1: Release Agent Preparation (RELEASING.md Steps 1-6)

Main Claude invokes the Release Agent (`.claude/agents/release-agent.md`) to:

- Validate environment (git state, QA, GitHub CLI)

- Detect/confirm version bump

- Update version files

- Generate CHANGELOG.md entry

- Create release notes

- **Detect breaking changes automatically**

- **Generate upgrade guide templates (if breaking changes)**

- Prepare summary for Opus review

### Stage 2: Opus Documentation Review (RELEASING.md Step 7)

Main Claude invokes ad-hoc Opus 4.5 agent to review:

- Version consistency across files

- CHANGELOG.md accuracy and format

- Release notes quality

- Breaking changes flagged correctly

- Upgrade guide existence (if breaking changes)

Opus does NOT review code or QA issues - only documentation.

### Stage 3: QA Verification Gate (RELEASING.md Step 8 - BLOCKING GATE)

Main Claude runs full QA suite manually - see RELEASING.md Step 8.

### Stage 4: Upgrade Guide Verification (RELEASING.md Step 9, Breaking Changes Check - BLOCKING GATE)

**CRITICAL**: This gate is MANDATORY if breaking changes detected.

Main Claude executes:

1. **Check Breaking Changes Flag**:

- Review Release Agent output for breaking changes

- If breaking changes detected, proceed to verification

- If no breaking changes, this gate passes with nothing to verify

2. **Verify Upgrade Guide Exists**:

```bash

# Determine version jump from Release Agent output

OLD_VERSION="2.11" # From last tag

NEW_VERSION="2.12" # From target version

MAJOR="2"

UPGRADE_DIR="CLAUDE/UPGRADES/v${MAJOR}/v${OLD_VERSION}-to-v${NEW_VERSION}"

if [ ! -d "$UPGRADE_DIR" ]; then

echo "❌ ABORT: Breaking changes detected but upgrade guide missing"

echo "Expected: $UPGRADE_DIR"

exit 1

fi

```

3. **Verify Guide Completeness**:

```bash

GUIDE_FILE="${UPGRADE_DIR}/v${OLD_VERSION}-to-v${NEW_VERSION}.md"

# Check for auto-generated warning (indicates incomplete)

if grep -q "AUTO-GENERATED UPGRADE GUIDE - HUMAN REVIEW REQUIRED" "$GUIDE_FILE"; then

echo "❌ ABORT: Upgrade guide needs human review"

echo ""

echo "Guide location: $GUIDE_FILE"

echo ""

echo "Complete these sections:"

grep -A 5 "HUMAN REVIEW REQUIRED" "$GUIDE_FILE"

echo ""

echo "Remove the warning comment after completing review."

exit 1

fi

```

4. **Verify Required Sections Populated**:

```bash

# Check for placeholder text that needs filling

if grep -q "NEEDS HUMAN REVIEW" "$GUIDE_FILE"; then

echo "❌ ABORT: Upgrade guide has incomplete sections"

echo ""

grep -n "NEEDS HUMAN REVIEW" "$GUIDE_FILE"

echo ""

echo "Complete all sections marked 'NEEDS HUMAN REVIEW'"

exit 1

fi

```

5. **Verify Supporting Files Exist**:

```bash

if [ ! -f "${UPGRADE_DIR}/config-before.yaml" ]; then

echo "⚠️ Warning: config-before.yaml missing"

fi

if [ ! -f "${UPGRADE_DIR}/config-after.yaml" ]; then

echo "⚠️ Warning: config-after.yaml missing"

fi

```

**If this gate FAILS**:

- ABORT release immediately

- Display clear error message with guide location

- List incomplete sections

- User must complete guide manually

- User re-runs `/release` after completion

**If this gate PASSES**:

- Proceed to the remaining blocking gates below

### Stage 5: Code Review Gate (RELEASING.md Step 10 - BLOCKING GATE)

Main Claude reviews `git diff <last-tag>..HEAD -- src/` for bugs, security issues, and quality problems - see RELEASING.md Step 10.

### Stage 6: CLAUDE.md Guidance Audit (RELEASING.md Step 11 - BLOCKING GATE)

Coverage of `get_claude_md()` is enforced by an integration test that Step 8's

QA run already executes; confirm it explicitly - see RELEASING.md Step 11.

### Stage 7: Acceptance Testing Gate (RELEASING.md Step 12 - BLOCKING GATE)

Main Claude executes acceptance tests - scope depends on bump type:

- MAJOR/MINOR: full test suite - see RELEASING.md Step 12

- PATCH + handler changes: targeted tests for changed handlers only

- PATCH + no handler changes: skip, document reason in release notes

### Stage 8: Finalization (RELEASING.md Steps 13-15)

Main Claude commits, tags, and publishes - see RELEASING.md Steps 13-15.

Steps 14-15 (tag, GitHub release) proceed as soon as every blocking gate has

passed — the original `/release` invocation is the authorisation; there is no

secondary confirmation step.

## Documentation

**📖 SINGLE SOURCE OF TRUTH:** [CLAUDE/development/RELEASING.md](../../../CLAUDE/development/RELEASING.md)

This skill implements the process defined in the release documentation. For complete details on:

- Pre-release validation steps

- UNRELEASED post-upgrade-tasks move (Step 6)

- Breaking changes detection and upgrade guide generation

- Upgrade guide verification gate

- Acceptance testing requirements and FAIL-FAST cycle (Step 12)

- Version detection rules

- Changelog generation format

- Post-release procedures

**See the release documentation above.** The documentation is the authoritative source - this skill follows it.

## Version

Introduced in: v2.2.0