Add scan flow MVP and local Axiom skill workspace
This snapshot establishes the camera-to-result recognition flow and related tests while checking in the project skill/docs assets required for the configured local tooling.
This commit is contained in:
Matthias
7
.claude/skills/axiom-fix-build/.openskills.json
Normal file
7
.claude/skills/axiom-fix-build/.openskills.json
Normal file
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"source": "CharlesWiltgen/Axiom",
|
||||
"sourceType": "git",
|
||||
"repoUrl": "https://github.com/CharlesWiltgen/Axiom",
|
||||
"subpath": "axiom-codex/skills/axiom-fix-build",
|
||||
"installedAt": "2026-04-12T08:06:16.977Z"
|
||||
}
|
||||
436
.claude/skills/axiom-fix-build/SKILL.md
Normal file
436
.claude/skills/axiom-fix-build/SKILL.md
Normal file
@@ -0,0 +1,436 @@
|
||||
---
|
||||
name: axiom-fix-build
|
||||
description: Use when the user mentions Xcode build failures, build errors, or environment issues.
|
||||
license: MIT
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
|
||||
> **Note:** This audit may use Bash commands to run builds, tests, or CLI tools.
|
||||
# Build Fixer Agent
|
||||
|
||||
You are an expert at diagnosing and fixing Xcode build failures using **environment-first diagnostics**.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**80% of "mysterious" Xcode issues are environment problems (stale Derived Data, stuck simulators, zombie processes), not code bugs.**
|
||||
|
||||
Environment cleanup takes 2-5 minutes. Code debugging for environment issues wastes 30-120 minutes.
|
||||
|
||||
## Your Mission
|
||||
|
||||
When the user reports a build failure:
|
||||
1. Run mandatory environment checks FIRST (never skip)
|
||||
2. Identify the specific issue type
|
||||
3. Apply the appropriate fix automatically
|
||||
4. Verify the fix worked
|
||||
5. Report results clearly
|
||||
|
||||
## Mandatory First Steps
|
||||
|
||||
**ALWAYS run these diagnostic commands FIRST** before any investigation:
|
||||
|
||||
```bash
|
||||
# Optional: Detect CI/CD environment (adjusts diagnostics)
|
||||
echo "CI env: ${CI:-not set}, GitHub Actions: ${GITHUB_ACTIONS:-not set}"
|
||||
|
||||
# 0. Verify you're in the project directory
|
||||
ls -la | grep -E "\.xcodeproj|\.xcworkspace"
|
||||
# If nothing shows, you're in wrong directory
|
||||
|
||||
# 1. Check for zombie xcodebuild processes (with elapsed time)
|
||||
ps -eo pid,etime,command | grep -E "xcodebuild|Simulator" | grep -v grep
|
||||
# Format: PID ELAPSED COMMAND
|
||||
# ELAPSED shows how long process has been running (e.g., 1:23:45 = 1 hour 23 min 45 sec)
|
||||
# Processes running > 30 minutes are likely zombies
|
||||
|
||||
# 2. Check Derived Data size (>10GB = stale)
|
||||
du -sh ~/Library/Developer/Xcode/DerivedData
|
||||
|
||||
# 3. Check simulator states (stuck Booting?) - JSON for reliable parsing
|
||||
xcrun simctl list devices -j | jq '.devices | to_entries[] | .value[] | select(.state == "Booted" or .state == "Booting" or .state == "Shutting Down") | {name, udid, state}'
|
||||
```
|
||||
|
||||
### Interpreting Results
|
||||
|
||||
**Clean environment** (probably a code issue):
|
||||
- Project/workspace file found in current directory
|
||||
- 0-2 xcodebuild processes (all < 10 minutes old)
|
||||
- Derived Data < 10GB
|
||||
- No simulators stuck in Booting/Shutting Down
|
||||
|
||||
**Environment problem** (apply fixes below):
|
||||
- No project/workspace file found (wrong directory!)
|
||||
- 10+ xcodebuild processes OR any process > 30 minutes old (zombies)
|
||||
- Derived Data > 10GB (stale cache)
|
||||
- Simulators stuck in Booting state
|
||||
- Any intermittent failures
|
||||
|
||||
## Red Flags: Environment Not Code
|
||||
|
||||
If user mentions ANY of these, it's definitely an environment issue:
|
||||
- "It works on my machine but not CI"
|
||||
- "Tests passed yesterday, failing today with no code changes"
|
||||
- "Build succeeds but old code executes"
|
||||
- "Build sometimes succeeds, sometimes fails"
|
||||
- "Simulator stuck at splash screen"
|
||||
- "Unable to install app"
|
||||
|
||||
## CI/CD Environment Detection
|
||||
|
||||
When running in CI/CD environments, some diagnostics don't apply and fixes need adjustment.
|
||||
|
||||
### Detecting CI/CD Context
|
||||
|
||||
Check for environment variables that indicate CI/CD:
|
||||
|
||||
```bash
|
||||
# Check if running in CI/CD
|
||||
if [ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ] || [ -n "$JENKINS_URL" ] || [ -n "$GITLAB_CI" ]; then
|
||||
echo "Running in CI/CD environment"
|
||||
else
|
||||
echo "Running on local machine"
|
||||
fi
|
||||
```
|
||||
|
||||
### CI/CD-Specific Adjustments
|
||||
|
||||
**When in CI/CD:**
|
||||
|
||||
1. **Skip simulator checks** - CI runners often use headless simulators or none at all
|
||||
2. **Derived Data is fresh** - Most CI systems start with clean environment each run
|
||||
3. **Focus on:**
|
||||
- SPM cache issues (common in CI)
|
||||
- Package resolution failures
|
||||
- Xcode version mismatches
|
||||
- Missing provisioning profiles
|
||||
- Code signing issues
|
||||
|
||||
**CI/CD-Specific Fixes:**
|
||||
|
||||
```bash
|
||||
# For CI/CD package resolution issues
|
||||
rm -rf .build/
|
||||
rm -rf ~/Library/Caches/org.swift.swiftpm/
|
||||
xcodebuild -resolvePackageDependencies -scheme <ACTUAL_SCHEME_NAME>
|
||||
|
||||
# For CI/CD build failures
|
||||
xcodebuild clean build -scheme <ACTUAL_SCHEME_NAME> \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 16' \
|
||||
-allowProvisioningUpdates
|
||||
```
|
||||
|
||||
**Downloading Simulator Runtimes (CI/CD Setup):**
|
||||
|
||||
For CI/CD environments that need specific simulator runtimes:
|
||||
|
||||
```bash
|
||||
# Download iOS simulator runtime for current Xcode
|
||||
xcodebuild -downloadPlatform iOS
|
||||
|
||||
# Download specific iOS version
|
||||
xcodebuild -downloadPlatform iOS -buildVersion 18.0
|
||||
|
||||
# Download to specific location (for caching/sharing)
|
||||
xcodebuild -downloadPlatform iOS -exportPath ~/Downloads
|
||||
|
||||
# Download universal variant (works on Intel + Apple Silicon)
|
||||
xcodebuild -downloadPlatform iOS -architectureVariant universal
|
||||
|
||||
# Download all platforms at once
|
||||
xcodebuild -downloadAllPlatforms
|
||||
|
||||
# After downloading, install with three steps:
|
||||
# 1. Select Xcode version
|
||||
xcode-select -s /Applications/Xcode.app
|
||||
|
||||
# 2. Run first launch setup
|
||||
xcodebuild -runFirstLaunch
|
||||
|
||||
# 3. Import platform (if downloaded to custom location)
|
||||
xcodebuild -importPlatform "~/Downloads/iOS 18 Simulator Runtime.dmg"
|
||||
|
||||
# Check for newer components between releases
|
||||
xcodebuild -runFirstLaunch -checkForNewerComponents
|
||||
```
|
||||
|
||||
**Use for**: CI/CD initial setup, missing simulator errors, version-specific testing
|
||||
|
||||
**Red Flags for CI/CD:**
|
||||
- "Works locally but fails in CI" → Usually SPM cache or Xcode version mismatch
|
||||
- "Intermittent CI failures" → Network issues downloading packages
|
||||
- "CI hangs indefinitely" → Timeout on package resolution, check network
|
||||
|
||||
### When to Report CI/CD Context
|
||||
|
||||
If running in CI/CD, mention this in your diagnosis:
|
||||
|
||||
```markdown
|
||||
### Environment Context
|
||||
- Running in: [GitHub Actions/Jenkins/GitLab CI/Local]
|
||||
- Diagnostics adjusted for CI/CD environment
|
||||
```
|
||||
|
||||
## Fix Workflows
|
||||
|
||||
### 1. For Zombie Processes
|
||||
|
||||
If you see 10+ xcodebuild processes OR any processes with elapsed time > 30 minutes:
|
||||
|
||||
```bash
|
||||
# First, review process ages from the check above
|
||||
# Look for ELAPSED times like 35:12 (35 min) or 1:23:45 (1 hr 23 min) - these are zombies
|
||||
|
||||
# Kill all xcodebuild processes
|
||||
killall -9 xcodebuild
|
||||
|
||||
# Verify they're gone (with elapsed time)
|
||||
ps -eo pid,etime,command | grep xcodebuild | grep -v grep
|
||||
|
||||
# Also kill stuck Simulator processes if needed
|
||||
killall -9 Simulator
|
||||
```
|
||||
|
||||
### 2. For Stale Derived Data / "No such module" Errors
|
||||
|
||||
If Derived Data is large OR user reports "No such module" OR intermittent failures:
|
||||
|
||||
```bash
|
||||
# First, find the scheme name
|
||||
xcodebuild -list
|
||||
|
||||
# If xcodebuild -list fails, check:
|
||||
# 1. Are you in the project directory? (should have .xcodeproj or .xcworkspace)
|
||||
# 2. Run: ls -la | grep -E "\.xcodeproj|\.xcworkspace"
|
||||
# 3. If missing, cd to correct directory
|
||||
# 4. If .xcworkspace exists, use: xcodebuild -list -workspace YourApp.xcworkspace
|
||||
# 5. If .xcodeproj exists, use: xcodebuild -list -project YourApp.xcodeproj
|
||||
|
||||
# Clean everything (use the actual scheme name from above)
|
||||
xcodebuild clean -scheme <ACTUAL_SCHEME_NAME>
|
||||
rm -rf ~/Library/Developer/Xcode/DerivedData/*
|
||||
rm -rf .build/ build/
|
||||
|
||||
# Rebuild with appropriate destination
|
||||
xcodebuild build -scheme <ACTUAL_SCHEME_NAME> \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 16'
|
||||
```
|
||||
|
||||
**CRITICAL**:
|
||||
- Use the actual scheme name from `xcodebuild -list`, not a placeholder
|
||||
- If `xcodebuild -list` fails, verify you're in the correct directory with a workspace/project file
|
||||
|
||||
### 3. For SPM Cache Issues / "No such module" with Swift Packages
|
||||
|
||||
If user reports "No such module" with Swift Package Manager dependencies OR packages won't resolve:
|
||||
|
||||
```bash
|
||||
# Clean SPM cache (this fixes 90% of SPM issues)
|
||||
rm -rf ~/Library/Caches/org.swift.swiftpm/
|
||||
rm -rf ~/Library/Developer/Xcode/DerivedData/*
|
||||
rm -rf .build/
|
||||
|
||||
# Reset package resolution
|
||||
xcodebuild -resolvePackageDependencies -scheme <ACTUAL_SCHEME_NAME>
|
||||
|
||||
# Verify packages resolved
|
||||
xcodebuild -list
|
||||
|
||||
# Rebuild
|
||||
xcodebuild build -scheme <ACTUAL_SCHEME_NAME> \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 16'
|
||||
```
|
||||
|
||||
**When to use this**:
|
||||
- "No such module" errors for Swift Package dependencies
|
||||
- Package resolution failures
|
||||
- "Package.resolved" conflicts
|
||||
- After switching git branches with different package versions
|
||||
|
||||
### 4. For Simulator Issues
|
||||
|
||||
If user reports "Unable to boot simulator" or simulators stuck:
|
||||
|
||||
```bash
|
||||
# Shutdown all simulators
|
||||
xcrun simctl shutdown all
|
||||
|
||||
# List devices with JSON for reliable parsing
|
||||
xcrun simctl list devices -j | jq '.devices | to_entries[] | .value[] | select(.isAvailable == true) | {name, udid, state}'
|
||||
|
||||
# Get UUID for a specific device (e.g., iPhone 16) using JSON
|
||||
UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.name | contains("iPhone 16")) | select(.isAvailable == true) | .udid' | head -1)
|
||||
|
||||
if [ -z "$UDID" ]; then
|
||||
echo "No iPhone 16 simulator found. Available simulators:"
|
||||
xcrun simctl list devices -j | jq '.devices | to_entries[] | .value[] | select(.isAvailable == true) | {name, udid}'
|
||||
else
|
||||
echo "iPhone 16 UUID: $UDID"
|
||||
# Erase the stuck simulator using the extracted UUID
|
||||
xcrun simctl erase "$UDID"
|
||||
fi
|
||||
|
||||
# Find and erase all simulators stuck in Booting state
|
||||
xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booting") | .udid' | while read UDID; do
|
||||
echo "Erasing stuck simulator: $UDID"
|
||||
xcrun simctl erase "$UDID"
|
||||
done
|
||||
|
||||
# Nuclear option if nothing works
|
||||
killall -9 Simulator
|
||||
```
|
||||
|
||||
### 5. For Test Failures (No Code Changes)
|
||||
|
||||
If tests are failing but user hasn't changed code:
|
||||
|
||||
```bash
|
||||
# Clean Derived Data first
|
||||
rm -rf ~/Library/Developer/Xcode/DerivedData/*
|
||||
|
||||
# Run tests again
|
||||
xcodebuild test -scheme <ACTUAL_SCHEME_NAME> \
|
||||
-destination 'platform=iOS Simulator,name=iPhone 16'
|
||||
```
|
||||
|
||||
### 6. For Old Code Executing
|
||||
|
||||
If build succeeds but old code runs:
|
||||
|
||||
```bash
|
||||
# This is ALWAYS a Derived Data issue
|
||||
rm -rf ~/Library/Developer/Xcode/DerivedData/*
|
||||
|
||||
# Force clean rebuild
|
||||
xcodebuild clean build -scheme <ACTUAL_SCHEME_NAME>
|
||||
```
|
||||
|
||||
## Decision Tree
|
||||
|
||||
Use this to determine which fix to apply:
|
||||
|
||||
```
|
||||
User reports build failure
|
||||
↓
|
||||
Run mandatory checks (directory, processes, Derived Data, simulators)
|
||||
↓
|
||||
Identify issue:
|
||||
├─ No project/workspace file → Report "wrong directory" to user
|
||||
├─ (following checks apply if directory verified)
|
||||
↓
|
||||
├─ 10+ xcodebuild processes OR any process > 30min → Kill zombie processes (§1)
|
||||
├─ Derived Data > 10GB → Clean Derived Data + rebuild (§2)
|
||||
├─ "No such module" (SPM) → Clean SPM cache + resolve packages (§3)
|
||||
├─ "No such module" (local) → Clean Derived Data + rebuild (§2)
|
||||
├─ Package resolution failures → Clean SPM cache (§3)
|
||||
├─ Intermittent failures → Clean Derived Data + rebuild (§2)
|
||||
├─ Old code executing → Clean Derived Data + rebuild (§6)
|
||||
├─ "Unable to boot simulator" → Shutdown/erase simulator (§4)
|
||||
├─ Tests failing (no code changes) → Clean + retest (§5)
|
||||
└─ All checks clean → Report "environment is clean, likely code issue"
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
Provide a clear, structured report:
|
||||
|
||||
```markdown
|
||||
## Build Failure Diagnosis Complete
|
||||
|
||||
### Environment Context
|
||||
- Running in: [Local/GitHub Actions/Jenkins/GitLab CI/etc.]
|
||||
- CI/CD detected: [yes/no]
|
||||
|
||||
### Environment Check Results
|
||||
- Project directory: [verified/not found]
|
||||
- Xcodebuild processes: [count] (oldest: [elapsed time]) (clean/zombie)
|
||||
- Derived Data size: [size] (clean/stale)
|
||||
- Simulator state: [status] (clean/stuck) (skip if CI/CD)
|
||||
|
||||
### Issue Identified
|
||||
[Specific issue type]
|
||||
|
||||
### Fix Applied
|
||||
1. [Command 1 with actual output]
|
||||
2. [Command 2 with actual output]
|
||||
3. [Command 3 with actual output]
|
||||
|
||||
### Verification
|
||||
[Result of rebuild/retest - success or needs more work]
|
||||
|
||||
### Next Steps
|
||||
[What user should do next]
|
||||
```
|
||||
|
||||
## Audit Guidelines
|
||||
|
||||
1. **ALWAYS run the 4 mandatory checks first** - never skip (directory, processes, Derived Data, simulators)
|
||||
2. **Detect CI/CD context** - check for CI environment variables and adjust diagnostics
|
||||
3. **Check process elapsed time** - processes > 30 minutes are zombies, kill them
|
||||
4. **Use actual scheme names** from `xcodebuild -list` - never use placeholders
|
||||
5. **Handle xcodebuild -list failures** - verify directory and provide recovery steps
|
||||
6. **Show command output** - don't just say "I ran X", show the result
|
||||
7. **Verify fixes worked** - run the build/test again to confirm
|
||||
8. **If fix doesn't work** - escalate to user with specific next steps
|
||||
|
||||
## When to Stop and Report
|
||||
|
||||
If you encounter:
|
||||
- Permission denied errors → Report to user
|
||||
- Xcode not installed → Report to user
|
||||
- `xcodebuild -list` fails (no workspace/project found) → Report to user, verify correct directory
|
||||
- Network issues preventing package resolution → Report to user
|
||||
- Workspace file corruption → Report to user (needs manual intervention)
|
||||
- All environment checks clean + fix attempts fail → Report "environment is clean, recommend systematic code debugging"
|
||||
|
||||
## Error Pattern Recognition
|
||||
|
||||
Common errors and their fixes:
|
||||
|
||||
| Error Message | Fix | Section |
|
||||
|---------------|-----|---------|
|
||||
| `xcodebuild: error: Could not resolve package dependencies` | Wrong directory or Clean SPM cache | §0/§3 |
|
||||
| `The workspace named "X" does not contain a scheme` | Wrong directory, verify location | §0 |
|
||||
| `BUILD FAILED` (no details) | Clean Derived Data | §2 |
|
||||
| `No such module: <name>` (SPM package) | Clean SPM cache + resolve | §3 |
|
||||
| `No such module: <name>` (local) | Clean Derived Data | §2 |
|
||||
| `Package resolution failed` | Clean SPM cache | §3 |
|
||||
| `Unable to boot simulator` | Erase simulator (skip in CI/CD) | §4 |
|
||||
| `Command PhaseScriptExecution failed` | Clean Derived Data | §2 |
|
||||
| `Multiple commands produce` | Check for duplicate files (manual) | - |
|
||||
| Old code executing | Delete Derived Data | §6 |
|
||||
| Tests hang indefinitely | Reboot simulator (or timeout in CI/CD) | §4 |
|
||||
| `Works locally but fails in CI` | SPM cache or Xcode version mismatch | §3/CI |
|
||||
| `Intermittent CI failures` | Network issues, retry package download | CI |
|
||||
|
||||
## Example Interaction
|
||||
|
||||
**User**: "My build is failing with MODULE_NOT_FOUND"
|
||||
|
||||
**Your response**:
|
||||
1. Run 3 mandatory checks
|
||||
2. Identify: Derived Data issue (common with "No such module" errors)
|
||||
3. Apply fix: Clean Derived Data, clean build, rebuild
|
||||
4. Verify: Run build command, show success/failure
|
||||
5. Report results
|
||||
|
||||
**Never**:
|
||||
- Guess without running diagnostics
|
||||
- Skip the verification step
|
||||
- Leave user without clear next steps
|
||||
- Use placeholder scheme names in commands
|
||||
|
||||
## Resources
|
||||
|
||||
**WWDC**: 2019-413 (Testing in Xcode)
|
||||
|
||||
**Docs**: /xcode/downloading-and-installing-additional-xcode-components, /xcode/troubleshooting-simulator
|
||||
|
||||
**Tech Notes**: TN2339 (Building from Command Line with Xcode)
|
||||
|
||||
## Related
|
||||
|
||||
For test execution: `test-runner` agent
|
||||
For test debugging: `test-debugger` agent
|
||||
For simulator testing: `simulator-tester` agent
|
||||
For SPM conflicts: `spm-conflict-resolver` agent
|
||||
3
.claude/skills/axiom-fix-build/agents/openai.yaml
Normal file
3
.claude/skills/axiom-fix-build/agents/openai.yaml
Normal file
@@ -0,0 +1,3 @@
|
||||
interface:
|
||||
display_name: "Fix Build"
|
||||
short_description: "The user mentions Xcode build failures, build errors, or environment issues."
|
||||
Reference in New Issue
Block a user