Bundle scripts, references, and schemas inside each skill for standalone installation

AGENTS.md

@@ -4,8 +4,8 @@ This is a multi-skill Xcode build optimization repository.
 
 ## Layout
 
-- `skills/` contains six installable Agent Skills, each with a `SKILL.md` entrypoint.
-- `references/`, `schemas/`, and `scripts/` at the repo root are shared support files used by the skills.
+- `skills/` contains six installable Agent Skills, each with a `SKILL.md` entrypoint. Each skill bundles its own scripts, references, and schemas so it works after standalone installation.
+- `references/`, `schemas/`, and `scripts/` at the repo root are canonical copies of the shared support files. Changes to these must be synced into the skill folders that use them (see CONTRIBUTING.md).
 - `.claude-plugin/` contains plugin and marketplace metadata.
 
 ## Skills
@@ -27,7 +27,7 @@ This is a multi-skill Xcode build optimization repository.
 - Benchmark before optimizing. Use `.build-benchmark/` artifacts as evidence.
 - Treat clean and incremental builds as separate metrics.
 - The orchestrator (`xcode-build-orchestrator`) is the primary entrypoint for end-to-end work.
-- Shared references and schemas live at the repo root, not inside individual skills.
+- Each skill bundles its own copies of scripts, references, and schemas for standalone installation. Root-level `scripts/`, `references/`, and `schemas/` are the canonical copies; keep both layers in sync.
 
 ## Handoff Between Skills
 

CONTRIBUTING.md

@@ -6,8 +6,8 @@ Thanks for helping improve this repository. Contributions are welcome when they
 
 This is a multi-skill repository that follows the Agent Skills open format:
 
-- Skills live under `skills/`, each with a `SKILL.md` entrypoint.
-- Shared reference material lives in `references/`, `schemas/`, and `scripts/` at the repo root.
+- Skills live under `skills/`, each with a `SKILL.md` entrypoint. Each skill bundles its own scripts, references, and schemas so it works after standalone installation.
+- Canonical copies of shared files live in `references/`, `schemas/`, and `scripts/` at the repo root. When a root-level file changes, update the copies inside every skill that bundles it (see "Keeping shared files in sync" below).
 - The skills are intentionally recommend-first. They should not make project or source changes without explicit developer approval.
 
 ## Recommended Workflow
@@ -57,6 +57,22 @@ Avoid broad iOS architecture guidance, CI platform evangelism, or product docume
 - Avoid network calls in scripts and GitHub Actions unless they are clearly required.
 - If you add or rename reference files, update the README structure block or let the sync workflow do it.
 
+### Keeping shared files in sync
+
+Each skill bundles copies of the scripts and references it needs. The root-level `scripts/`, `references/`, and `schemas/` directories hold the canonical versions. When you change a root-level file, copy the updated version into every skill folder that includes it:
+
+| Root file | Bundled in skills |
+|-----------|-------------------|
+| `scripts/benchmark_builds.py` | xcode-build-benchmark, xcode-build-orchestrator, xcode-build-fixer |
+| `scripts/diagnose_compilation.py` | xcode-compilation-analyzer, xcode-build-orchestrator |
+| `scripts/generate_optimization_report.py` | xcode-build-orchestrator |
+| `scripts/check_spm_pins.py` | spm-build-analysis |
+| `references/benchmark-artifacts.md` | xcode-build-benchmark, xcode-build-orchestrator |
+| `references/build-settings-best-practices.md` | xcode-project-analyzer, xcode-build-orchestrator, xcode-build-fixer |
+| `references/recommendation-format.md` | xcode-compilation-analyzer, xcode-project-analyzer, spm-build-analysis, xcode-build-orchestrator, xcode-build-fixer |
+| `references/build-optimization-sources.md` | xcode-compilation-analyzer, xcode-project-analyzer, spm-build-analysis |
+| `schemas/build-benchmark.schema.json` | xcode-build-benchmark |
+
 ## Typical Contribution Types
 
 - Improve one of the six skill entrypoints.

README.md

@@ -206,13 +206,13 @@ That distinction is central to this repo and follows both Apple's Xcode guidance
 
 ## Shared Support Layer
 
-The skills share:
+Each skill bundles its own copies of the scripts, references, and schemas it needs so it works after standalone installation. The canonical copies live at the repo root:
 
-- a common `.build-benchmark/` artifact contract
-- a shared JSON schema for benchmark output
-- helper scripts for benchmarking, timing-summary parsing, compilation diagnostics, report generation, and recommendation rendering
-- a build settings best practices reference for the pass/fail audit
-- a single source summary file so README and skill guidance stay aligned
+- `scripts/` -- helper scripts for benchmarking, timing-summary parsing, compilation diagnostics, report generation, and recommendation rendering
+- `references/` -- build settings best practices, artifact format, recommendation format, and source citations
+- `schemas/` -- JSON schema for benchmark output
+
+When a root-level file changes, the corresponding copies inside each skill that uses it must be updated (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 
 ## Skill Structure
 <!-- BEGIN SKILL STRUCTURE -->
@@ -221,27 +221,40 @@ skills/
   xcode-build-benchmark/
     SKILL.md
     references/
+      benchmark-artifacts.md
       benchmarking-workflow.md
   xcode-compilation-analyzer/
     SKILL.md
     references/
+      build-optimization-sources.md
       code-compilation-checks.md
+      recommendation-format.md
   xcode-project-analyzer/
     SKILL.md
     references/
+      build-optimization-sources.md
+      build-settings-best-practices.md
       project-audit-checks.md
+      recommendation-format.md
   spm-build-analysis/
     SKILL.md
     references/
+      build-optimization-sources.md
+      recommendation-format.md
       spm-analysis-checks.md
   xcode-build-orchestrator/
     SKILL.md
     references/
+      benchmark-artifacts.md
+      build-settings-best-practices.md
       orchestration-report-template.md
+      recommendation-format.md
   xcode-build-fixer/
     SKILL.md
     references/
+      build-settings-best-practices.md
       fix-patterns.md
+      recommendation-format.md
 ```
 <!-- END SKILL STRUCTURE -->
 

skills/spm-build-analysis/SKILL.md

@@ -88,5 +88,5 @@ If the main problem is not package-related, hand off to [`xcode-project-analyzer
 ## Additional Resources
 
 - For the detailed audit checklist, see [references/spm-analysis-checks.md](references/spm-analysis-checks.md)
-- For the shared recommendation structure, see [../../references/recommendation-format.md](../../references/recommendation-format.md)
-- For source citations, see [../../references/build-optimization-sources.md](../../references/build-optimization-sources.md)
+- For the shared recommendation structure, see [references/recommendation-format.md](references/recommendation-format.md)
+- For source citations, see [references/build-optimization-sources.md](references/build-optimization-sources.md)

skills/spm-build-analysis/references/build-optimization-sources.md

@@ -0,0 +1,159 @@
+# Build Optimization Sources
+
+This file stores the external sources that the README and skill docs should cite consistently.
+
+## Apple: Improving the speed of incremental builds
+
+Source:
+
+- <https://developer.apple.com/documentation/xcode/improving-the-speed-of-incremental-builds>
+
+Key takeaways:
+
+- Measure first with `Build With Timing Summary` or `xcodebuild -showBuildTimingSummary`.
+- Accurate target dependencies improve correctness and parallelism.
+- Run scripts should declare inputs and outputs so Xcode can skip unnecessary work.
+- `.xcfilelist` files are appropriate when scripts have many inputs or outputs.
+- Custom frameworks and libraries benefit from module maps, typically by enabling `DEFINES_MODULE`.
+- Module reuse is strongest when related sources compile with consistent options.
+- Breaking monolithic targets into better-scoped modules can reduce unnecessary rebuilds.
+
+## Apple: Improving build efficiency with good coding practices
+
+Source:
+
+- <https://developer.apple.com/documentation/xcode/improving-build-efficiency-with-good-coding-practices>
+
+Key takeaways:
+
+- Use framework-qualified imports when module maps are available.
+- Keep Objective-C bridging surfaces narrow.
+- Prefer explicit type information when inference becomes expensive.
+- Use explicit delegate protocols instead of overly generic delegate types.
+- Simplify complex expressions that are hard for the compiler to type-check.
+
+## Apple: Building your project with explicit module dependencies
+
+Source:
+
+- <https://developer.apple.com/documentation/xcode/building-your-project-with-explicit-module-dependencies>
+
+Key takeaways:
+
+- Explicit module builds make module work visible in the build log and improve scheduling.
+- Repeated builds of the same module often point to avoidable module variants.
+- Inconsistent build options across targets can force duplicate module builds.
+- Timing summaries can reveal option drift that prevents module reuse.
+
+## SwiftLee: Build performance analysis for speeding up Xcode builds
+
+Source:
+
+- <https://www.avanderlee.com/optimization/analysing-build-performance-xcode/>
+
+Key takeaways:
+
+- Clean and incremental builds should both be measured because they reveal different problems.
+- Build Timeline and Build Timing Summary are practical starting points for build optimization.
+- Build scripts often produce large incremental-build wins when guarded correctly.
+- `-warn-long-function-bodies` and `-warn-long-expression-type-checking` help surface compile hotspots.
+- Typical debug and release build setting mismatches are worth auditing, especially in older projects.
+
+## Apple: Xcode Release Notes -- Compilation Caching
+
+Source:
+
+- Xcode Release Notes (149700201)
+
+Key takeaways:
+
+- Compilation caching is an opt-in feature for Swift and C-family languages.
+- It caches prior compilation results and reuses them when the same source inputs are recompiled.
+- Branch switching and clean builds benefit the most.
+- Can be enabled via the "Enable Compilation Caching" build setting or per-user project settings.
+
+## Apple: Demystify explicitly built modules (WWDC24)
+
+Source:
+
+- <https://developer.apple.com/videos/play/wwdc2024/10171/>
+
+Key takeaways:
+
+- Explains how explicitly built modules divide compilation into scan, module build, and source compile stages.
+- Unrelated modules build in parallel, improving CPU utilization.
+- Module variant duplication is a key bottleneck -- uniform compiler options across targets prevent it.
+- The build log shows each module as a discrete task, making it easier to diagnose scheduling issues.
+
+## Stackademic: Improving Swift Compile-Time Performance -- 14 Tips
+
+Source:
+
+- <https://blog.stackademic.com/improving-swift-compile-time-performance-14-tips-that-actually-work-f511d9b53209>
+
+Key takeaways:
+
+- Mark classes `final` to eliminate virtual dispatch overhead and help the compiler optimize.
+- Use `private`/`fileprivate` for symbols not used outside their scope.
+- Prefer `struct` and `enum` over `class` when reference semantics are not needed.
+- Avoid long method chains without intermediate type annotations -- even simple-looking chains can take seconds to compile.
+- Add explicit return types to closures passed to generic functions.
+- Break large SwiftUI view bodies into smaller composed subviews.
+
+## Bitrise: Demystifying Explicitly Built Modules for Xcode
+
+Source:
+
+- <https://bitrise.io/blog/post/demystifying-explicitly-built-modules-for-xcode>
+
+Key takeaways:
+
+- Explicit module builds give `xcodebuild` visibility into smaller compilation tasks for better parallelism.
+- Enabled by default for C/Objective-C in Xcode 16+; experimental for Swift.
+- Minimizing module variants by aligning build options is the primary optimization lever.
+- Some projects see regressions from dependency scanning overhead -- benchmark before and after.
+
+## Bitrise: Xcode Compilation Cache FAQ
+
+Source:
+
+- <https://docs.bitrise.io/en/bitrise-build-cache/build-cache-for-xcode/xcode-compilation-cache-faq.html>
+
+Key takeaways:
+
+- Granular caching is controlled by `SWIFT_ENABLE_COMPILE_CACHE` and `CLANG_ENABLE_COMPILE_CACHE`, under the umbrella `COMPILATION_CACHING` setting.
+- Non-cacheable tasks include `CompileStoryboard`, `CompileXIB`, `CompileAssetCatalogVariant`, `PhaseScriptExecution`, `DataModelCompile`, `CopyPNGFile`, `GenerateDSYMFile`, and `Ld`.
+- SPM dependencies are not yet cacheable as of Xcode 26 beta.
+
+## RocketSim Docs: Build Insights
+
+Sources:
+
+- <https://www.rocketsim.app/docs/features/build-insights/build-insights/>
+- <https://www.rocketsim.app/docs/features/build-insights/team-build-insights/>
+
+Key takeaways:
+
+- RocketSim automatically tracks clean vs incremental builds over time without build scripts.
+- It reports build counts, duration trends, and percentile-based metrics such as p75 and p95.
+- Team Build Insights adds machine, Xcode, and macOS comparisons for cross-team visibility.
+- This repository is best positioned as the point-in-time analyze-and-improve toolkit, while RocketSim is the monitor-over-time companion.
+
+## Swift Forums: Slow incremental builds because of planning swift module
+
+Source:
+
+- <https://forums.swift.org/t/slow-incremental-builds-because-of-planning-swift-module/84803>
+
+Key takeaways:
+
+- "Planning Swift module" can dominate incremental builds (up to 30s per module), sometimes exceeding clean build time.
+- Replanning every module without scheduling compiles is a sign that build inputs are being modified unexpectedly (e.g., a misconfigured linter touching file timestamps).
+- Enable **Task Backtraces** (Xcode 16.4+: Scheme Editor > Build > Build Debugging) to see why each task re-ran in an incremental build.
+- Heavy Swift macro usage (e.g., TCA / swift-syntax) can cause trivial changes to cascade into near-full rebuilds.
+- `swift-syntax` builds universally (all architectures) when no prebuilt binary is available, adding significant overhead.
+- `SwiftEmitModule` can take 60s+ after a single-line change in large modules.
+- Asset catalog compilation is single-threaded per target; splitting assets into separate bundles across targets enables parallel compilation.
+- Multi-platform targets (e.g., adding watchOS) can cause SPM packages to build 3x (iOS arm64, iOS x86_64, watchOS arm64).
+- Zero-change incremental builds still incur ~10s of fixed overhead: compute dependencies, send project description, create build description, script phases, codesigning, and validation.
+- Codesigning and validation run even when output has not changed.

skills/spm-build-analysis/references/recommendation-format.md

@@ -0,0 +1,85 @@
+# Recommendation Format
+
+All optimization skills should report recommendations in a shared structure so the orchestrator can merge and prioritize them cleanly.
+
+## Required Fields
+
+Each recommendation should include:
+
+- `title`
+- `wait_time_impact` -- plain-language statement of expected wall-clock impact, e.g. "Expected to reduce your clean build by ~3s", "Reduces parallel compile work but unlikely to reduce build wait time", or "Impact on wait time is uncertain -- re-benchmark to confirm"
+- `actionability` -- classifies how fixable the issue is from the project (see values below)
+- `category`
+- `observed_evidence`
+- `estimated_impact`
+- `confidence`
+- `approval_required`
+- `benchmark_verification_status`
+
+### Actionability Values
+
+Every recommendation must include an `actionability` classification:
+
+- `repo-local` -- Fix lives entirely in project files, source code, or local configuration. The developer can apply it without side effects outside the repo.
+- `package-manager` -- Requires CocoaPods or SPM configuration changes that may have broad side effects (e.g., linkage mode, dependency restructuring). These should be benchmarked before and after.
+- `xcode-behavior` -- Observed cost is driven by Xcode internals and is not suppressible from the project. Report the finding for awareness but do not promise a fix.
+- `upstream` -- Requires changes in a third-party dependency or external tool. The developer cannot fix it locally.
+
+## Suggested Optional Fields
+
+- `scope`
+- `affected_files`
+- `affected_targets`
+- `affected_packages`
+- `implementation_notes`
+- `risk_level`
+
+## JSON Example
+
+```json
+{
+  "recommendations": [
+    {
+      "title": "Guard a release-only symbol upload script",
+      "wait_time_impact": "Expected to reduce your incremental build by approximately 6 seconds.",
+      "actionability": "repo-local",
+      "category": "project",
+      "observed_evidence": [
+        "Incremental builds spend 6.3 seconds in a run script phase.",
+        "The script runs for Debug builds even though the output is only needed in Release."
+      ],
+      "estimated_impact": "High incremental-build improvement",
+      "confidence": "High",
+      "approval_required": true,
+      "benchmark_verification_status": "Not yet verified",
+      "scope": "Target build phase",
+      "risk_level": "Low"
+    }
+  ]
+}
+```
+
+## Markdown Rendering Guidance
+
+When rendering for human review, preserve the same field order:
+
+1. title
+2. wait-time impact
+3. actionability
+4. observed evidence
+5. estimated impact
+6. confidence
+7. approval required
+8. benchmark verification status
+
+That makes it easier for the developer to approve or reject specific items quickly.
+
+## Verification Status Values
+
+Recommended values:
+
+- `Not yet verified`
+- `Queued for verification`
+- `Verified improvement`
+- `No measurable improvement`
+- `Inconclusive due to benchmark noise`