/xcode-workflows

name: xcode-workflows
description: Xcode build system guidance for xcodebuild operations. Use when building iOS projects, running tests, analyzing build failures, or configuring schemes. Covers build/clean/test operations, interpreting xcodebuild output, and troubleshooting common build errors.

Xcode Workflows

**Use the `execute_xcode_command` MCP tool for all iOS build operations**

The xclaude-plugin provides the `execute_xcode_command` MCP tool which consolidates all xcodebuild operations into a single, token-efficient dispatcher.

⚠️ CRITICAL: Always Use MCP Tools First

**This is the most important rule:** When working with iOS builds, you MUST use the `execute_xcode_command` MCP tool.

• ✅ **DO**: Invoke `execute_xcode_command` for all build/test/clean operations
• ✅ **DO**: If the MCP tool fails, adjust parameters and retry
• ✅ **DO**: Read error messages and debug the parameters
• ❌ **NEVER**: Fall back to bash `xcodebuild` commands
• ❌ **NEVER**: Use `xcodebuild` directly in bash
• ❌ **NEVER**: Run `xcrun xcodebuild` in a terminal

**Why?** The MCP tool provides:

• Structured error handling
• Token efficiency (consolidated into 1 tool vs. verbose bash output)
• Proper integration with the xclaude-plugin architecture
• Consistent response formatting

If `execute_xcode_command` fails, the issue is with parameters or the project - not that you should use bash.

When to Use Bash (And When NOT to)

❌ NEVER Use Bash For These (Use MCP Tools Instead)

| Task | ❌ WRONG (Bash) | ✅ RIGHT (MCP Tool) | | -------------- | ---------------------------- | ------------------------------------- | | List schemes | `xcodebuild -list` | `execute_xcode_command` op: "list" | | Build app | `xcodebuild -scheme...` | `execute_xcode_command` op: "build" | | Run tests | `xcodebuild -scheme... test` | `execute_xcode_command` op: "test" | | Clean build | `xcodebuild clean` | `execute_xcode_command` op: "clean" | | Get Xcode info | `xcodebuild -version` | `execute_xcode_command` op: "version" |

✅ Bash is Acceptable For (Non-Build Tasks)

• File operations: `mkdir`, `cp`, `rm`, `ls`, etc.
• Text inspection: `grep`, `find`, `cat`, etc.
• Git operations: `git status`, `git log`, etc.
• Environment checks: `which`, `xcode-select --version`, etc.
• Project exploration: `find . -name "*.swift"`, etc.

The Rule: If it's about Xcode building/testing → Use MCP tool, not bash

Quick Reference

| Task | MCP Tool | Operation | Key Parameters | | ------------------- | ----------------------- | --------- | ------------------------------------------ | | Build for simulator | `execute_xcode_command` | `build` | scheme, configuration:Debug | | Build for device | `execute_xcode_command` | `build` | scheme, configuration:Release, destination | | Run tests | `execute_xcode_command` | `test` | scheme, destination | | Clean build | `execute_xcode_command` | `clean` | scheme | | List schemes | `execute_xcode_command` | `list` | - | | Get Xcode info | `execute_xcode_command` | `version` | - |

Standard Workflows

1. Building an App

**Step 1: Discover Schemes - Use `execute_xcode_command` with operation: "list"**

Invoke the `execute_xcode_command` MCP tool:

{
  "operation": "list",
  "project_path": "/path/to/Project.xcodeproj"
}

**Note:** `project_path` is optional - auto-detected from current directory.

**Returns:**

{
  "schemes": ["MyApp", "MyAppTests", "MyAppUITests"],
  "targets": ["MyApp", "MyAppKit", "MyAppTests"]
}

**Step 2: Build - Use `execute_xcode_command` with operation: "build"**

Invoke the `execute_xcode_command` MCP tool with build parameters:

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "destination": "platform=iOS Simulator,name=iPhone 15"
}

**Common Destinations:**

• iOS Simulator (explicit - recommended): `"platform=iOS Simulator,name=iPhone 15,OS=18.0"`
• iOS Simulator (auto-resolve): `"platform=iOS Simulator,name=iPhone 15"` (will auto-detect latest OS)
• iOS Device: `"platform=iOS,id=<device-udid>"`
• Any Simulator: `"platform=iOS Simulator,name=Any iOS Simulator Device"`
• macOS: `"platform=macOS"`

**Note:** The destination parameter now supports auto-resolution! If you omit the OS version, the tool will automatically query available simulators and select the latest OS version for the specified device name. For explicit control, include the OS version in your destination string.

2. Running Tests

**Unit Tests:**

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15"
}

**Specific Test Plan:**

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "test_plan": "UnitTests"
  }
}

**Run Specific Tests:**

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "only_testing": [
      "MyAppTests/LoginTests/testSuccessfulLogin",
      "MyAppTests/LoginTests/testInvalidCredentials"
    ]
  }
}

**Skip Specific Tests:**

{
  "operation": "test",
  "scheme": "MyApp",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "options": {
    "skip_testing": ["MyAppUITests"]
  }
}

3. Clean Build

**When to Clean:**

• Build artifacts corrupted
• Switching branches significantly
• Mysterious build failures
• Before release builds

{
  "operation": "clean",
  "scheme": "MyApp"
}

**Clean + Build Pattern:**

{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "options