Xcode Build Orchestrator
Run reproducible Xcode clean and incremental build benchmarks with canonical `.build-benchmark/` artifacts so you can prove whether optimization changes actually shorten wall-clock wait time.
Overview
Xcode Build Orchestrator is an agent skill most often used in Ship (also Build frontend, Operate infra) that defines reproducible `.build-benchmark/` Xcode build measurements with wall-clock as the success metric.
Install
npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill xcode-build-orchestratorWhat is this skill?
- Treats `.build-benchmark/` as the canonical store for JSON summaries and per-run `.log` files
- Separates wall-clock `duration_seconds` (primary metric) from cumulative Build Timing Summary categories
- Documents multi-run clean benchmark log naming (e.g. clean-1/2/3) plus optional compilation-cache runs
- Warns that parallel SwiftCompile totals can exceed wall-clock and mislead bottleneck calls without comparison
- Recommended triple clean-run log pattern (clean-1, clean-2, clean-3) per scheme timestamp
- Primary success metric is wall-clock duration_seconds / median_seconds, not cumulative timing categories alone
Adoption & trust: 2.5k installs on skills.sh; 1.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You cannot tell if an Xcode optimization helped because build timings are one-off, incomparable, or misread from cumulative task summaries.
Who is it for?
Solo iOS/macOS developers iterating on compile times who need disciplined benchmark artifacts before changing build settings or modules.
Skip if: Pure Swift feature work with no build-time pain, or web/Android projects outside the Xcode toolchain.
When should I use this skill?
You need canonical, comparable Xcode build benchmark outputs under `.build-benchmark/` for specialist analysis in this optimization skill repo.
What do I get? / Deliverables
You get a consistent benchmark folder with JSON medians and labeled logs so specialists can compare clean versus cached builds using wall-clock evidence.
- Timestamped `<scheme>.json` benchmark summary with median wall-clock
- Per-run clean, cached-clean, and incremental `.log` files under `.build-benchmark/`
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build-time performance is a ship-time quality gate for iOS teams; orchestration also supports Operate when regressions appear in CI. The skill centers on measured build duration and timing evidence—canonical shelf is ship → perf, not feature implementation.
Where it fits
Capture three clean builds and median wall-clock before enabling compilation cache for your main scheme.
After splitting a large Swift module, rerun orchestrated benchmarks to see if incremental builds improved.
Archive `.build-benchmark/` JSON from CI-like machines to compare median_seconds when pipeline duration spikes.
How it compares
Measurement orchestration and artifact layout—not a one-click “fix my Xcode project” generator.
Common Questions / FAQ
Who is xcode-build-orchestrator for?
Indie and small-team Apple-platform developers using coding agents to benchmark Xcode schemes systematically rather than eyeballing a single build.
When should I use xcode-build-orchestrator?
Use it in Ship → perf before merging build-setting changes; in Build → frontend when module structure affects compile graphs; and in Operate → infra when CI build durations regress.
Is xcode-build-orchestrator safe to install?
It drives local Xcode builds and writes logs under your repo; review the Security Audits panel on this page and avoid running benchmarks on untrusted schemes or shared secrets in log paths.
SKILL.md
READMESKILL.md - Xcode Build Orchestrator
# Benchmark Artifacts All skills in this repository should treat `.build-benchmark/` as the canonical location for measured build evidence. ## Goals - Keep build measurements reproducible. - Make clean and incremental build data easy to compare. - Preserve enough context for later specialist analysis without rerunning the benchmark. ## Wall-Clock vs Cumulative Task Time The `duration_seconds` field on each run and the `median_seconds` in the summary represent **wall-clock time** -- how long the developer actually waits. This is the primary success metric. The `timing_summary_categories` are **aggregated task times** parsed from Xcode's Build Timing Summary. Because Xcode runs many tasks in parallel across CPU cores, these totals typically exceed the wall-clock duration. A large cumulative `SwiftCompile` value is diagnostic evidence of compiler workload, not proof that compilation is blocking the build. Always compare category totals against the wall-clock median before concluding that a category is a bottleneck. ## File Layout Recommended outputs: - `.build-benchmark/<timestamp>-<scheme>.json` - `.build-benchmark/<timestamp>-<scheme>-clean-1.log` - `.build-benchmark/<timestamp>-<scheme>-clean-2.log` - `.build-benchmark/<timestamp>-<scheme>-clean-3.log` - `.build-benchmark/<timestamp>-<scheme>-cached-clean-1.log` (when COMPILATION_CACHE_ENABLE_CACHING is enabled) - `.build-benchmark/<timestamp>-<scheme>-cached-clean-2.log` - `.build-benchmark/<timestamp>-<scheme>-cached-clean-3.log` - `.build-benchmark/<timestamp>-<scheme>-incremental-1.log` - `.build-benchmark/<timestamp>-<scheme>-incremental-2.log` - `.build-benchmark/<timestamp>-<scheme>-incremental-3.log` Use an ISO-like UTC timestamp without spaces so the files sort naturally. ## Artifact Requirements Each JSON artifact should include: - schema version - creation timestamp - project context - environment details when available - the normalized build command - separate `clean` and `incremental` run arrays - summary statistics for each build type - parsed timing-summary categories - free-form notes for caveats or noise ## Clean, Cached Clean, And Incremental Separation Do not merge different build type measurements into a single list. They answer different questions: - **Clean builds** show full build-system, package, and module setup cost with a cold compilation cache. - **Cached clean builds** show clean build cost when the compilation cache is warm. This is the realistic scenario for branch switching, pulling changes, or Clean Build Folder. Only present when `COMPILATION_CACHE_ENABLE_CACHING = YES` is detected. - **Incremental builds** show edit-loop productivity and script or cache invalidation problems. ## Raw Logs Store raw `xcodebuild` output beside the JSON artifact whenever possible. That allows later skills to: - re-parse timing summaries - inspect failed builds - search for long type-check warnings - correlate build-system phases with recommendations ## Measurement Caveats ### COMPILATION_CACHE_ENABLE_CACHING `COMPILATION_CACHE_ENABLE_CACHING = YES` stores compiled artifacts in a system-managed cache outside DerivedData so that repeated compilations of identical inputs are served from cache. The standard clean-build benchmark (`xcodebuild clean` between runs) may add overhead from cache population without showing the corresponding cache-hit benefit. The benchmark script automatically detects `COMPILATION_CACHE_ENABLE_CACHING = YES` and runs a **cached clean** benchmark phase. This phase: 1. Builds once to warm the compilation cache. 2. Deletes DerivedData (but not the compilation cache) before each measured run. 3. Rebuilds, measuring the cache-hit clean build time. The cached clean metric captures the realistic developer experience: branch switching, pulling changes, and Clean Build Folder. Use the cached clean median as the primary comparison metric when evaluating `COMPILATION_CACHE_ENABLE_CACHING` impact. To skip this phase, pass `--n