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 .claude/config.json (optional)
• 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 name to build
xcbuild.simulatorId	Default simulator UUID
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