Xcode release automation for Claude Code: SemVer bumps and tags, changelogs, decisions tracking and TestFlight notes for iOS/macOS apps

version
1.3.4
GitHub stars
10

Install

/plugin install release@scarrillo-release

Run it inside Claude Code after adding the marketplace with /plugin marketplace add scarrillo/release.

Contents

Discovered from source

Commands 5

Changelog Generator

Generate a comprehensive changelog document based on recent changes in this project.

Model Selection

Before generating the changelog, check for model preference:

  1. Check config for release-plugin.model setting

  2. If not set, ask the user: "Which model should I use for changelog generation?"

    1. Current model (inherit from conversation)
    2. Claude Opus 4.5 (claude-opus-4-5-20251101) - Most capable
    3. Claude Sonnet 4 (claude-sonnet-4-20250514) - Balanced (Recommended)
    4. Claude Haiku 3.5 (claude-3-5-haiku-20241022) - Fastest

    Then ask: "Save this as default for this project?"

    • If yes, persist to .claude/config.json under release-plugin.model

Note: Model selection applies to all plugin commands (changelog, decisions, whattotest).

Instructions

  1. Analyze recent changes using this priority order:

    Primary source - Current session:

    • Review all work completed in this conversation session
    • Include files created, modified, features implemented, and bugs fixed
    • This is the most accurate and detailed source of recent work

    Cross-reference with git to deduplicate:

    • Check recent git commit history (git log)
    • Check staged changes (git diff --staged)
    • Check unstaged changes (git diff)
    • Use git data to verify session work and avoid duplicate entries
    • If work from the session has already been committed, use the commit info to enrich the changelog entry (commit hash, timestamp)

    Handle uncommitted session work:

    • If session work is not yet committed, ask the user:
      1. "Commit first" - Let the user commit their changes, then proceed
      2. "Include uncommitted" - Generate changelog including uncommitted session work
      3. "Skip uncommitted" - Only include work that has been committed

    Reference existing changelogs:

    • Check any existing changelog files for format consistency and to avoid re-documenting old changes
  2. Categorize changes into:

    • Features: New functionality added
    • Improvements: Enhancements to existing features
    • Bug Fixes: Issues that were resolved
    • Breaking Changes: Changes that may affect existing functionality (if any)
  3. Generate two summaries (in this order):

Internal Developer Summary (write this first)

Create comprehensive technical notes for the development team using Problem/Solution format. This is the authoritative record of all changes.

For each change, include:

  • Problem: What issue or need prompted this change?
  • Solution: How was it solved? Include relevant code snippets.
  • How It Works: For complex features, explain the implementation logic
  • Files Changed: List of files modified/created with brief description of each
  • Dependencies: Any packages added/updated
  • Migration Notes: Steps needed if applicable
  • Known Issues: Any limitations or issues to be aware of

Public User-Facing Summary (derive from developer summary)

Based on the Internal Developer Summary above, create a simplified user-friendly version:

  • Translate technical features into user benefits
  • Rewrite improvements in plain, non-technical language
  • Describe bug fixes by the problem they solve (not the technical fix)
  • Omit: Internal refactoring, technical debt, developer tooling changes, implementation details users don't need to know

Output Location

Two files are generated:

  • changelog.md - Internal Developer Summary (comprehensive technical notes)
  • changelog-public.md - Public User-Facing Summary (user-friendly release notes)

Both files are created in the same location.

If changelog.md doesn't exist, ask the user: "Where should I create the changelog files?"

  1. Project root (./changelog.md and ./changelog-public.md)
  2. Documentation folder (./docs/changelog.md and ./docs/changelog-public.md)
  3. Custom location (let user specify)

If changelog.md already exists, use its current location for both files.

If files exist: Prepend new entries after the header (newest entries at top). Read existing content first to avoid duplicates and maintain format consistency.

Output Format

changelog.md (Internal Developer Summary)

# Changelog

## [Version] - YYYY-MM-DD

#### [Feature/Fix Name]

**Problem**: [Description of the issue or need]

**Solution**: [How it was solved]

```swift
// Relevant code snippet showing the implementation

How It Works: [For complex features, explain the logic]

Files Changed:

  • path/to/file.swift - [what changed]
  • path/to/another.swift - [what changed]

Dependencies: [Any added/updated, or "None"]

Known Issues: [Any limitations, or "None"]



### changelog-public.md (Public User-Facing Summary)

```markdown
# Release Notes

## [Version] - YYYY-MM-DD

### What's New
- [User-friendly feature description]

### Improvements
- [User-friendly improvement description]

### Bug Fixes
- [User-friendly fix description]

---

After Changelog Generation

Once the changelog is complete, ask the user about follow-up documentation:

  1. Decisions: "Were there any decisions or proposals discussed this session that should be documented?"

    • If yes, run /decisions to capture decisions, proposals, and trade-offs from the session
    • This includes implemented decisions, deferred ideas, and rejected approaches
  2. WhatToTest (Xcode projects only):

    • Check config for release-plugin.whattotest.enabled setting
    • If not set, detect if this is an Xcode project by checking for: .xcodeproj, .xcworkspace, Package.swift, or Podfile
    • If Xcode project detected (or enabled: true in config):
      • Ask: "Would you like me to generate TestFlight WhatToTest from the public-facing summary?"
      • Offer to save preference: "Save this as default for this project?"
    • If not an Xcode project (and no config override), skip this prompt
    • If yes, use the Public User-Facing Summary to generate WhatToTest.en-US.txt
    • Do not re-analyze - derive directly from the public summary

Arguments

$ARGUMENTS

Version/date range: Scope changelog to specific version or time period

  • /release:changelog v1.2.0
  • /release:changelog 2024-01-01

Follow-up behavior flags:

  • --auto - Automatically run both /decisions and /whattotest without asking
  • --ask - Ask before running each follow-up (default)
  • --skip - Skip all follow-ups, only generate changelog
  • --decisions - Auto-run /decisions only
  • --whattotest - Auto-run /whattotest only
  • --no-decisions - Skip /decisions prompt
  • --no-whattotest - Skip /whattotest prompt

Examples:

  • /release:changelog --auto - Generate all docs without prompts
  • /release:changelog --skip - Only changelog, no follow-ups
  • /release:changelog v1.2.0 --decisions --no-whattotest - Version 1.2.0, auto-run decisions, skip whattotest

Configuration File

Check for .claude/config.json at project root. Look for settings under the release-plugin namespace:

{
  "release-plugin": {
    "model": "claude-sonnet-4-20250514",
    "changelog": {
      "outputPath": "./changelog.md",
      "followUp": {
        "decisions": "ask",
        "whattotest": "ask"
      }
    },
    "decisions": {
      "outputPath": "./decisions.md"
    },
    "whattotest": {
      "onExisting": "ask"
    }
  }
}

Config Options

release-plugin.model: Model for all plugin commands

  • "inherit" - Use current conversation model (default)
  • "claude-opus-4-5-20251101" - Most capable
  • "claude-sonnet-4-20250514" - Balanced (recommended)
  • "claude-3-5-haiku-20241022" - Fastest

release-plugin.changelog.outputPath: "./changelog.md" | "./docs/changelog.md" | custom path release-plugin.changelog.followUp.decisions: "always" | "ask" | "never" release-plugin.changelog.followUp.whattotest: "always" | "ask" | "never" release-plugin.decisions.outputPath: "./decisions.md" | "./docs/decisions.md" | custom path release-plugin.whattotest.enabled: "auto" (detect Xcode project) | true | false release-plugin.whattotest.outputPath: "./TestFlight/WhatToTest.en-US.txt" | custom path release-plugin.whattotest.onExisting: "prepend" | "replace" | "ask"

Persisting User Choices

When prompting the user for a location or preference, offer to save their choice: "Would you like to save this preference to .claude/config.json for future runs?"

If yes:

  1. Check if .claude/config.json exists in the project root
  2. If not, create the .claude/ directory and config.json file
  3. Read existing config (if any) to preserve other settings
  4. Add/update the setting under the release-plugin namespace
  5. Write the updated config back to the file

Example - saving changelog outputPath:

# Create .claude directory if needed
mkdir -p .claude

# Write config with the user's preference
{
  "release-plugin": {
    "changelog": {
      "outputPath": "./docs/changelog.md"
    }
  }
}

Command-line arguments override config file settings.

Decisions Document Generator

Capture decisions and proposals from the current session for future reference. Includes both implemented decisions and proposals still under consideration.

Model: Uses the model configured in release-plugin.model (see /release:changelog for model selection).

How to Run

  • Standalone: Run /decisions directly at any point to capture decisions from the current session
  • From /release:changelog: After generating a changelog, you'll be prompted to run this command

When to Use

  • After discussing architectural approaches
  • When a decision was made (implemented or not)
  • When proposals were explored but deferred
  • After comparing solutions or libraries
  • When trade-offs were evaluated
  • After a research or exploration session (even without code changes)

Instructions

  1. Review current session for:

    • Decisions made (with rationale)
    • Proposals discussed (implemented or not)
    • Approaches compared
    • Trade-offs evaluated
    • Ideas deferred for later
  2. Capture regardless of implementation status:

    • Implemented → document the decision and link to changelog
    • Not implemented → document as proposal for future review
    • Rejected → document why it was rejected (valuable context)
  3. Organize by topic for easy future reference

Output Location

If decisions.md doesn't exist, ask the user: "Where should I create the decisions document?"

  1. Project root (./decisions.md)
  2. Documentation folder (./docs/decisions.md)
  3. Same location as changelog (if it exists)
  4. Custom location (let user specify)

If decisions.md already exists, use its current location.

If file exists: Prepend new entries after the # Decisions & Proposals header (newest entries at top). Read existing content first to avoid duplicates.

Output Format

Structure:

# Decisions & Proposals

## [Topic/Feature Area] - YYYY-MM-DD

### Status: [Implemented | Proposed | Rejected | Deferred]

### Context
[What problem or question prompted this decision/proposal?]

### Proposal
[What was proposed or decided?]

### Options Considered
1. **[Option A]**: [Brief description]
   - Pros: [advantages]
   - Cons: [disadvantages]

2. **[Option B]**: [Brief description]
   - Pros: [advantages]
   - Cons: [disadvantages]

### Decision
[What was decided, or "Pending review" if still a proposal]

### Rationale
[Why this approach was chosen/proposed]

### Trade-offs Accepted
[What compromises come with this decision]

### References
- [Links to docs, samples, related PRs]

---

Status Definitions

  • Implemented: Decision was made and code was written (see changelog)
  • Proposed: Idea discussed, not yet implemented, worth revisiting
  • Deferred: Good idea, but intentionally postponed
  • Rejected: Considered and decided against (document why)

Arguments

If a specific topic is provided, scope to that area: $ARGUMENTS

Release Version Manager

Interactive version management for software projects. Automates semantic versioning (SemVer), project file updates, and git tag creation.

Model: Uses the model configured in release-plugin.model (see /release:changelog for model selection).

Instructions

1. Detect Project Type

Check for project files in the project root only (not recursively) in this order:

Project TypeDetectionVersion File(s)
Claude Plugin.claude-plugin/plugin.json in project rootplugin.json + marketplace.json → version
Xcode (iOS/macOS)*.xcodeproj directory in project rootproject.pbxproj → MARKETING_VERSION
(Future: Next.js)package.json + next.config.*package.json → version
(Future: Android)build.gradle or build.gradle.ktsbuild.gradle → versionName

Important: Only check the immediate project root for detection files. Do not search subdirectories to avoid finding installed plugins, dependencies, or nested projects.

If no supported project type found: "No supported project detected. Currently supports: Claude Plugin, Xcode (iOS/macOS)"

2. Read Current Version

For Claude plugins:

  1. Read .claude-plugin/plugin.json
  2. Extract version field value
  3. Parse SemVer components (MAJOR.MINOR.PATCH)

Display: "Project: Claude Plugin ([plugin name])" Display: "Current version: X.Y.Z"

For Xcode projects:

  1. Find .xcodeproj directory in project root
  2. Read <project>.xcodeproj/project.pbxproj
  3. Extract first MARKETING_VERSION = X.Y.Z; value
  4. Parse SemVer components (MAJOR.MINOR.PATCH)

Display: "Project: [ProjectName].xcodeproj" Display: "Current version: X.Y.Z"

3. Prompt for Increment Type

If no argument provided, ask the user:

"Select version increment (SemVer):"

OptionResultDescription
1. patchX.Y.(Z+1)Bug fixes, backwards compatible
2. minorX.(Y+1).0New features, backwards compatible
3. major(X+1).0.0Breaking changes
4. tag(no change)Create or update tag only

4. Generate Release Documentation (Optional)

Before committing the release, ask the user:

"Would you like to generate release documentation first?"

  1. Yes - Run /release:changelog now (recommended)
  2. No - Skip documentation

If yes, execute /release:changelog which will:

  • Generate changelog.md (developer notes)
  • Generate changelog-public.md (user-facing release notes)
  • Optionally prompt for /release:decisions and /release:whattotest

This ensures documentation is included in the release commit.

5. Check Git Execution Mode

Check config for release-plugin.release.gitMode setting.

If not set, ask the user:

"How should git commands be handled?"

  1. Run automatically - Claude executes git commands (showing progress)
  2. Show commands only - Display commands for you to run manually

If user selects option 1 (auto):

  • Confirm Claude has permission to execute git commands
  • Request bash permissions for git operations if needed
  • Test with a safe command like git status to verify access

Then ask: "Save this preference for future runs?"

  • If yes, persist to .claude/config.json under release-plugin.release.gitMode
    • Option 1 → "auto"
    • Option 2 → "manual"

6. Execute Version Increment

For patch/minor/major:

  1. Calculate new version per SemVer:

    • patch: MAJOR.MINOR.(PATCH+1)
    • minor: MAJOR.(MINOR+1).0
    • major: (MAJOR+1).0.0
  2. Show: "New version: X.Y.Z → A.B.C"

  3. Confirm: "Proceed with version increment?"

  4. Update version file(s):

    • Claude Plugin: Update version field in both:
      • .claude-plugin/plugin.json
      • .claude-plugin/marketplace.json (in the plugins[0].version field)
    • Xcode: Replace ALL MARKETING_VERSION = X.Y.Z; with MARKETING_VERSION = A.B.C; in project.pbxproj
  5. Verify update succeeded by reading back the version

  6. If gitMode is "auto" - Execute git commands (showing each command as it runs):

    Running: git add <version-file(s)>  # plugin.json + marketplace.json for Claude, or project.pbxproj for Xcode
    Running: git add <changelog-files>  # if documentation was generated
    Running: git commit -m "Release vA.B.C"
    Running: git tag rel.vA.B.C
    

    Then display:

    Done! Version incremented to A.B.C
    Committed and tagged as 'rel.vA.B.C'
    
    To push to remote:
      git push && git push origin rel.vA.B.C
    
  7. If gitMode is "manual" - Display commands for user to run:

    Version file updated to A.B.C
    
    Run these commands to complete the release:
      git add <version-file> <changelog-files>
      git commit -m "Release vA.B.C"
      git tag rel.vA.B.C
      git push && git push origin rel.vA.B.C
    

For tag (create or update tag):

  1. Determine tag name: rel.vX.Y.Z (current version)

  2. Check if tag exists: git tag -l rel.vX.Y.Z

  3. If gitMode is "auto":

    • If tag exists:
      • Show: "Tag 'rel.vX.Y.Z' exists. Update to current commit?"
      • If confirmed, run: git tag -f rel.vX.Y.Z
    • If tag doesn't exist:
      • Show: "Create tag 'rel.vX.Y.Z'?"
      • If confirmed, run: git tag rel.vX.Y.Z
    • Display success and push command
  4. If gitMode is "manual":

    • If tag exists:
      • Display: git tag -f rel.vX.Y.Z and git push origin -f rel.vX.Y.Z
    • If tag doesn't exist:
      • Display: git tag rel.vX.Y.Z and git push origin rel.vX.Y.Z

Arguments

$ARGUMENTS

Direct increment type:

  • /release:release patch - Increment patch version (bug fixes)
  • /release:release minor - Increment minor version (new features)
  • /release:release major - Increment major version (breaking changes)
  • /release:release tag - Create or update tag (no version change)

If no argument, show interactive menu.

Configuration

Check for .claude/config.json at project root. Look for settings under release-plugin.release:

{
  "release-plugin": {
    "release": {
      "gitMode": "auto"
    }
  }
}
OptionValuesDescription
gitMode"auto"Claude executes git commands automatically
"manual"Claude displays commands for user to run

The tag Option and CI/CD Triggers

The tag option is useful for triggering CI builds without incrementing the version:

Xcode Cloud workflow:

  • Configure Xcode Cloud to build on tags matching rel.v*
  • Use tag to iterate on a release candidate
  • Force-push updated tag to trigger new build

Example:

# Initial release
/release:release patch          # Creates rel.v1.2.4, commits, tags

# Quick fix needed in same version
git commit -m "Fix critical bug"
/release:release tag            # Updates rel.v1.2.4 to current commit
git push origin -f rel.v1.2.4   # Triggers new CI build

Project-Specific Notes

Claude Plugin

  • Updates version in both plugin.json and marketplace.json
  • Both files must have matching versions for marketplace distribution
  • Detection is scoped to .claude-plugin/ in project root only

Xcode (iOS/macOS)

  • Only modifies MARKETING_VERSION in project.pbxproj
  • BUILD_NUMBER is typically auto-incremented by Xcode Cloud
  • Supports projects with multiple targets (updates all occurrences)

Future Project Types

This command is designed to support additional project types:

  • Next.js: Update version in package.json
  • Android: Update versionName in build.gradle
  • Flutter: Update version in pubspec.yaml
  • React Native: Update both package.json and native projects

Contributions welcome for additional project type support.

TestFlight WhatToTest Generator

Generate a WhatToTest document for TestFlight beta releases.

Model: Uses the model configured in release-plugin.model (see /release:changelog for model selection).

Instructions

  1. Locate source content (in priority order):

    • If called from /release:changelog: Use the changelog-public.md that was just generated in this session. Do not re-analyze - derive directly from that file.
    • If called directly: Look for source content in this order:
      1. changelog-public.md in the project
      2. Recent changelog files in the project
      3. Git commit history for recent changes
      4. Release notes or version documentation
  2. Check for existing WhatToTest files:

    Search for existing WhatToTest files in ./TestFlight/, checking in this order:

    1. WhatToTest.en-US.txt (default)
    2. Other locale variants (e.g., .de.txt, .fr.txt)

    If existing file(s) found, use the same location and filename.

    Check config for release-plugin.whattotest.onExisting:

    • If "prepend": Prepend new entry without asking
    • If "replace": Replace content without asking
    • If "ask" (default): Prompt the user: "WhatToTest file already exists. How should I handle it?"
      1. Prepend new entry (keep history, newest at top) - Recommended
      2. Replace all (start fresh with only this release)

    If no existing file found, create ./TestFlight/WhatToTest.en-US.txt. Create the TestFlight/ folder if it doesn't exist.

  3. Generate WhatToTest content that is:

    • Under 4000 characters total (hard limit — TestFlight rejects content exceeding this). Count characters before writing the file. If over, condense until it fits.
    • No special characters — use only plain ASCII. Avoid smart quotes, em dashes, bullets (•), or other unicode characters. Use hyphens (-) for lists and straight quotes.
    • Concise and actionable for testers
    • Focused on what testers should specifically test
    • Written in plain language (non-technical)
    • Organized by feature area or priority

Output Format

Structure for each release entry:

[App Name] v[Version] - YYYY-MM-DD

[Brief overview of this beta release - 1-2 sentences]

Key Areas to Test:

1. [Feature/Area Name]
   - [Specific test case or scenario]
   - [Another test case]

2. [Feature/Area Name]
   - [Specific test case or scenario]
   - [Another test case]

Known Issues:
- [Any known issues testers should be aware of]

Feedback Focus:
- [Specific questions or areas where you want tester feedback]

---

When prepending, each release gets its own section separated by ---.

Notes

  • The WhatToTest file is automatically included with your TestFlight build when placed in a TestFlight folder at your project root
  • Keep content under 4000 characters (TestFlight limit)
  • Focus on NEW or CHANGED functionality that needs testing
  • Localized filenames: WhatToTest.en-US.txt (US English), WhatToTest.de.txt (German), etc.

Arguments

If a version number is provided, generate WhatToTest content for that specific version: $ARGUMENTS

Xcode Build

Build an iOS app for the iOS Simulator using xcodebuild, with automatic project detection and simulator selection.

Arguments

$ARGUMENTS

  • No arguments: Use cached settings or prompt for selection on first run
  • --change: Clear cached settings and prompt for new scheme and simulator selection
  • --scheme=<name>: Use a specific scheme (updates cache)
  • --id=<UUID>: Use a specific simulator UUID (one-time, doesn't update cache)

Configuration

Plugin settings are stored in dedicated config files (Claude Code's settings.json has a strict schema):

ScopeFileUse Case
project.claude/config.jsonTeam defaults, version controlled
local.claude/config.local.jsonPersonal settings, gitignored

Project Settings (.claude/config.json)

Team defaults, committed to version control:

{
  "release-plugin": {
    "xcbuild": {
      "scheme": "MyApp",
      "showWarnings": true
    }
  }
}

Local Settings (.claude/config.local.json)

Personal settings, gitignored (simulator UUIDs are machine-specific):

{
  "release-plugin": {
    "xcbuild": {
      "simulatorId": "A2444326-C93A-4271-9EF0-C44AA5D4FC42",
      "scheme": "MyApp-Dev"
    }
  }
}

Settings Reference

SettingRecommended ScopeDescription
schemeprojectDefault scheme (team default)
simulatorIdlocalDefault simulator UUID (machine-specific)
showWarningsprojectShow build warnings in output (default: true)

Precedence (highest to lowest)

  1. Command-line arguments (--scheme=, --id=)
  2. Local config (.claude/config.local.json)
  3. Project config (.claude/config.json)
  4. Session cache
  5. Prompt user

Instructions

Step 1: Check for arguments and cached settings

Parse $ARGUMENTS:

  • If --id=<UUID> is provided, use that UUID for this build only (skip to Step 5)
  • If --scheme=<name> is provided, use that scheme and update cache (proceed to Step 3)
  • If --change is provided, clear all cached settings and proceed to Step 1b
  • If no arguments, check settings in precedence order:
    1. .claude/config.local.json → release-plugin.xcbuild.scheme and simulatorId
    2. .claude/config.json → release-plugin.xcbuild.scheme and simulatorId
    3. Session cache from earlier in this conversation
    4. If scheme is missing, proceed to Step 1b (detect project, then select scheme)
    5. If simulator is missing, proceed to Step 3 (query and select simulator)
    6. If both are found, skip to Step 5 (run build - trust saved simulator ID)

Step 1b: Detect Xcode project (if needed)

Find the project or workspace in the current directory:

ls -d *.xcworkspace 2>/dev/null || ls -d *.xcodeproj 2>/dev/null
  • Prefer .xcworkspace over .xcodeproj (workspaces handle CocoaPods/SPM dependencies)
  • If multiple found, use the first one
  • Cache the project/workspace name for subsequent builds

Step 2: Select scheme (if needed)

Get available schemes:

xcodebuild -list -json

Parse the JSON project.schemes array. Identify a recommended scheme:

  • Prefer scheme matching the project/workspace name exactly
  • Exclude schemes containing "Tests", "UITests", "Keyboard", "Widget", "Extension"
  • If only one non-test/extension scheme exists, use it directly without prompting

If multiple schemes are available, use AskUserQuestion:

Header: "Scheme"

Question: "Which scheme should be used for builds?"

Options (show up to 4, add "(Recommended)" suffix to first):

  1. Main app scheme - description: "Main app target"
  2. Other schemes with descriptive labels based on name (e.g., "ASC" → "App Store Connect", "Keyboard" → "Keyboard extension only")

Example for a project with schemes ["MyApp", "MyApp ASC Sub", "MyAppKeyboard"]:

  • Option 1: "MyApp (Recommended)" - "Main app target"
  • Option 2: "MyApp ASC Sub" - "App Store Connect submission"
  • Option 3: "MyAppKeyboard" - "Keyboard extension only"

After user selects:

  1. Cache the scheme name for subsequent builds in this session
  2. Ask: "Save this scheme as the project default?" (saves to .claude/config.json)

Step 3: Query available simulators (only when needed)

Only run this step when:

  • No simulator ID is configured (first run)
  • --change flag was used
  • Build failed due to invalid simulator

First, output a message to the user: "Querying available simulators..."

Then run this command to get available simulators:

xcrun simctl list devices available --json

Parse the JSON to build a list of available iPhone simulators:

  • Group by iOS version (runtime)
  • Include device name and UUID
  • Sort by iOS version (newest first), then by device name

Identify the recommended simulator: The newest iPhone Pro model on the highest iOS version.

Step 4: Select simulator (first run or after build failure)

Only run this step when:

  • No simulator ID is configured (first run)
  • --change flag was used
  • Build failed due to invalid simulator (see Step 5)

Use AskUserQuestion to present options:

Header: "Simulator"

Question: "Which iOS Simulator should be used for builds?"

Options (show up to 4):

  1. Recommended - e.g., "iPhone 17 Pro Max (iOS 26.2)" with description "Recommended - Latest Pro model"
  2. Next best option - e.g., "iPhone 17 Pro (iOS 26.2)"
  3. Another popular option - e.g., "iPhone 16 Pro (iOS 18.2)"
  4. If user needs something else, they can select "Other" and provide a UUID

After user selects:

  1. Cache the simulator name and UUID for subsequent builds in this session
  2. Ask: "Save this simulator for this project?" (saves to .claude/config.local.json)

Step 5: Run the build

For a workspace:

xcodebuild -workspace <Name>.xcworkspace -scheme <Scheme> -destination "id=<UUID>" build 2>&1 | grep -E "(warning:|error:|BUILD SUCCEEDED|BUILD FAILED)" | grep -v "export " | tail -20

For a project (no workspace):

xcodebuild -project <Name>.xcodeproj -scheme <Scheme> -destination "id=<UUID>" build 2>&1 | grep -E "(warning:|error:|BUILD SUCCEEDED|BUILD FAILED)" | grep -v "export " | tail -20

Note: If release-plugin.xcbuild.showWarnings is false in config, exclude warning: from the grep pattern.

If build fails due to invalid simulator (error contains "unable to find a destination matching" or similar):

  1. Inform the user: "Configured simulator not found. It may have been deleted or this config is from a different machine."
  2. Go to Step 3 (query available simulators)
  3. Then Step 4 (prompt user to select a new simulator)
  4. Retry the build with the new simulator

Step 6: Report results

Format output as:

Project: <Project/Workspace Name>
Scheme: <Scheme Name>
Simulator: <Device Name> (<iOS Version>)
ID: <UUID>

[Any SwiftLint warnings or build errors]

BUILD SUCCEEDED [X.X sec]

Or on failure:

Project: <Project/Workspace Name>
Scheme: <Scheme Name>
Simulator: <Device Name> (<iOS Version>)
ID: <UUID>

[Build errors]

BUILD FAILED - [summary of errors]

Persisting User Choices

After selecting scheme or simulator, offer to save:

For scheme (team default): "Save this scheme as the project default?"

  • If yes, save to .claude/config.json under release-plugin.xcbuild.scheme
  • This is version controlled and shared with the team

For simulator (personal/machine-specific): "Save this simulator for this project?"

  • If yes, save to .claude/config.local.json under release-plugin.xcbuild.simulatorId
  • This is gitignored (machine-specific UUIDs)

Saving to a config file

  1. Create .claude/ directory if needed
  2. Read existing file content (if any) to preserve other settings
  3. Parse as JSON, or start with empty object {}
  4. Ensure release-plugin.xcbuild path exists
  5. Add/update the specific setting
  6. Write the updated JSON back to the file
  7. Create parent directories if needed (e.g., mkdir -p ~/.claude)

Examples

First run (no cached settings):

/release:xcbuild

→ Detects project, asks user to select scheme and simulator, caches choices, runs build

Subsequent runs:

/release:xcbuild

→ Uses cached project/scheme/simulator, runs build immediately

Change scheme and simulator:

/release:xcbuild --change

→ Clears cache, asks user to select new scheme and simulator, updates cache, runs build

Use specific scheme:

/release:xcbuild --scheme=FontPopKeyboard

→ Uses specified scheme, updates cache, uses cached simulator

Use specific simulator UUID:

/release:xcbuild --id=A2444326-C93A-4271-9EF0-C44AA5D4FC42

→ Uses provided UUID for this build only (doesn't update cache)

Sponsors

Details

Marketplace
scarrillo/release
Author
Shawn Carrillo
Category
Productivity
License
MIT
Keywords
release, release-automation, semver, semantic-versioning, versioning, changelog, release-notes, git, git-tag, ci-cd, cicd, testflight, whattotest, ios, macos, xcode, adr, decisions, documentation, automation