@leejungkiin/awkit 1.4.0 → 1.4.2

package/skills/xcode-build-orchestrator/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: xcode-build-orchestrator
+description: Điều phối tối ưu hoá Xcode build bằng cách chạy benchmark trước, sau đó kích hoạt các skill phân tích chuyên sâu, ưu tiên các vấn đề tìm được, yêu cầu phê duyệt rõ ràng từ dev, giao phó việc sửa lỗi cho xcode-build-fixer, và cuối cùng chạy lại benchmark để đối chiếu. Sử dụng khi lập trình viên muốn một luồng tối ưu Xcode toàn diện từ A-Z, muốn tăng tốc độ build, cần audit toàn bộ cấu hình build, hoặc cần một đợt kiểm tra "đề xuất trước - sửa sau" bao gồm cả code, build settings và Swift Packages.
+---
+
+# Xcode Build Orchestrator
+
+Use this skill as the recommend-first entrypoint for end-to-end Xcode build optimization work.
+
+## Non-Negotiable Rules
+
+- Wall-clock build time (how long the developer waits) is the primary success metric. Every recommendation must state its expected impact on the developer's actual wait time.
+- Start in recommendation mode.
+- Benchmark before making changes.
+- Do not modify project files, source files, packages, or scripts without explicit developer approval.
+- Preserve the evidence trail for every recommendation.
+- Re-benchmark after approved changes and report the wall-clock delta.
+
+## Two-Phase Workflow
+
+The orchestration is designed as two distinct phases separated by developer review.
+
+### Phase 1 -- Analyze (recommend-only)
+
+Run this phase in agent mode because the agent needs to execute builds, run benchmark scripts, write benchmark artifacts, and generate the optimization report. However, treat Phase 1 as **recommend-only**: do not modify any project files, source files, packages, or build settings. The only files the agent creates during this phase are benchmark artifacts and the optimization plan inside `.build-benchmark/`.
+
+1. Collect the build target context: workspace or project, scheme, configuration, destination, and current pain point. When both `.xcworkspace` and `.xcodeproj` exist, prefer `.xcodeproj` unless the workspace contains sub-projects required for the build. Workspaces that reference external projects may fail if those projects are not checked out.
+2. Run `xcode-build-benchmark` to establish a baseline if no fresh benchmark exists. The benchmark script auto-detects `COMPILATION_CACHING = YES` and includes cached clean builds that measure the realistic developer experience (warm cache). If the build fails to compile, check `git log` for a recent buildable commit. When working in a worktree, cherry-picking a targeted build fix from a feature branch is acceptable to reach a buildable state. If SPM packages reference gitignored directories in their `exclude:` paths (e.g., `__Snapshots__`), create those directories before building -- worktrees do not contain gitignored content and `xcodebuild -resolvePackageDependencies` will crash otherwise.
+3. Verify the benchmark artifact has non-empty `timing_summary_categories`. If empty, the timing summary parser may have failed -- re-parse the raw logs or inspect them manually. If `COMPILATION_CACHING` is enabled, also verify the artifact includes `cached_clean` runs.
+   - **Benchmark confidence check**: For each build type (clean, cached clean, incremental), compare the min and max values. If the spread (max - min) exceeds 20% of the median, flag the benchmark as having high variance and recommend running additional repetitions (5+ runs) before drawing conclusions. High variance makes it difficult to distinguish real improvements from noise. After applying changes, only claim an improvement if the post-change median falls outside the baseline's min-max range.
+4. If incremental builds are the primary pain point and Xcode 16.4+ is available, recommend the developer enable **Task Backtraces** (Scheme Editor > Build tab > Build Debugging > "Task Backtraces"). This reveals why each task re-ran, which is critical for diagnosing unexpected replanning or input invalidation. Include any Task Backtrace evidence in the analysis.
+5. Determine whether compile tasks are likely blocking wall-clock progress or just consuming parallel CPU time. Compare the sum of all timing-summary category seconds against the wall-clock median: if the sum is 2x+ the median, most work is parallelized and compile hotspot fixes are unlikely to reduce wait time. If `SwiftCompile`, `CompileC`, `SwiftEmitModule`, or `Planning Swift module` dominate the timing summary **and** appear likely to be on the critical path, run `diagnose_compilation.py` to capture type-checking hotspots. If they are parallelized, still run diagnostics but label findings as "parallel efficiency improvements" rather than "build time improvements."
+6. Run the specialist analyses that fit the evidence by reading each skill's SKILL.md and applying its workflow:
+   - [`xcode-compilation-analyzer`](../xcode-compilation-analyzer/SKILL.md)
+   - [`xcode-project-analyzer`](../xcode-project-analyzer/SKILL.md)
+   - [`spm-build-analysis`](../spm-build-analysis/SKILL.md)
+7. Merge findings into a single prioritized improvement plan.
+8. Generate the markdown optimization report using `generate_optimization_report.py` and save it to `.build-benchmark/optimization-plan.md`. This report includes the build settings audit, timing analysis, prioritized recommendations, and an approval checklist.
+9. Stop and present the plan to the developer for review.
+
+The developer reviews `.build-benchmark/optimization-plan.md`, checks the approval boxes for the recommendations they want implemented, and then triggers phase 2.
+
+### Phase 2 -- Execute and verify (agent mode)
+
+Run this phase in agent mode after the developer has reviewed and approved recommendations from the plan. Delegate all implementation work to [`xcode-build-fixer`](../xcode-build-fixer/SKILL.md) by reading its SKILL.md and applying its workflow.
+
+10. Read `.build-benchmark/optimization-plan.md` and identify the approved items from the approval checklist.
+11. Hand off to `xcode-build-fixer` with the approved plan. The fixer applies each approved change, verifies compilation, and re-benchmarks.
+12. Append verification results to the optimization plan: post-change medians, absolute and percentage deltas, and confidence notes.
+13. Report before and after results, plus any remaining follow-up opportunities.
+
+## Prioritization Rules
+
+The goal is to reduce how long the developer waits for builds to finish.
+
+1. Identify the developer's primary pain (clean build, incremental build, or both) and the measured wall-clock median.
+2. Determine what is likely **blocking** wall-clock progress:
+   - If the sum of all timing-summary category seconds is 2x+ the wall-clock median, most work is parallelized. Compile hotspot fixes are unlikely to reduce wait time.
+   - If a single serial category (e.g. `PhaseScriptExecution`, `CompileAssetCatalog`, `CodeSign`) accounts for a large fraction of wall-clock, that is the real bottleneck.
+   - If `Planning Swift module` or `SwiftEmitModule` dominates incremental builds, the cause is likely invalidation or module size, not individual file compile speed.
+3. Rank recommendations by likely wall-time savings, not cumulative task reduction.
+4. Source-level compile fixes should not outrank project/graph/configuration fixes unless evidence suggests they are on the critical path.
+
+Prefer changes that are measurable, reversible, and low-risk.
+
+## Recommendation Impact Language
+
+Every recommendation presented to the developer must include one of these impact statements:
+
+- "Expected to reduce your [clean/incremental] build by approximately X seconds."
+- "Reduces parallel compile work but is unlikely to reduce your build wait time because other tasks take equally long."
+- "Impact on wait time is uncertain -- re-benchmark after applying to confirm."
+- "No wait-time improvement expected. The benefit is [deterministic builds / faster branch switching / reduced CI cost]."
+- For COMPILATION_CACHING specifically: "Measured 5-14% faster clean builds across tested projects. The benefit compounds in real workflows where the cache persists between builds -- branch switching, pulling changes, and CI with persistent DerivedData."
+
+Never quote cumulative task-time savings as the headline impact. If a change reduces 5 seconds of parallel compile work but another equally long task still runs, the developer's wait time does not change.
+
+## Approval Gate
+
+Before implementing anything, present a short approval list that includes:
+
+- recommendation name
+- expected wait-time impact (using the impact language above)
+- evidence summary
+- affected files or settings
+- whether the change is low, medium, or high risk
+
+Wait for explicit developer approval.
+
+## Post-Approval Execution
+
+After approval, delegate to `xcode-build-fixer`:
+
+- the fixer implements only the approved items
+- changes are applied atomically and kept scoped
+- any deviations from the original recommendation plan are noted
+- the fixer re-benchmarks with the same benchmark contract
+
+## Final Report
+
+Lead with the wall-clock result in plain language, e.g.: "Your clean build now takes 82s (was 86s) -- 4s faster." Then include:
+
+- baseline clean and incremental wall-clock medians
+- post-change clean and incremental wall-clock medians
+- absolute and percentage wall-clock deltas
+- what changed
+- what was intentionally left unchanged
+- confidence notes if noise prevents a strong conclusion -- if benchmark variance is high (min-to-max spread exceeds 20% of median), say so explicitly rather than presenting noisy numbers as definitive improvements or regressions
+- if cumulative task metrics improved but wall-clock did not, say plainly: "Compiler workload decreased but build wait time did not improve. This is expected when Xcode runs these tasks in parallel with other equally long work."
+- a ready-to-paste community results row and a link to open a PR (see the report template)
+
+## Preferred Command Paths
+
+### Benchmark
+
+```bash
+python3 scripts/benchmark_builds.py \
+  --project App.xcodeproj \
+  --scheme MyApp \
+  --configuration Debug \
+  --destination "platform=iOS Simulator,name=iPhone 16" \
+  --output-dir .build-benchmark
+```
+
+For macOS apps use `--destination "platform=macOS"`. For watchOS use `--destination "platform=watchOS Simulator,name=Apple Watch Series 10"`. For tvOS use `--destination "platform=tvOS Simulator,name=Apple TV"`. Omit `--destination` to use the scheme's default.
+
+To measure real incremental builds (file-touched rebuild) instead of zero-change builds, add `--touch-file path/to/SomeFile.swift`.
+
+### Compilation Diagnostics
+
+```bash
+python3 scripts/diagnose_compilation.py \
+  --project App.xcodeproj \
+  --scheme MyApp \
+  --configuration Debug \
+  --destination "platform=iOS Simulator,name=iPhone 16" \
+  --threshold 100 \
+  --output-dir .build-benchmark
+```
+
+### Optimization Report
+
+```bash
+python3 scripts/generate_optimization_report.py \
+  --benchmark .build-benchmark/<artifact>.json \
+  --project-path App.xcodeproj \
+  --diagnostics .build-benchmark/<diagnostics>.json \
+  --output .build-benchmark/optimization-plan.md
+```
+
+## Additional Resources
+
+- For the report template, see [references/orchestration-report-template.md](references/orchestration-report-template.md)
+- For benchmark artifact requirements, see [references/benchmark-artifacts.md](references/benchmark-artifacts.md)
+- For the recommendation format, see [references/recommendation-format.md](references/recommendation-format.md)
+- For build settings best practices, see [references/build-settings-best-practices.md](references/build-settings-best-practices.md)

package/skills/xcode-build-orchestrator/references/benchmark-artifacts.md

@@ -0,0 +1,94 @@
+# 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_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_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_CACHING
+
+`COMPILATION_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_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_CACHING` impact.
+
+To skip this phase, pass `--no-cached-clean`.
+
+### First-Run Variance
+
+The first clean build after the warmup cycle often runs 20-40% slower than subsequent clean builds due to cold OS-level caches (disk I/O, dynamic linker cache, etc.). The benchmark script mitigates this by running a warmup clean+build cycle before measured runs. If variance between the first and later clean runs is still high, prefer the median or min over the mean, and note the variance in the artifact's `notes` field.
+
+## Shared Consumer Expectations
+
+Any skill reading a benchmark artifact should be able to identify:
+
+- what was measured
+- how it was measured
+- whether the run succeeded
+- whether the results are stable enough to compare
+
+For the authoritative field-level schema, see the `build-benchmark.schema.json` bundled with the xcode-build-benchmark skill.

package/skills/xcode-build-orchestrator/references/build-settings-best-practices.md

@@ -0,0 +1,216 @@
+# Build Settings Best Practices
+
+This reference lists Xcode build settings that affect build performance. Use it to audit a project and produce a pass/fail checklist.
+
+The scope is strictly **build performance**. Do not flag language-migration settings like `SWIFT_STRICT_CONCURRENCY` or `SWIFT_UPCOMING_FEATURE_*` -- those are developer adoption choices unrelated to build speed.
+
+## How To Read This Reference
+
+Each setting includes:
+
+- **Setting name** and the Xcode build-settings key
+- **Recommended value** for Debug and Release
+- **Why it matters** for build time
+- **Risk** of changing it
+
+Use checkmark and cross indicators when reporting:
+
+- `[x]` -- setting matches the recommended value
+- `[ ]` -- setting does not match; include the actual value and the expected value
+
+## Debug Configuration
+
+These settings optimize for fast iteration during development.
+
+### Compilation Mode
+
+- **Key:** `SWIFT_COMPILATION_MODE`
+- **Recommended:** `singlefile` (Xcode UI: "Incremental"; or unset -- Xcode defaults to singlefile for Debug)
+- **Why:** Single-file mode recompiles only changed files. `wholemodule` recompiles the entire target on every change.
+- **Risk:** Low
+
+### Swift Optimization Level
+
+- **Key:** `SWIFT_OPTIMIZATION_LEVEL`
+- **Recommended:** `-Onone`
+- **Why:** Optimization passes add significant compile time. Debug builds do not benefit from runtime speed improvements.
+- **Risk:** Low
+
+### GCC Optimization Level
+
+- **Key:** `GCC_OPTIMIZATION_LEVEL`
+- **Recommended:** `0`
+- **Why:** Same rationale as Swift optimization level, but for C/C++/Objective-C sources.
+- **Risk:** Low
+
+### Build Active Architecture Only
+
+- **Key:** `ONLY_ACTIVE_ARCH` (`BUILD_ACTIVE_ARCHITECTURE_ONLY`)
+- **Recommended:** `YES`
+- **Why:** Building all architectures doubles or triples compile and link time for no debug benefit.
+- **Risk:** Low
+
+### Debug Information Format
+
+- **Key:** `DEBUG_INFORMATION_FORMAT`
+- **Recommended:** `dwarf`
+- **Why:** `dwarf-with-dsym` generates a separate dSYM bundle which adds overhead. Plain `dwarf` embeds debug info directly in the binary, which is sufficient for local debugging.
+- **Risk:** Low
+
+### Enable Testability
+
+- **Key:** `ENABLE_TESTABILITY`
+- **Recommended:** `YES`
+- **Why:** Required for `@testable import`. Adds minor overhead by exporting internal symbols, but this is expected during development.
+- **Risk:** Low
+
+### Active Compilation Conditions
+
+- **Key:** `SWIFT_ACTIVE_COMPILATION_CONDITIONS`
+- **Recommended:** Should include `DEBUG`
+- **Why:** Guards conditional compilation blocks (e.g., `#if DEBUG`) and ensures debug-only code paths are included.
+- **Risk:** Low
+
+### Eager Linking
+
+- **Key:** `EAGER_LINKING`
+- **Recommended:** `YES`
+- **Why:** Allows the linker to start work before all compilation tasks finish, reducing wall-clock build time. Particularly effective for Debug builds where link time is a meaningful fraction of total build time.
+- **Risk:** Low
+
+## Release Configuration
+
+These settings optimize for production builds.
+
+### Compilation Mode
+
+- **Key:** `SWIFT_COMPILATION_MODE`
+- **Recommended:** `wholemodule`
+- **Why:** Whole-module optimization produces faster runtime code. Build time is secondary for release.
+- **Risk:** Low
+
+### Swift Optimization Level
+
+- **Key:** `SWIFT_OPTIMIZATION_LEVEL`
+- **Recommended:** `-O` or `-Osize`
+- **Why:** Produces optimized binaries. `-Osize` trades some speed for smaller binary size.
+- **Risk:** Low
+
+### GCC Optimization Level
+
+- **Key:** `GCC_OPTIMIZATION_LEVEL`
+- **Recommended:** `s`
+- **Why:** Optimizes C/C++/Objective-C for size, matching the typical release expectation.
+- **Risk:** Low
+
+### Build Active Architecture Only
+
+- **Key:** `ONLY_ACTIVE_ARCH`
+- **Recommended:** `NO`
+- **Why:** Release builds must include all supported architectures for distribution.
+- **Risk:** Low
+
+### Debug Information Format
+
+- **Key:** `DEBUG_INFORMATION_FORMAT`
+- **Recommended:** `dwarf-with-dsym`
+- **Why:** dSYM bundles are required for crash symbolication in production.
+- **Risk:** Low
+
+### Enable Testability
+
+- **Key:** `ENABLE_TESTABILITY`
+- **Recommended:** `NO`
+- **Why:** Removes internal-symbol export overhead from release builds. Testing should use Debug configuration.
+- **Risk:** Low
+
+## General (All Configurations)
+
+### Compilation Caching
+
+- **Key:** `COMPILATION_CACHING`
+- **Recommended:** `YES`
+- **Why:** Caches compilation results for Swift and C-family sources so repeated compilations of the same inputs are served from cache. The biggest wins come from branch switching and clean builds where source files are recompiled unchanged. This is an opt-in feature. The umbrella setting controls both `SWIFT_ENABLE_COMPILE_CACHE` and `CLANG_ENABLE_COMPILE_CACHE` under the hood; those can be toggled independently if needed.
+- **Measurement:** Measured 5-14% faster clean builds across tested projects (87 to 1,991 Swift files). The benefit compounds in real developer workflows where the cache persists between builds -- branch switching, pulling changes, and CI with persistent DerivedData -- though the exact savings depend on how many files change between builds.
+- **Risk:** Low -- can also be enabled via per-user project settings so it does not need to be committed to the shared project file.
+
+### Integrated Swift Driver
+
+- **Key:** `SWIFT_USE_INTEGRATED_DRIVER`
+- **Recommended:** `YES`
+- **Why:** Uses the integrated Swift driver which runs inside the build system process, eliminating inter-process overhead for compilation scheduling. Enabled by default in modern Xcode but worth verifying in migrated projects.
+- **Risk:** Low
+
+### Clang Module Compilation
+
+- **Key:** `CLANG_ENABLE_MODULES`
+- **Recommended:** `YES`
+- **Why:** Enables Clang module compilation for C/Objective-C sources, caching module maps on disk instead of reprocessing headers on every import. Eliminates redundant header parsing across translation units.
+- **Risk:** Low
+
+### Explicit Module Builds
+
+- **Key:** `SWIFT_ENABLE_EXPLICIT_MODULES` (C/ObjC enabled by default in Xcode 16+; for Swift use `_EXPERIMENTAL_SWIFT_EXPLICIT_MODULES`)
+- **Recommended:** Evaluate per-project
+- **Why:** Makes module compilation visible to the build system as discrete tasks, improving parallelism and scheduling. Reduces redundant module rebuilds by making dependency edges explicit. Some projects see regressions due to the overhead of dependency scanning, so benchmark before and after enabling.
+- **Risk:** Medium -- test thoroughly; currently experimental for Swift targets.
+
+## Cross-Target Consistency
+
+These checks find settings differences between targets that cause redundant build work.
+
+### Project-Level vs Target-Level Overrides
+
+Build-affecting settings should be set at the project level unless a target has a specific reason to override. Unnecessary per-target overrides cause confusion and can silently create module variants.
+
+Settings to check for project-level consistency:
+
+- `SWIFT_COMPILATION_MODE`
+- `SWIFT_OPTIMIZATION_LEVEL`
+- `ONLY_ACTIVE_ARCH`
+- `DEBUG_INFORMATION_FORMAT`
+
+### Module Variant Duplication
+
+When multiple targets import the same SPM package but compile with different Swift compiler options, the build system produces separate module variants for each combination. This inflates `SwiftEmitModule` task counts.
+
+Check for drift in:
+
+- `SWIFT_OPTIMIZATION_LEVEL`
+- `SWIFT_COMPILATION_MODE`
+- `OTHER_SWIFT_FLAGS`
+- Target-level build settings that override project defaults
+
+### Out of Scope
+
+Do **not** flag the following as build-performance issues:
+
+- `SWIFT_STRICT_CONCURRENCY` -- language migration choice
+- `SWIFT_UPCOMING_FEATURE_*` -- language migration choice
+- `SWIFT_APPROACHABLE_CONCURRENCY` -- language migration choice
+- `SWIFT_ACTIVE_COMPILATION_CONDITIONS` values beyond `DEBUG` (e.g., `WIDGETS`, `APPCLIP`) -- intentional per-target customization
+
+## Checklist Output Format
+
+When reporting results, use this structure:
+
+```markdown
+### Debug Configuration
+- [x] `SWIFT_COMPILATION_MODE`: `singlefile` (recommended: `singlefile`)
+- [ ] `DEBUG_INFORMATION_FORMAT`: `dwarf-with-dsym` (recommended: `dwarf`)
+- [x] `SWIFT_OPTIMIZATION_LEVEL`: `-Onone` (recommended: `-Onone`)
+...
+
+### Release Configuration
+- [x] `SWIFT_COMPILATION_MODE`: `wholemodule` (recommended: `wholemodule`)
+...
+
+### General (All Configurations)
+- [ ] `COMPILATION_CACHING`: `NO` (recommended: `YES`)
+...
+
+### Cross-Target Consistency
+- [x] All targets inherit `SWIFT_OPTIMIZATION_LEVEL` from project level
+- [ ] `OTHER_SWIFT_FLAGS` differs between Stock Analyzer and StockAnalyzerClip
+...
+```

package/skills/xcode-build-orchestrator/references/orchestration-report-template.md

@@ -0,0 +1,143 @@
+# Orchestration Report Template
+
+Use this structure when the orchestrator consolidates benchmark evidence and specialist findings. The `generate_optimization_report.py` script produces this format automatically when given the benchmark and diagnostics artifacts.
+
+```markdown
+# Xcode Build Optimization Plan
+
+## Project Context
+- **Project:** `App.xcodeproj`
+- **Scheme:** `MyApp`
+- **Configuration:** `Debug`
+- **Destination:** `platform=iOS Simulator,name=iPhone 16`
+- **Xcode:** Xcode 26.x
+- **Date:** 2026-01-01T00:00:00Z
+- **Benchmark artifact:** `.build-benchmark/<timestamp>-<scheme>.json`
+
+## Baseline Benchmarks
+
+| Metric | Clean | Cached Clean | Zero-Change |
+|--------|-------|-------------|-------------|
+| Median | 0.000s | 0.000s | 0.000s |
+| Min | 0.000s | 0.000s | 0.000s |
+| Max | 0.000s | 0.000s | 0.000s |
+| Runs | 3 | 3 | 3 |
+
+> **Cached Clean** = clean build with a warm compilation cache. This is the realistic scenario for branch switching, pulling changes, or Clean Build Folder. Only present when `COMPILATION_CACHING = YES` is detected. "Zero-Change" = rebuild with no edits (measures fixed overhead). Use `--touch-file` in the benchmark script to measure true incremental builds where a source file is modified.
+
+### Clean Build Timing Summary
+
+> **Note:** These are aggregated task times across all CPU cores. Because Xcode runs many tasks in parallel, these totals typically exceed the actual build wait time shown above. A large number here does not mean it is blocking your build.
+
+| Category | Tasks | Seconds |
+|----------|------:|--------:|
+| SwiftCompile | 325 | 271.245s |
+| SwiftEmitModule | 30 | 23.625s |
+| ... | ... | ... |
+
+## Build Settings Audit
+
+### Debug Configuration
+- [x] `SWIFT_COMPILATION_MODE`: `(unset)` (recommended: `incremental`)
+- [x] `SWIFT_OPTIMIZATION_LEVEL`: `-Onone` (recommended: `-Onone`)
+- [x] `GCC_OPTIMIZATION_LEVEL`: `0` (recommended: `0`)
+- [x] `ONLY_ACTIVE_ARCH`: `YES` (recommended: `YES`)
+- [x] `DEBUG_INFORMATION_FORMAT`: `dwarf` (recommended: `dwarf`)
+- [x] `ENABLE_TESTABILITY`: `YES` (recommended: `YES`)
+- [x] `EAGER_LINKING`: `YES` (recommended: `YES`)
+
+### General (All Configurations)
+- [x] `COMPILATION_CACHING`: `YES` (recommended: `YES`)
+- [x] `SWIFT_USE_INTEGRATED_DRIVER`: `YES` (recommended: `YES`)
+- [x] `CLANG_ENABLE_MODULES`: `YES` (recommended: `YES`)
+
+### Release Configuration
+- [x] `SWIFT_COMPILATION_MODE`: `wholemodule` (recommended: `wholemodule`)
+- [x] `SWIFT_OPTIMIZATION_LEVEL`: `-O` (recommended: `-O`)
+- ...
+
+### Cross-Target Consistency
+- [x] `SWIFT_COMPILATION_MODE` is consistent across all targets
+- [ ] `OTHER_SWIFT_FLAGS` has target-level overrides: ...
+
+## Compilation Diagnostics
+
+| Duration | Kind | File | Line | Name |
+|---------:|------|------|-----:|------|
+| 150ms | function-body | MyView.swift | 42 | body |
+| ... | ... | ... | ... | ... |
+
+## Prioritized Recommendations
+
+### 1. Recommendation title
+**Wait-Time Impact:** Expected to reduce your clean build by approximately 3 seconds.
+**Category:** project
+**Evidence:** ...
+**Impact:** High
+**Confidence:** High
+**Risk:** Low
+
+## Approval Checklist
+- [ ] **1. Recommendation title** -- Wait-Time Impact: ~3s clean build reduction | Risk: Low
+- [ ] **2. Another recommendation** -- Wait-Time Impact: Uncertain, re-benchmark to confirm | Risk: Low
+
+## Next Steps
+
+After implementing approved changes, re-benchmark with the same inputs:
+
+...
+
+Compare the new wall-clock medians against the baseline. Report results as:
+"Your [clean/incremental] build now takes X.Xs (was Y.Ys) -- Z.Zs faster/slower."
+
+## Execution Report (post-approval)
+
+### Baseline
+- Clean build median: X.Xs
+- Cached clean build median: X.Xs (if applicable)
+- Incremental build median: X.Xs
+
+### Changes Applied
+
+| # | Change | Actionability | Measured Result | Status |
+|---|--------|---------------|-----------------|--------|
+| 1 | Description of change | repo-local | Clean: X.Xs→Y.Ys, Incr: X.Xs→Y.Ys | Kept / Reverted / Blocked |
+| 2 | ... | ... | ... | ... |
+
+Status values: `Kept`, `Kept (best practice)`, `Reverted`, `Blocked`, `No improvement`
+
+### Final Cumulative Result
+- Post-change clean build: X.Xs (was Y.Ys) -- Z.Zs faster/slower
+- Post-change cached clean build: X.Xs (was Y.Ys) -- Z.Zs faster/slower (when COMPILATION_CACHING enabled)
+- Post-change incremental build: X.Xs (was Y.Ys) -- Z.Zs faster/slower
+- **Net result:** Faster / Slower / Unchanged
+- If cumulative task metrics improved but wall-clock did not: "Compiler workload decreased but build wait time did not improve. This is expected when Xcode runs these tasks in parallel with other equally long work."
+- If standard clean builds are slower but cached clean builds are faster: "Standard clean builds show overhead from compilation cache population. Cached clean builds (the realistic developer workflow) are faster, confirming the net benefit."
+
+### Blocked or Non-Actionable Findings
+- Finding: reason it could not be addressed from the repo
+
+## Remaining follow-up ideas
+- Item:
+- Why it was deferred:
+
+## Share your results
+
+Add your improvement to the community results table by opening a pull request.
+Copy the row below and append it to the table in README.md:
+
+| <project-name> | X.Xs → X.Xs (-X.Xs / X% faster) | X.Xs → X.Xs (-X.Xs / X% faster) |
+
+Open a PR: https://github.com/AvdLee/Xcode-Build-Optimization-Agent-Skill/edit/main/README.md
+```
+
+## Usage Notes
+
+- Keep approval-required items explicit.
+- Do not imply that an unapproved recommendation was applied.
+- If results are noisy, say that the verification is inconclusive instead of overstating success.
+- The Build Settings Audit scope is strictly build performance. Do not flag language-migration settings like `SWIFT_STRICT_CONCURRENCY` or `SWIFT_UPCOMING_FEATURE_*`.
+- The Compilation Diagnostics section is populated by `diagnose_compilation.py`. If not run, note that it was skipped.
+- `COMPILATION_CACHING` has been measured at 5-14% faster clean builds across tested projects. The benefit compounds in real developer workflows (branch switching, pulling changes, CI with persistent DerivedData). The benchmark script auto-detects this setting and runs a cached clean phase for validation.
+- When recommending SPM version pins, verify that tagged versions exist (`git ls-remote --tags`) before suggesting a pin-to-tag change. If no tags exist, recommend pinning to a commit revision hash.
+- Before including a local package in a build-time recommendation, verify it is referenced in `project.pbxproj` via `XCLocalSwiftPackageReference`. Packages that exist on disk but are not linked do not affect build time.