Release Toolkit Plugin For Claude Code

A Claude Code plugin for release automation. Semantic versioning, changelogs, architectural decisions, and TestFlight integration.

Why Use This?

Release management is tedious. This plugin automates the repetitive parts:

• Version Management - Increment versions per SemVer, commit, and tag in one command
• Changelogs - Problem/Solution format from your session, not vague commit messages
• Decisions - Capture the "why" behind choices, even ones you didn't implement
• TestFlight notes - Beta tester instructions derived directly from your changelog

About

Renamed from "Changelog Plugin" - Now a comprehensive release toolkit with semantic versioning, changelogs, and more. Commands are now namespaced under release: (e.g., /release:changelog).

Requirements

• Claude Code CLI

Installation

# Add the marketplace
/plugin marketplace add scarrillo/release
# Install the plugin
/plugin install release@scarrillo

Commands

Command	Description	Output
/release:release	Increment version (SemVer), commit, tag	Git commit + rel.vX.Y.Z tag
/release:changelog	Generate changelog from session work	changelog.md + changelog-public.md
/release:decisions	Capture decisions and proposals	decisions.md
/release:whattotest	Generate TestFlight testing guide	TestFlight/WhatToTest.en-US.txt
/release:xcbuild	Build iOS/macOS app with auto-detection	Build output with warnings/errors

Note: Commands are namespaced with release: prefix when installed via marketplace.

Workflow

/release:changelog # Document completed work
↓
/release:decisions # Capture decisions (prompted)
↓
/release:whattotest # Generate test notes (prompted)
↓
/release:release # Increment version, commit, tag

Or run any command standalone.

Features

/release:release

• Increment version per SemVer (major, minor, patch)
• Auto-detects project type: Claude Plugin, Xcode (more platforms coming)
• Prompts to generate changelog before committing
• Updates version file(s), commits, and creates git tag
• tag option for CI/CD triggers without version change

/release:changelog

• Uses current session context as primary source
• Cross-references with git to deduplicate
• Problem/Solution format with code snippets
• Generates two files:
  • changelog.md - Technical developer notes
  • changelog-public.md - User-friendly release notes

/release:decisions

• Documents decisions regardless of implementation status
• Tracks: Implemented, Proposed, Deferred, Rejected
• Records rationale and trade-offs

/release:whattotest

• Derives content from changelog-public.md
• Creates TestFlight/ folder structure
• Tester-focused, actionable format
• Stays within 4000 character limit

/release:xcbuild

• Auto-detects .xcworkspace or .xcodeproj in current directory
• Lists available schemes and recommends main app target
• Queries available simulators and recommends latest iPhone Pro
• Caches selections for fast subsequent builds
• Persists settings to plugin config files:
  • Scheme → .claude/config.json (project/team default)
  • Simulator → .claude/config.local.json (gitignored, machine-specific)
• Arguments: --change (re-select), --scheme=<name>, --id=<UUID>

Supported Project Types

Project Type	Detection	Version Location
Claude Plugin	.claude-plugin/plugin.json	plugin.json + marketplace.json
Xcode (iOS/macOS)	*.xcodeproj	project.pbxproj → MARKETING_VERSION

More platforms coming: Next.js, Android, Flutter, React Native.

Fun fact: This plugin can release itself. We used /release:release to publish v1.2.0.

Sample Output

This plugin documents itself. View real output in this repo:

File	Description
docs/changelog.md	Developer changelog with Problem/Solution format
docs/changelog-public.md	User-facing release notes
docs/decisions.md	Architectural decisions and proposals
TestFlight/WhatToTest.txt	Beta tester instructions

Configuration

Model Selection

On first run, you'll be prompted to choose which model to use:

Model	ID	Use Case
Current	inherit	Use conversation's model (default)
Opus 4.5	claude-opus-4-5-20251101	Most capable
Sonnet 4	claude-sonnet-4-20250514	Balanced (recommended)
Haiku 3.5	claude-3-5-haiku-20241022	Fastest

This allows Opus users to hand off tasks to a faster model. Your choice can be saved to config.

Command Flags

/release:changelog --auto # Run all follow-ups automatically
/release:changelog --skip # No follow-ups
/release:changelog --decisions # Auto-run decisions only
/release:changelog --no-whattotest # Skip whattotest prompt

Persistent Config

Create .claude/config.json in your project (a sample is included). Settings are namespaced under release-plugin:

{
"release-plugin": {
"model": "claude-sonnet-4-20250514",
"changelog": {
"outputPath": "./changelog.md",
"followUp": {
"decisions": "ask",
"whattotest": "ask"
}
},
"decisions": {
"outputPath": "./decisions.md"
},
"whattotest": {
"onExisting": "ask"
},
"release": {
"gitMode": "auto"
},
"xcbuild": {
"scheme": "MyApp",
"simulatorId": "UUID",
"showWarnings": true
}
}
}

Option	Values
model	"inherit", "claude-opus-4-5-20251101", "claude-sonnet-4-20250514", "claude-3-5-haiku-20241022"
outputPath	"./file.md", "./docs/file.md", custom
followUp.*	"always", "ask", "never"
onExisting	"prepend", "replace", "ask"
gitMode	"auto" (Claude runs git), "manual" (show commands only)
xcbuild.scheme	Default scheme (in .claude/config.json)
xcbuild.simulatorId	Default simulator UUID (in .claude/config.local.json)
xcbuild.showWarnings	true (show warnings), false (errors only)

When prompted for choices, you can save them to config for future runs.

Command-line flags override config settings.

License

MIT