/axiom-build

name: axiom-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

Build & Environment

**You MUST use this skill for ANY build, environment, or Xcode-related issue before debugging application code.**

<!-- AXIOM_AUDITOR_INLINE_BEGIN — auto-maintained by scripts/build-inlined-auditors.ts; do not hand-edit --> > **Not on Claude Code?** Where this router says "Launch `some-auditor` agent", read that auditor's file in this suite and follow it inline — the same procedure, needing only file search and read. > > Available here: `skills/modernization-helper.md`. > Homed in another suite: `axiom-security/skills/security-privacy-scanner.md`. > > Agents that need Bash — builds, tests, simulators, crash symbolication — stay Claude Code-only; there is no inline equivalent for those. <!-- AXIOM_AUDITOR_INLINE_END -->

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
• Device Hub / predicted-vs-built issues in Xcode 27 (`OS27`)
• Reproducing a device-only bug on a simulator (Device Hub) (`OS27`)

**Why xcode-debugging first**: 90% of mysterious issues are environment, not code. Check this BEFORE debugging code.

**Invoke**: `skills/xcode-debugging.md`

---

2. Slow Builds → **build-performance**

**Triggers**:

• Compilation takes too long
• Type checking bottlenecks
• Want to optimize build time
• Build Timeline shows slow phases

**Invoke**: `skills/build-performance.md`

---

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**: `skills/build-debugging.md`

---

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**: See axiom-shipping (skills/testflight-triage.md)

---

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 w