Helm saw a 87% incremental build improvement (70s → 9s) after enabling
COMPILATION_CACHING. Also adds a general note above the table explaining
that a small clean-build increase is expected with compilation caching.
Skills referenced shared resources (scripts/, references/, schemas/) via paths
outside their own folder. When installed standalone via `npx skills add --skill`
or `cp -R skills/`, those external paths broke because only the skill folder
is copied.
Each skill now bundles its own copies of the scripts, references, and schemas
it needs. Root-level canonical copies remain for repo documentation and CI.
CONTRIBUTING.md documents which root files map to which skills.
The script was hard-coding the entire repo structure (references, schemas,
scripts, .claude-plugin) into the README skill tree. Simplified to only
output the skills/ directory, matching the intended structure.
- Fix 3b. to nested sub-bullet for valid Markdown list syntax
- Align ExtractAppIntentsMetadata wording in xcode-project-analyzer to
match the xcode-behavior classification from the audit checklist
- Add actionability field handling to generate_optimization_report.py
in both recommendation rendering and approval checklist
A community member ran the optimization skills on an older ObjC + CocoaPods
project. The agent improvised CocoaPods-specific changes not covered by any
reference material, overestimated how actionable some findings were, and
produced a 14% regression. This commit addresses the root causes:
- Add actionability classification (repo-local / package-manager /
xcode-behavior / upstream) to the recommendation format so every finding
states how fixable it is from the repo
- Add CocoaPods deprecation notice: do not attempt CocoaPods-specific
optimizations; recommend migrating to SPM instead
- Add regression-aware revert guidance: best-practice settings are never
revert candidates; speculative changes are only reverted when all build
types regress; compilation caching trade-offs are evaluated holistically
- Add structured execution report to the fixer and orchestrator template
so each change is tracked with its measured result and kept/reverted status
- Add benchmark confidence checks: flag high-variance runs and recommend
additional repetitions before drawing conclusions
- Clarify ExtractAppIntentsMetadata is Xcode-driven and not suppressible
from repo-local settings
The config files, assets, scripts, schemas, and references are already
described in the Shared Support Layer section. The structure tree now
focuses on what skill users care about: the six skills and their
reference files.
Bring the repo to parity with the SwiftUI-Agent-Skill reference:
- Add assets/logo.svg skill icon
- Add .cursor-plugin/plugin.json for Cursor marketplace submission
- Add agents/openai.yaml for Codex / OpenAI-compatible tools
- Update .claude-plugin/marketplace.json schema URL to full GitHub raw URL
- Update README with Cursor and Codex installation options and skill structure tree
The orchestrator references the other five skills via relative paths.
Installing only the orchestrator with --skill leaves those paths broken.
Drop the --skill flag from Quick Start so all skills are installed by
default, and clarify in Installation Options that the orchestrator
requires all skills.
Reorder README sections to front-load value: move How It Works and
Community Results above installation details, add an Every Second Counts
impact callout, rewrite How It Works with a mermaid orchestration diagram,
and add a What It Checks summary table linking to the new
OPTIMIZATION-CHECKS.md reference document.
OPTIMIZATION-CHECKS.md catalogues all 12 check categories with detailed
explanations and external references (Apple docs, WWDC sessions, articles).
Add Documentation Sync rules to AGENTS.md so future skill changes keep
README and OPTIMIZATION-CHECKS.md in sync.
Add Enchanted, Wikipedia iOS, and Kickstarter iOS to the community
results table with links to their upstream PRs.
Replace vague COMPILATION_CACHING language ("impact uncertain",
"trust documented benefit") with data-backed framing across all
skill docs: "Measured 5-14% faster clean builds across tested
projects (87 to 1,991 Swift files). Benefit compounds during
branch switching and pulling changes."
Replace the 7-column table with a compact 3-column format:
App, Clean Build, Incremental Build. Each cell uses arrow
notation with absolute and percentage deltas for clarity:
"41.5s → 33.2s (-8.3s / 20% faster)".
Add an anchor link early in the README so readers can jump
straight to the results. Add StockAnalyzer as the first
community entry. Update the orchestration report template
to generate matching copy-paste rows.
Standard clean builds show cache-population overhead without the
corresponding cache-hit benefit, making COMPILATION_CACHING appear
to regress performance. The new "cached clean" phase measures clean
builds with a warm compilation cache by deleting DerivedData (not
the system compilation cache) between runs. This captures the
realistic developer workflow: branch switching, pulling changes,
and Clean Build Folder.
Changes:
- benchmark_builds.py: auto-detect COMPILATION_CACHING and run
cached clean builds using a controlled DerivedData path
- Schema bumped to 1.2.0 with optional cached_clean runs/summary
- Report generator shows Cached Clean column when data is present
- All skill docs and references updated to use the cached clean
metric as the primary comparison for COMPILATION_CACHING impact
User feedback showed the skills were over-indexing on cumulative task time
(which Xcode parallelizes) and presenting it as build-time savings. This led
to many source-level fixes that reduced compiler workload without actually
reducing how long the developer waits.
Key changes:
- AGENTS.md: wall-clock first principle inherited by all skills
- Orchestrator: blocking-vs-parallel heuristics, impact language templates,
wall-clock-first final report
- Report script/template: timing-table disclaimers, wait-time impact field,
plain-language verification
- Compilation analyzer: parallel workload labeling when not on critical path
- Project/SPM analyzers: wall-clock qualifier on prioritization tiers
- Fixer: wall-clock delta leads reporting, honest language when task metrics
improve but wait time does not
- Benchmark artifacts: documents wall-clock vs cumulative distinction
- Recommendation format: new wait_time_impact required field
- Updated README.md to include a quick start guide for the xcode-build-orchestrator skill and detailed installation instructions.
- Added a new script, check_spm_pins.py, to scan for branch-pinned SPM dependencies and check tag availability.
- Enhanced benchmark_builds.py to support measuring real incremental builds with a new --touch-file option.
- Expanded generate_optimization_report.py to auto-generate recommendations based on audit results.
- Revised multiple SKILL.md files to clarify usage instructions and best practices for various skills, including zero-change build analysis and worktree considerations.
- Added sections on measurement caveats related to compilation caching and first-run variance in `benchmark-artifacts.md`.
- Updated `build-optimization-sources.md` with insights from Swift forums regarding slow incremental builds due to planning Swift modules.
- Improved `benchmark_builds.py` to include a warmup clean+build cycle for better cache performance measurement.
- Expanded `generate_optimization_report.py` to include general expectations for compilation caching.
- Revised multiple SKILL.md files to clarify verification processes for local packages and version pins, and to address Swift macro rebuild impacts.
- Updated orchestration report template to note limitations of measuring `COMPILATION_CACHING` improvements.
- Added a new skill: `xcode-build-fixer` for applying approved optimization changes.
- Introduced `xcode-build-orchestrator` to manage the optimization workflow.
- Updated existing skills to reflect new names and roles, including `xcode-compilation-analyzer` and `xcode-project-analyzer`.
- Revised documentation across multiple files to include six installable skills and their purposes.
- Enhanced contribution guidelines to align with the new skill structure.
- Updated plugin metadata to reflect the addition of new skills.
First versioned snapshot of the full skill repository including:
- Five installable agent skills under skills/
- Shared references, schemas, and helper scripts
- Plugin and marketplace metadata for Claude Code
- GitHub workflows for release and README sync
- Compilation caching as a recommended build setting
- Four deeper Swift compiler diagnostic flags for compilation analysis
- Fixed SWIFT_COMPILATION_MODE to use singlefile (actual build setting value)
Antoine van der Lee