/axiom-build

name: axiom-build
description: Use when ANY iOS or macOS build fails, a crash log needs diagnosing, a test run crashes, Xcode misbehaves, or an environment issue blocks work before code is the suspect. Covers build failures, dependency conflicts, simulator diagnostics.
license: MIT

Build & Environment

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

**Bundled tools on Claude Code:** if `command -v <tool>` finds nothing (hooks off or `--bare`), use `<plugin-root>/tools/<tool>` in place of the bare name; `<plugin-root>` is two levels above this skill's `Base directory for this skill:` path.

<!-- AXIOM_AUDITOR_INLINE_BEGIN — rewritten for Codex by scripts/build-codex.ts; do not hand-edit --> > **Auditors are skills here.** Where this router says "Launch `some-auditor` agent", invoke the > matching Codex skill instead — same procedure, no Claude Code agent required. > > Available: `axiom-modernize`, `axiom-scan-security-privacy`. > > The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run. <!-- AXIOM_AUDITOR_INLINE_END -->

Capture Build and Test Diagnostics

Before the next necessary build or test, resolve `tools/axbuild` under the **actual loaded package** in Claude Code (`command -v axbuild`; if that finds nothing, `tools/axbuild` two levels above the `Base directory for this skill:` path of a loaded Axiom skill) or Codex (`<plugin-root>/tools/`), or discover an executable on PATH in Pi. Check executable permission and run its absolute path with `--help`; assign that observed path to `AXBUILD`. Never infer an installation path from an example.

Cursor and MCP distributions do not bundle axbuild and expose no axbuild MCP wrapper. Use the **saved-log fallback** below when a verified shell helper is unavailable.

Before **every** Xcode invocation, run `pgrep -lx xcodebuild; echo "pgrep exit=$?"`: exit 1 means none are running, 0 lists them, and any other exit means the inventory failed. Investigate existing builds; process count and age do not establish zombie status. Never terminate unrelated processes. When interrupted or timed out, axbuild also stops build scripts and other processes descended from its build that Xcode moved into separate process groups, found by parentage when cleanup begins and on each cleanup pass. It reports `cleanup-incomplete` for any such descendant it could not stop or verify (another user's, unreadable, or being debugged). Jobs that had already left the build's process tree, such as daemons or launchd-started tools, are neither stopped nor reported. Inspect ownership before stopping anything it lists. Discover the actual scheme and destination before executing:

"$AXBUILD" xcodebuild -scheme "$SCHEME" -destination "$DESTINATION" build
"$AXBUILD" swift test --package-path "$PACKAGE"

Preserve caller flags, working directory, environment, test selection, coverage and explicit artifact paths. The wrapper adds absent diagnostic defaults; it never cleans caches or automatically rebuilds. Do not pipe a build through another command.

Inspect `command` (native outcome) and `collection` (evidence completeness) separately. Native success can accompany partial collection. The default JSON is bounded to 8,000 UTF-8 bytes; inspect `omissions` and read `artifacts.report` relative to the absolute `artifacts.run` directory for complete records and evaluated values. The startup stderr JSON identifies the run directory before completion. Use diagnostic locations and values rather than rebuilding to redisplay output.

The retained log is the primary compiler source; test results and validated Swift Testing events supplement it. A null failed-test count means uncertainty, not zero. Preserve result bundles for attachment export, coverage, console logs and deeper inspection. Native informational commands pass their output through.

**Saved-log fallback:** redirect the necessary native command's stdout/stderr to a unique file, let it finish, record its exit status and inspect that saved file. An xcresult build summary is not equivalent to the compiler log. Read an existing log before considering another build. If a build's output ends in a truncation marker, or before xcodebuild's closing `** BUILD … **` or `** TEST … **` line, read the saved log or report instead of rebuilding.

<!-- end of shared section; source: skills/axiom-build/SKILL.md, copies regenerated by npm run build:shared -->

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 link