---
name: xcodebuild
description: Build, test, and archive iOS/macOS apps with xcodebuild and Xcode
  CLI tools. Use for CI integration, scheme management, simulator control, and
  build troubleshooting.
metadata:
  category: user-invoked
disable-model-invocation: true
---

## Pi Context-Aware Execution

When this skill is invoked in Pi, treat the user's current request and any skill arguments as the task input. Do not treat this file as the task by itself.

Before applying the skill, establish only the context needed for the request:

1. Identify the current working directory and relevant project scope.
2. Read local guidance first when present: AGENTS.md, CLAUDE.md, TODO.md, or nearby task/spec files.
3. Inspect the current codebase with targeted searches (prefer rg) and read relevant files before making claims or proposing changes.
4. Ground findings and recommendations in project evidence: cite file paths, commands, tests, docs, or external sources as applicable.
5. Ask a concise clarification only when the arguments and codebase context are insufficient to proceed safely.

Operate conservatively: avoid broad scans, large reads, subagents, or parallel fanout unless the user's requested depth clearly requires them.
Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.

# Xcode Build Engineering

## Current Versions (Verify Before Use)

```bash
xcodebuild -version                 # Xcode version
xcrun simctl list devices           # Available simulators
xcrun --show-sdk-path               # SDK path
swift --version                     # Swift version
```

Check [Xcode release notes](https://developer.apple.com/documentation/xcode-release-notes) for the latest version.

## Core Principles

1. **Command-line first.** If you can't build from `xcodebuild`, your CI will break.
2. **Schemes are shared.** Every scheme used in CI must be marked "Shared" in Xcode.
3. **DerivedData is disposable.** Clean builds should succeed. Cache selectively.
4. **Simulators are ephemeral.** Don't depend on simulator state between runs.

## Build Commands

```bash
# Basic build
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' build

# Run tests
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' test

# Archive for distribution
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release archive -archivePath build/MyApp.xcarchive

# Export IPA
xcodebuild -exportArchive -archivePath build/MyApp.xcarchive -exportPath build -exportOptionsPlist ExportOptions.plist
```

## CI Integration

```yaml
# .github/workflows/ios.yml
- uses: maxim-lobanov/setup-xcode@v1
  with:
    xcode-version: latest-stable
- run: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' test
```

## Common Anti-Patterns

| Anti-Pattern | Why It's Wrong | Fix |
|---|---|---|
| Non-shared scheme in CI | CI can't find the scheme | Check "Shared" in Manage Schemes |
| Hardcoded simulator name | Breaks when new Xcode drops old simulators | Use `xcrun simctl list` dynamically |
| Signing in CI without match | Manual provisioning is fragile | Use fastlane match or Xcode Cloud |
| Committing DerivedData | Bloated repo, conflicts | Add to `.gitignore` |
| No `-derivedDataPath` | Pollutes default location, cache issues | Explicit path in CI |

## Validation Checklist

- [ ] Build succeeds with clean DerivedData
- [ ] Tests pass on CI simulator
- [ ] All schemes used in CI are shared
- [ ] `-derivedDataPath` set explicitly in CI
- [ ] Code signing works in CI (manual or automatic)
- [ ] Archive + export tested before release

## Official Resources

- [xcodebuild man page](https://keith.github.io/xcode-man-pages/xcodebuild.html)
- [Xcode CLI docs](https://developer.apple.com/library/archive/technotes/tn2339/_index.html)
- [fastlane](https://docs.fastlane.tools/) for signing and distribution automation