release

Release

Create a versioned GitHub release: detect the current version, update the version manifests, commit, tag, push, and let gh release create --generate-notes write the release-page notes. The repository's CHANGELOG.md is not this skill's file — dev:post-merge Step 9.5 and docs:changelog own it.

Guidelines

• Interactive input is capability-aware. Every prompt and confirmation below is a gate, not one hardcoded tool: AskUserQuestion under Claude Code, request_user_input under Codex where exposed, otherwise one concise blocking question asked before the irreversible action (the tag, the push, gh release create). Full policy: AGENTS.md → "Cross-runtime interactive input policy".
• The tag and the release are public and irreversible. Never run Steps 8-9 without the Step 5 confirmation, and never publish a tag this run did not create.

Arguments

• Version (optional): Explicit version string, e.g., 1.2.0
• --patch / --minor / --major: Semver bump shorthand (overrides auto-detection)
• --dry-run: Preview version bump and changelog without creating anything
• --draft: Create as draft release on GitHub
• --prerelease: Mark as pre-release on GitHub
• --skip-validation: Skip build/test verification before releasing
• --init <commit>: Create initial baseline tag (for first-ever release)

Workflow

1. Check Prerequisites

   • Verify gh CLI is installed and authenticated: gh auth status
   • Verify clean working tree: git status --porcelain
     • If uncommitted changes exist, prompt user to commit or stash first
   • Verify current branch is pushed to remote: git rev-parse --abbrev-ref --symbolic-full-name @{u}. No upstream means the tag would point at a commit GitHub cannot see — stop and have the user push the branch first.

2. Detect Previous Tag

   • Run git fetch --tags and then git tag --list 'v[0-9]*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -t. -k1.2,1n -k2,2n -k3,3n | tail -1 to find the highest existing release tag; the strict vX.Y.Z filter keeps v2, pre-release and nightly tags out of the pick. Do not use git describe --tags --abbrev=0: it returns the nearest tag reachable from HEAD, which is not the latest version whenever a higher tag lives on another branch — and that single value feeds both the bump base and --notes-start-tag.
   • If no tags exist:
     • If --init <commit> provided: create baseline tag at specified commit

       git tag v0.0.0 <commit>
       

     • If --init not provided: prompt user with options:
       • Tag current HEAD as v0.0.0 (baseline only, no release)
       • Tag a specific commit as baseline
       • Abort and let user set up tags manually
     • After baseline created, re-run detection