/axiom-concurrency

name: axiom-concurrency
description: Use when writing ANY async code, actors, or threads in an Apple-platform app, or seeing ANY concurrency error. Covers Swift 6 concurrency, @MainActor, Sendable, data races, async/await patterns.
license: MIT

Concurrency

**You MUST use this skill for ANY concurrency, async/await, threading, or Swift 6 concurrency work.**

**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-audit-concurrency`. > > The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run. <!-- AXIOM_AUDITOR_INLINE_END -->

Quick Reference

| Symptom / Task | Reference | |----------------|-----------| | async/await patterns, @MainActor, actors | See `skills/swift-concurrency.md` | | Data race errors, Sendable conformance | See `skills/swift-concurrency.md` | | Swift 6 migration, @concurrent attribute | See `skills/swift-concurrency.md` | | Actor definition, reentrancy, global actors | See `skills/swift-concurrency-ref.md` | | Task/TaskGroup/cancellation API | See `skills/swift-concurrency-ref.md` | | AsyncStream, continuations | See `skills/swift-concurrency-ref.md` | | DispatchQueue → actor migration | See `skills/swift-concurrency-ref.md` | | Mutex (iOS 18+), OSAllocatedUnfairLock | See `skills/synchronization.md` | | Atomic types, lock vs actor decision | See `skills/synchronization.md` | | MainActor.assumeIsolated | See `skills/assume-isolated.md` | | @preconcurrency protocol conformances | See `skills/assume-isolated.md` | | Legacy delegate callbacks | See `skills/assume-isolated.md` | | Warning-free build crashes with `_dispatch_assert_queue_fail` | See `skills/isolation-inheritance-diag.md` | | Crash signature `_swift_task_checkIsolatedSwift` | See `skills/isolation-inheritance-diag.md` | | Core Data `context.perform` runtime crash inside @MainActor class | See `skills/isolation-inheritance-diag.md` | | Combine `.map`/`.sink` crash from receive(on:) placement | See `skills/isolation-inheritance-diag.md` | | Delegate method crash from isolation inheritance (CLLocationManager, NSDocument, AVAudioPlayerDelegate, WKNavigationDelegate, PHPhotoLibraryChangeObserver) | See `skills/isolation-inheritance-diag.md` | | PhotoKit `performChanges` block traps on PhotoKit's queue | See `skills/isolation-inheritance-diag.md` | | Actor reentrancy / stale state across await | See `skills/isolation-inheritance-diag.md` | | Swift Concurrency Instruments template | See `skills/concurrency-profiling.md` | | Actor contention diagnosis | See `skills/concurrency-profiling.md` | | Thread pool exhaustion | See `skills/concurrency-profiling.md` |

Decision Tree

digraph concurrency {
    start [label="Concurrency task" shape=ellipse];
    what [label="What do you need?" shape=diamond];

    start -> what;
    what -> "skills/swift-concurrency.md" [label="async/await, actors,\nSendable, data races,\nSwift 6 migration"];
    what -> "skills/swift-concurrency-ref.md" [label="API syntax lookup\n(TaskGroup, AsyncStream,\ncontinuations, migration)"];
    what -> "skills/synchronization.md" [label="Mutex, locks,\natomic types"];
    what -> "skills/assume-isolated.md" [label="assumeIsolated,\n@preconcurrency"];
    what -> "skills/isolation-inheritance-diag.md" [label="warning-free build crashes\n_dispatch_assert_queue_fail\n_swift_task_checkIsolatedSwift"];
    what -> "skills/concurrency-profiling.md" [label="profile async perf,\nactor contention"];
}

1. Data races / actor isolation / @MainActor / Sendable / Swift 6 migration? → `skills/swift-concurrency.md` 1a. Need specific API syntax (actor definition, TaskGroup, AsyncStream, continuations)? → `skills/swift-concurrency-ref.md` 1b. NotificationCenter observer, `userInfo` casting, or Sendable errors unpacking a notification? → `skills/swift-concurrency-ref.md` (Typed Notifications — `MainActorMessage`/`AsyncMessage`, iOS 26+) 2. Writing async/await code? → `skills/swift-concurrency.md` 3. assumeIsolated / @preconcurrency? → `skills/assume-isolated.md` 3a. Warning-free Swift 6 build that crashes in production with `_dispatch_assert_queue_fail` or `_swift_task_checkIsolatedSwift`? → `skills/isolation-inheritance-diag.md` 4. Mutex / lock / synchronization? → `skills/synchronization.md` 5. Profile async performance / actor contention? → `skills/concurrency-profiling.md` 6. Value type / ARC / generic optimization? → See axiom-performance (skills/swift-performance.md) 7. borrowing / consuming / ~Copyable? → See axiom-swift (skills/ownership-conventions.md) 8. Combine / @Published / AnyCancellable / reactive streams? → See axiom-uikit (skills/combine-patterns.md) 9. Want automated concurrency scan? → concurrency-auditor (Agent)

Concurrency in practice

• HealthKit queries with Swift Concurrency (canonical bridging example) → See axiom-health (skills/queries.md)

Conflict Resolution

**concurrency vs axiom-performance**: When app freezes or feels slow: 1. **Try concurrency FIRST** — Main thread blocking is the #1 cause of UI freezes. Check for synchronous work on @MainActor before profiling. 2. **Only use axiom-performance** if concurrency fixes don't help — Profile after ruling out obvious blocking. 3. **To pin a specific freeze to app code**, see the Hang Window Workflow in axiom-performance (skills/hang-diagnostics.md) — re-scope `xcprof analyze` to the hang window with `--start-ms/--end-ms --user-binary` to surface the app-owned frame on the main thread.

**concurrency vs axiom-build**: When seeing Swif