scarrillo-release

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: