Release

---
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`
and update it per step, because authorisation and progress have to live where a
compaction cannot reach them.

**Write it once Stage 0's slate-clean gate returns `0`, not before** — see
"The release state file" in RELEASING.md for why that ordering is load-bearing.
A release stopped AT the slate gate never started, and a state file written
ahead of it deadlocks the very stop the gate asks for (Plan 00407 N1).

- **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).

## Run this first

Claude Code loads this markdown and nothing else — the file below is not run
for you, and it holds the procedure to follow (Plan 00324):

```bash
bash "${CLAUDE_SKILL_DIR:-.claude/skills/release}/invoke.sh" <major|minor|patch|X.Y.Z>
```

Follow its output exactly; what is written here is orientation.

## 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 first runs the full QA gate on the clean HEAD (RELEASING.md Step 1b;
the agent is a sub-agent and cannot), then invokes the Release Agent
(`.claude/agents/release-agent.md`) to:

- Validate environment (git state, QA via `--read-only`, 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 and pre-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