--- name: axiom-ios-build description: Use when ANY iOS build fails, test crashes, Xcode misbehaves, or environment issue occurs before debugging code. Covers build failures, compilation errors, dependency conflicts, simulator problems, environment-first diagnostics. license: MIT --- # iOS Build & Environment Router **You MUST use this skill for ANY build, environment, or Xcode-related issue before debugging application code.** ## When to Use Use this router when you encounter: - Build failures (`BUILD FAILED`, compilation errors, linker errors) - Test crashes or hangs - Simulator issues (won't boot, device errors) - Xcode misbehavior (stale builds, zombie processes) - Dependency conflicts (CocoaPods, SPM) - Build performance issues (slow compilation) - Environment issues before debugging code ## Routing Logic This router invokes specialized skills based on the specific issue: ### 1. Environment-First Issues → **xcode-debugging** **Triggers**: - `BUILD FAILED` without obvious code cause - Tests crash in clean project - Simulator hangs or won't boot - "No such module" after SPM changes - Zombie `xcodebuild` processes - Stale builds (old code still running) - Clean build differs from incremental build **Why xcode-debugging first**: 90% of mysterious issues are environment, not code. Check this BEFORE debugging code. **Invoke**: `/skill axiom-xcode-debugging` --- ### 2. Slow Builds → **build-performance** **Triggers**: - Compilation takes too long - Type checking bottlenecks - Want to optimize build time - Build Timeline shows slow phases **Invoke**: `/skill axiom-build-performance` --- ### 3. SPM Dependency Conflicts → **spm-conflict-resolver** (Agent) **Triggers**: - SPM resolution failures - "No such module" after adding package - Duplicate symbol linker errors - Version conflicts between packages - Swift 6 package compatibility issues - Package.swift / Package.resolved conflicts **Why spm-conflict-resolver**: Specialized agent that analyzes Package.swift and Package.resolved to diagnose and resolve Swift Package Manager conflicts. **Invoke**: Launch `spm-conflict-resolver` agent --- ### 4. Security & Privacy Audit → **security-privacy-scanner** (Agent) **Triggers**: - App Store submission prep - Privacy Manifest requirements (iOS 17+) - Hardcoded credentials in code - Sensitive data storage concerns - ATS violations - Required Reason API declarations **Why security-privacy-scanner**: Specialized agent that scans for security vulnerabilities and privacy compliance issues. **Invoke**: Launch `security-privacy-scanner` agent or `/axiom:audit security` --- ### 5. iOS 17→18 Modernization → **modernization-helper** (Agent) **Triggers**: - Migrate ObservableObject to @Observable - Update @StateObject to @State - Adopt modern SwiftUI patterns - Deprecated API cleanup - iOS 17+ migration **Why modernization-helper**: Specialized agent that scans for legacy patterns and provides migration paths with code examples. **Invoke**: Launch `modernization-helper` agent or `/axiom:audit modernization` --- ### 6. Build Failure Auto-Fix → **build-fixer** (Agent) **Triggers**: - BUILD FAILED with no clear error details - Build sometimes succeeds, sometimes fails - App builds but runs old code - "Unable to boot simulator" error - Want automated environment-first diagnostics **Why build-fixer**: Autonomous agent that checks zombie processes, Derived Data, SPM cache, and simulator state before investigating code. Saves 30+ minutes on environment issues. **Invoke**: Launch `build-fixer` agent or `/axiom:fix-build` --- ### 7. Slow Build Optimization → **build-optimizer** (Agent) **Triggers**: - Builds take too long - Want to identify slow type checking - Expensive build phase scripts - Suboptimal build settings - Want parallelization opportunities **Why build-optimizer**: Scans Xcode projects for build performance optimizations — slow type checking, expensive scripts, suboptimal settings — to reduce build times by 30-50%. **Invoke**: Launch `build-optimizer` agent or `/axiom:optimize-build` --- ### 8. General Dependency Issues → **build-debugging** **Triggers**: - CocoaPods resolution failures - "Multiple commands produce" errors - Framework version mismatches - Non-SPM dependency graph conflicts **Invoke**: `/skill axiom-build-debugging` --- ### 9. TestFlight Crash Triage → **testflight-triage** **Triggers**: - Beta tester reported a crash - Crash reports in Xcode Organizer - Crash logs aren't symbolicated - TestFlight feedback with screenshots - App was killed but no crash report **Why testflight-triage**: Systematic workflow for investigating TestFlight crashes and reviewing beta feedback. Covers symbolication, crash interpretation, common patterns, and Claude-assisted analysis. **Invoke**: `/skill axiom-testflight-triage` --- ### 10. App Store Connect Navigation → **app-store-connect-ref** **Triggers**: - How to find crashes in App Store Connect - ASC metrics dashboard navigation - Understanding crash-free users percentage - Comparing crash rates between versions - Exporting crash data from ASC - App Store Connect API for crash data **Why app-store-connect-ref**: Reference for navigating ASC crash analysis, metrics dashboards, and data export workflows. **Invoke**: `/skill axiom-app-store-connect-ref` --- ### 11. Crash Log Analysis → **crash-analyzer** (Agent) **Triggers**: - User has .ips or .crash file to analyze - User pasted crash report text - Need to parse crash log programmatically - Identify crash pattern from exception type - Check symbolication status **Why crash-analyzer**: Autonomous agent that parses crash reports, identifies patterns (null pointer, Swift runtime, watchdog, jetsam), and generates actionable analysis. **Invoke**: Launch `crash-analyzer` agent or `/axiom:analyze-crash` --- ### 12. MetricKit API Reference → **metrickit-ref** **Triggers**: - MetricKit setup and subscription - MXMetricPayload parsing (CPU, memory, launches, hitches) - MXDiagnosticPayload parsing (crashes, hangs, disk writes) - MXCallStackTree decoding and symbolication - Field crash/hang collection - Background exit metrics **Why metrickit-ref**: Complete MetricKit API reference with setup patterns, payload parsing, and integration with crash reporting systems. **Invoke**: `/skill axiom-metrickit-ref` --- ### 13. Hang Diagnostics → **hang-diagnostics** **Triggers**: - App hangs or freezes - Main thread blocked for >1 second - UI unresponsive to touches - Xcode Organizer shows hang diagnostics - MXHangDiagnostic from MetricKit - Watchdog terminations (app killed during launch/background transition) **Why hang-diagnostics**: Systematic diagnosis of hangs with decision tree for busy vs blocked main thread, tool selection (Time Profiler, System Trace), and 8 common hang patterns with fixes. **Invoke**: `/skill axiom-hang-diagnostics` --- ### 14. Live Debugging → **axiom-lldb** **Triggers**: - Need to reproduce a crash interactively - Want to set breakpoints and inspect state - Crash report analyzed, now need live investigation - Need to attach debugger to running app **Why axiom-lldb**: Crash reports tell you WHAT crashed. LLDB tells you WHY. **Invoke**: `/skill axiom-lldb` --- ### 16. Runtime Console Capture → **xclog-ref** **Triggers**: - Need to see what the app is logging at runtime - App crashes but no crash report (need console output) - Silent failures (network, data, auth) with no UI feedback - Want to capture print()/os_log() output from simulator - Need structured log output for analysis - "What is the app printing?" **Why xclog-ref**: Xcode's debug console isn't accessible externally. xclog combines simctl stdout/stderr with `log stream` JSON to capture everything print(), NSLog(), os_log(), and Logger emit — with structured fields (level, subsystem, category) for automated analysis. **Invoke**: `/skill axiom-xclog-ref` or `/axiom:console` --- ### 15. Code Signing Issues → **code-signing** **Triggers**: - "No signing certificate found" - "Provisioning profile doesn't include signing certificate" - errSecInternalComponent in CI - ITMS-90035 Invalid Signature on upload - Ambiguous identity / multiple certificates - Entitlement mismatch or missing capability - Setting up CI/CD code signing (GitHub Actions, fastlane match) - Certificate expired or revoked **Why code-signing**: Code signing errors are NEVER code bugs — they are 100% configuration (certificates, profiles, entitlements, keychains). Diagnosing with CLI tools takes 5 minutes vs hours of guessing. **Invoke**: `/skill axiom-code-signing` (workflows) or `/skill axiom-code-signing-diag` (troubleshooting) --- ## Decision Tree 1. Mysterious/intermittent/clean build fails? → xcode-debugging (environment-first) 2. SPM dependency conflict? → spm-conflict-resolver (Agent) 3. CocoaPods/other dependency conflict? → build-debugging 4. Slow build time? → build-performance 5. Security/privacy/App Store prep? → security-privacy-scanner (Agent) 6. Want automated build fix (environment-first diagnostics)? → build-fixer (Agent) 7. Want build time optimization scan? → build-optimizer (Agent) 8. Modernization/deprecated APIs? → modernization-helper (Agent) 9. TestFlight crash/feedback? → testflight-triage 10. Navigating App Store Connect? → app-store-connect-ref 11. Have a crash log (.ips/.crash)? → crash-analyzer (Agent) 12. MetricKit setup/parsing? → metrickit-ref 13. App hang/freeze/watchdog? → hang-diagnostics 14. Need to reproduce crash interactively / inspect runtime state? → axiom-lldb 15. Code signing error (certificate, profile, entitlement, Keychain)? → code-signing / code-signing-diag 16. Need to see runtime console output (print/os_log)? → xclog-ref or `/axiom:console` ## Anti-Rationalization | Thought | Reality | |---------|---------| | "I know how to fix this linker error" | Linker errors have 4+ root causes. xcode-debugging diagnoses all in 2 min. | | "Let me just clean the build folder" | Clean builds mask the real issue. xcode-debugging finds the root cause. | | "It's just an SPM issue, I'll fix Package.swift" | SPM conflicts cascade. spm-conflict-resolver analyzes the full dependency graph. | | "The simulator is just slow today" | Simulator issues indicate environment corruption. xcode-debugging checks systematically. | | "I'll skip environment checks, it compiles locally" | Environment-first saves 30+ min. Every time. | | "I'll read the crash report more carefully instead of reproducing" | Crash reports show WHAT crashed, not WHY. Reproducing in LLDB with breakpoints reveals the actual state. axiom-lldb has the workflow. | | "I know my certificate is fine, let me check the code" | Code signing errors are NEVER code bugs. 100% configuration. code-signing diagnoses with CLI in 5 min. | | "I can't see what the app is logging without Xcode" | xclog captures print() + os_log from the simulator. Structured JSON output with level, subsystem, category. `/axiom:console` or `/skill axiom-xclog-ref`. | ## When NOT to Use (Conflict Resolution) **Do NOT use ios-build for these — use the correct router instead:** | Error Type | Correct Router | Why NOT ios-build | |------------|----------------|-------------------| | Swift 6 concurrency errors | **ios-concurrency** | Code error, not environment | | SwiftData migration errors | **ios-data** | Schema issue, not build environment | | "Sending 'self' risks data race" | **ios-concurrency** | Language error, not Xcode issue | | Type mismatch / compilation errors | Fix the code | These are code bugs | **ios-build is for environment mysteries**, not code errors: - ✅ "No such module" when code is correct - ✅ Simulator won't boot - ✅ Clean build fails, incremental works - ✅ Zombie xcodebuild processes - ❌ Swift concurrency warnings/errors - ❌ Database migration failures - ❌ Type checking errors in valid code ## Example Invocations User: "My build failed with a linker error" → Invoke: `/skill axiom-xcode-debugging` (environment-first diagnostic) User: "Builds are taking 10 minutes" → Invoke: `/skill axiom-build-performance` User: "SPM won't resolve dependencies" → Invoke: `spm-conflict-resolver` agent User: "Two packages require different versions of the same dependency" → Invoke: `spm-conflict-resolver` agent User: "Duplicate symbol linker error" → Invoke: `spm-conflict-resolver` agent User: "I need to prepare for App Store security review" → Invoke: `security-privacy-scanner` agent User: "Do I need a Privacy Manifest?" → Invoke: `security-privacy-scanner` agent User: "Are there hardcoded credentials in my code?" → Invoke: `security-privacy-scanner` agent User: "How do I migrate from ObservableObject to @Observable?" → Invoke: `modernization-helper` agent User: "Update my code to use modern SwiftUI patterns" → Invoke: `modernization-helper` agent User: "Should I still use @StateObject?" → Invoke: `modernization-helper` agent User: "A beta tester said my app crashed" → Invoke: `/skill axiom-testflight-triage` User: "I see crashes in App Store Connect but don't know how to investigate" → Invoke: `/skill axiom-testflight-triage` User: "My crash logs aren't symbolicated" → Invoke: `/skill axiom-testflight-triage` User: "I need to review TestFlight feedback" → Invoke: `/skill axiom-testflight-triage` User: "How do I find crashes in App Store Connect?" → Invoke: `/skill axiom-app-store-connect-ref` User: "Where's the crash-free users metric in ASC?" → Invoke: `/skill axiom-app-store-connect-ref` User: "How do I export crash data from App Store Connect?" → Invoke: `/skill axiom-app-store-connect-ref` User: "Analyze this crash log" [pastes .ips content] → Invoke: `crash-analyzer` agent or `/axiom:analyze-crash` User: "Parse this .ips file: ~/Library/Logs/DiagnosticReports/MyApp.ips" → Invoke: `crash-analyzer` agent or `/axiom:analyze-crash` User: "Why did my app crash? Here's the report..." → Invoke: `crash-analyzer` agent or `/axiom:analyze-crash` User: "How do I set up MetricKit to collect crash data?" → Invoke: `/skill axiom-metrickit-ref` User: "How do I parse MXDiagnosticPayload?" → Invoke: `/skill axiom-metrickit-ref` User: "What's in MXCallStackTree and how do I decode it?" → Invoke: `/skill axiom-metrickit-ref` User: "My app hangs sometimes" → Invoke: `/skill axiom-hang-diagnostics` User: "The main thread is blocked and UI is unresponsive" → Invoke: `/skill axiom-hang-diagnostics` User: "Xcode Organizer shows hang diagnostics for my app" → Invoke: `/skill axiom-hang-diagnostics` User: "My app was killed by watchdog during launch" → Invoke: `/skill axiom-hang-diagnostics` User: "I have a crash report and need to reproduce it in the debugger" → Invoke: `/skill axiom-lldb` User: "How do I set breakpoints to catch this crash?" → Invoke: `/skill axiom-lldb` User: "My build is failing with BUILD FAILED but no error details" → Invoke: `build-fixer` agent or `/axiom:fix-build` User: "Build sometimes succeeds, sometimes fails" → Invoke: `build-fixer` agent or `/axiom:fix-build` User: "How can I speed up my Xcode build times?" → Invoke: `build-optimizer` agent or `/axiom:optimize-build` User: "No signing certificate found when I try to build" → Invoke: `/skill axiom-code-signing-diag` User: "errSecInternalComponent in my GitHub Actions CI" → Invoke: `/skill axiom-code-signing-diag` User: "How do I set up code signing for GitHub Actions?" → Invoke: `/skill axiom-code-signing` User: "What is my app printing to the console?" → Invoke: `/skill axiom-xclog-ref` or `/axiom:console` User: "I need to see the simulator console output" → Invoke: `/skill axiom-xclog-ref` or `/axiom:console` User: "The app fails silently, no error in the UI" → Invoke: `/skill axiom-xclog-ref` or `/axiom:console` --- Source attribution: CharlesWiltgen Original project: https://github.com/CharlesWiltgen/Axiom/blob/a66a3c0b44011011fed256c49954ba3c77075a1e/.claude-plugin/plugins/axiom/skills/axiom-ios-build/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2025 Charles Wiltgen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: CharlesWiltgen Original project: https://github.com/CharlesWiltgen/Axiom/blob/a66a3c0b44011011fed256c49954ba3c77075a1e/.claude-plugin/plugins/axiom/skills/axiom-ios-build/SKILL.md Attribution basis: Recovered original package and original project license at a pinned revision Fields of work: Development & Engineering Roles: Backend Developer, Mobile Developer, QA / Test Engineer Specialties: Backend, Mobile Tools: Cocoapods, Xcode, Swift Package Manager Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 493a856edb2e64fbc7dee2bb7beca55c0f05ee975ed452c5dc30ebd3c0e26326 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.