xcode-workflows

What this skill does

# 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:

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

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

**Returns:**

```json
{
  "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:

```json
{
  "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:**

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

**Specific Test Plan:**

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

**Run Specific Tests:**

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

**Skip Specific Tests:**

```json
{
  "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

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

**Clean + Build Pattern:**

```json
{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Debug",
  "options": {
    "clean_before_build": true
  }
}
```

## Configurations

### Debug vs Release

**Debug (Default):**

- Optimizations disabled
- Debug symbols included
- Faster compile time
- Larger binary
- Use for: Development, testing

**Release:**

- Optimizations enabled
- Debug symbols optional
- Slower compile time
- Smaller binary
- Use for: Production, App Store, performance testing

```json
{
  "operation": "build",
  "scheme": "MyApp",
  "configuration": "Release"
}
```

## Build Options

### Common Options

```json
{
  "operation": "build",
  "scheme": "MyApp",
  "options": {
    "clean_before_build": true,
    "parallel": true,
    "sdk": "iphoneos17.0",
    "arch": "arm64",
    "quiet": false
  }
}
```

**Options Explained:**

- **clean_before_build**: Clean before building (ensures fresh build)
- **parallel**: Enable parallel builds (faster on multi-core)
- **sdk**: Specific SDK version (usually auto-selected)
- **arch**: Target architecture (arm64 for devices, x86_64 for old simulators)
- **quiet**: Reduce build output verbosity

## Interpreting Build Results

### Success Response

```json
{
  "success": true,
  "summary": "Build succeeded",
  "warnings": 3,
  "build_time": "45.2s",
  "scheme": "MyApp",
  "configuration": "Debug"
}
```

### Failure Response

```json
{
  "success": false,
  "error": "Build failed",
  "errors": 2,
  "warnings": 5,
  "failure_reason": "Compilation errors in ViewController.swift"
}
```

### Progressive Disclosure

Large build logs use progressive disclosure:

```json
{
  "success": true,
  "summary": "Build succeeded with 15 warnings",
  "cache_id": "build-abc123",
  "quick_stats": {
    "warnings": 15,
    "build_time": "62.3s"
  },
  "next_steps": [
    "Use cache_id to get full build log if needed",
    "Review warnings for potential issues"
  ]
}
```

## Common Build Errors

### Error: "No scheme named 'X' found"

**Cause:** Scheme doesn't exist or isn't shared

**Solution:**

1. Run `list` operation to see available schemes
2. Check if scheme is shared (Xcode → Product → Scheme → Manage Schemes)

### Error: "Code signing identity not found"

**Cause:** Missing or invalid signing certificate

**Solution:**

1. Check Team ID in project settings
2. Verify certificates in Keychain
3. Use automatic signing if possible

```json