---
description: "Thin wrapper that dispatches to xcode-build-orchestrator on iOS projects. Benchmarks current Xcode build, runs compilation / project / SPM analyzers, produces a recommend-first optimization plan, and re-benchmarks after the developer approves changes. Use when an iOS build is slow and needs measuring before anything is changed."
description-tr: "iOS projelerinde xcode-build-orchestrator'a delege eden ince sarmalayıcı. Mevcut Xcode build'ini ölçer, derleme / proje / SPM analizlerini koşar, önce-öneri yaklaşımlı bir optimizasyon planı üretir ve geliştirici onayından sonra yeniden ölçer."
argument-hint: "(none - operates on current repo)"
---

# multi-agent build-optimize - Xcode Build Performance Wrapper

Wraps the vendored `xcode-build-orchestrator` skill (and its 5 specialist analyzers) so iOS users do not have to remember the orchestrator skill name. Recommend-first: no project files are modified without explicit developer approval. All output lands in `.build-benchmark/` in the current repo.

> **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix - instruction prose stays English (this file is read as a system prompt). `AskUserQuestion.label` and `header` stay English. `question` and `description` follow `outputLanguage`. The emitted benchmark plan body (the upstream skill controls it) is English by upstream convention.

## When to use

- Slow clean or incremental Xcode builds (long CompileSwiftSources, SwiftEmitModule, Planning Swift module)
- Build settings audit before a release branch cut
- SPM resolution time complaints, plugin overhead suspicions
- Pre-CI optimization pass when build wall-clock starts dominating PR cycle time

## Pre-check

Before dispatch, fail fast on non-iOS repos. Detect iOS context via the standard markers used by Phase 1 stack detection:

| Marker | Action |
|--------|--------|
| `*.xcodeproj` or `*.xcworkspace` in cwd | Proceed to dispatch |
| `Package.swift` only (SwiftPM lib, no Xcode project) | Proceed; orchestrator handles `xcodebuild -package-path` |
| Android / Backend / Frontend markers only | Surface a short error: "build-optimize is iOS-only. Detected: <stack>. Use the platform-appropriate perf skill (android-performance / web-performance / etc.) instead." Exit. |
| No recognizable stack | Surface "no iOS project found in cwd" and exit. |

## Steps

1. **Detect stack** (as above). On non-iOS, exit with the explanatory message.

2. **Identify project + scheme** for the orchestrator:
   - If both `.xcworkspace` and `.xcodeproj` exist, prefer `.xcodeproj` unless the workspace contains sub-projects required for the build (upstream orchestrator's own rule).
   - If multiple schemes, AskUserQuestion to pick one (single-select, options derived from `xcodebuild -list -json`).
   - Configuration default: `Debug` (developers spend most wait time here). Ask to override only if user input suggests Release-focused work.
   - Destination default: a generic simulator (`platform=iOS Simulator,name=iPhone 16`) unless the project pins a different one.

3. **Dispatch** to `xcode-build-orchestrator` via the Skill tool:
   ```
   Skill(skill="ai-ios-toolkit:xcode-build-orchestrator", args="")
   ```
   The orchestrator's Phase 1 (Analyze) runs `xcode-build-benchmark`, the three specialist analyzers, and writes `.build-benchmark/optimization-plan.md`. No project files are modified during Phase 1.

4. **Hand off** the rendered plan path to the user. The user reviews `.build-benchmark/optimization-plan.md`, checks the approval boxes for items they want, and triggers Phase 2 manually (or re-invokes this wrapper with the plan already produced).

5. **Phase 2 (apply + verify)** is initiated by the user. The wrapper does not auto-execute Phase 2 because the upstream contract requires explicit approval via the checkboxes in the plan file. When the user signals "implement the approved items", the wrapper dispatches to `xcode-build-fixer`:
   ```
   Skill(skill="ai-ios-toolkit:xcode-build-fixer", args="")
   ```
   The fixer applies only the approved changes and re-benchmarks for wall-clock delta verification.

## Side-effect contract

- Phase 1 (Analyze): writes only inside `.build-benchmark/` in the cwd. No project file edits.
- Phase 2 (Fix): edits build settings, source files, packages, or scripts the developer approved. Re-benchmarks to verify.
- Never opens a worktree. Never creates a branch. Never commits. Never opens a PR. Build optimization wins land in the user's normal commit workflow.

## Reusable refs

| Path | Reason |
|------|--------|
| `ai-ios-toolkit:xcode-build-orchestrator` | The orchestrator this wrapper dispatches to |
| `ai-ios-toolkit:xcode-build-benchmark` | Baseline timing |
| `ai-ios-toolkit:xcode-compilation-analyzer` | Swift compile hotspots |
| `ai-ios-toolkit:xcode-project-analyzer` | Build settings / script phases / parallelism |
| `ai-ios-toolkit:spm-build-analysis` | SPM graph + plugins |
| `ai-ios-toolkit:xcode-build-fixer` | Apply approved fixes + re-benchmark |
| ai-ios-toolkit plugin NOTICE (xcode build skills) | MIT attribution + upstream pin |

## Notes

- The upstream `OPTIMIZATION-CHECKS.md` (in the AvdLee repo) has the full 40+ check catalog. Surface a link from the optimization plan if the user wants to see what was checked vs skipped.
- Wall-clock build time (not parallel CPU time) is the primary success metric. The orchestrator labels findings as "build time improvements" or "parallel efficiency improvements" accordingly.
- If `COMPILATION_CACHE_ENABLE_CACHING = YES`, the benchmark auto-includes cached-clean runs (realistic warm-cache developer experience).
- Variance flag: when a benchmark's min-max spread exceeds 20% of the median, the orchestrator marks the run high-variance and recommends 5+ repetitions before drawing conclusions.