/release

Tag a version, generate changelog, and create a GitHub release.

Usage

/release [version] [--dry-run] [--draft]

Arguments

• version: Semver version (1.2.3) or bump type (patch, minor, major)
• --dry-run: Preview release without creating anything
• --draft: Create as draft release (don't publish)

Instructions

When this skill is invoked:

Agent Behavior

Autonomy:

• Determine version bump from commit history if not specified
• Generate changelog from conventional commits
• Create tag and GitHub release end-to-end

Safety:

• Never release from a dirty worktree
• Never release from a non-main branch without confirmation
• Always run quality checks before tagging

Release Process

Phase 1: Pre-Release Checks

1. Verify clean worktree:

   git status --porcelain

   If dirty, stop and ask user to commit or stash.

2. Verify branch:

   git branch --show-current

   Warn if not main or master.

3. Run quality checks:

   make quality  # or equivalent from prd/00_technology.md

   All checks must pass before release.

4. Get current version:

   git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0"

Phase 2: Determine Version

If version not specified, analyze commits since last tag:

git log $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD --oneline

Auto-bump rules (conventional commits):

• feat!: or BREAKING CHANGE: → major
• feat: → minor
• fix:, perf:, refactor: → patch

Phase 3: Generate Changelog

1. Check for CHANGELOG.md in project root.

   • If it exists, update it (see format below).
   • If it doesn't exist, generate changelog for the GitHub release only.

2. Classify changes using the Breaking Change Policy in CHANGELOG.md.

   • If a commit touches a surface listed in the policy table, check whether it's breaking.
   • If breaking changes are found and the bump type is not major, warn the user.

3. Update CHANGELOG.md (if present):

   • Move items from [Unreleased] into a new [X.Y.Z] - YYYY-MM-DD section.
   • Add the comparison link at the bottom of the file.
   • Categorize entries: Added, Changed, Deprecated, Removed, Fixed, Security.

4. Generate GitHub release notes from commits since last tag:

## What's Changed

### Breaking Changes
- description (#PR)

### Features
- description (#PR)

### Bug Fixes
- description (#PR)

### Performance
- description (#PR)

### Other Changes
- description (#PR)

**Full Changelog**: v1.0.0...v1.1.0

Phase 4: Create Release

1. Update version in package config if applicable:

   # package.json, pyproject.toml, Cargo.toml, etc.

2. Commit version bump (if file changed):

   git add {package_config}
   git commit -m "chore: bump version to {version}"

3. Create annotated tag:

   git tag -a v{version} -m "Release v{version}"

4. Push tag:

   git push origin main --tags

5. Create GitHub release:

   gh release create v{version} --title "v{version}" --notes "{changelog}"
   # or with --draft flag
   gh release create v{version} --title "v{version}" --notes "{changelog}" --draft

Dry Run Mode

When --dry-run is specified:

• Show what version would be created
• Show generated changelog
• Show files that would be modified
• Do NOT create tags, commits, or releases

Version File Locations

Stack	File	Field
Node.js	package.json	version
Python	pyproject.toml	[project] version
Go	No file (tags only)	—
iOS	Info.plist	CFBundleShortVersionString
Android	build.gradle.kts	versionName / versionCode

Example Output

$ /release minor

Pre-release checks...
  Branch: main
  Worktree: clean
  Tests: passing (142/142)
  Lint: clean
  Current version: v1.2.0

Analyzing commits since v1.2.0...
  3 features, 2 fixes, 1 refactor

Bumping: v1.2.0 → v1.3.0

Changelog:
  ## What's Changed
  ### Features
  - Add OAuth2 login support (#45)
  - Add user avatar uploads (#48)
  - Add dark mode toggle (#52)
  ### Bug Fixes
  - Fix memory leak in image processing (#46)
  - Fix pagination on user list (#50)

Creating release...
  Updated package.json version
  Created tag v1.3.0
  Pushed to origin/main
  Created GitHub release: https://github.com/org/repo/releases/tag/v1.3.0

Release v1.3.0 published!