--- id: CharlesWiltgen/Axiom/axiom-watchos version: "70eb74c3" license: MIT install: manual updated: 2026-07-27 --- # axiom-watchos — axiom-watchos guides you through complete watchOS development—from app architecture and independent apps to Watch Connectivity, complications, Smart Stack widgets, controls, and background task management. It routes you to specialized skills for design patterns, device diagnostics, and migrations while clarifying when to reach for cross-platform resources like SwiftUI or HealthKit. Publisher: CharlesWiltgen · Stars: 1095 · Updated: 2026-07-27 Install (manual): `git clone https://github.com/CharlesWiltgen/Axiom` ## SKILL.md # watchOS Development **You MUST use this skill for ANY watchOS-specific development including app structure, independent apps, Watch Connectivity, complications and Smart Stack widgets, controls, Live Activities on watch, background tasks, and ClockKit migration.** > **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. > > Homed in another suite: `axiom-build/skills/modernization-helper.md`. > > Agents that need Bash — builds, tests, simulators, crash symbolication — stay Claude Code-only; there is no inline equivalent for those. ## Quick Reference | Symptom / Task | Reference | |----------------|-----------| | App structure, independent apps, watchOS 26 submission requirements | See `skills/platform-basics.md` | | watchOS HIG, glanceable UX, navigation model | See `skills/design-for-watchos.md` | | Smart Stack widgets, complications, ClockKit→WidgetKit, RelevanceKit | See `skills/smart-stack-and-complications.md` | | Controls on watch surfaces, Live Activities on watch | See `skills/controls-and-live-activities.md` | | Watch Connectivity (WCSession), paired-device data transfer, Family Setup | See `skills/watch-connectivity.md` | | Xcode won't install/launch/attach to a Watch; Watch missing or `unavailable` in Device Hub / devicectl | See `skills/watch-device-diag.md` | | Background tasks, freshness scheduling, TN3135 networking limits | See `skills/background-and-networking.md` | | BGTaskScheduler migration, deprecated WK background scheduling `OS27` | See `skills/background-and-networking.md` | | Foundation Models / Private Cloud Compute on the watch `OS27` | See `skills/platform-basics.md` | | WatchKit→SwiftUI migration, ClockKit→WidgetKit migration | See `skills/modernization.md` | ## Cross-Suite Routes These topics overlap with watchOS development but live in separate suites: #### SwiftUI (shared iOS/watchOS/macOS) - View state, data flow, @Observable → See axiom-swiftui - Navigation basics (NavigationStack) → See axiom-swiftui - Layout, animations → See axiom-swiftui #### Design - General HIG, Liquid Glass, SF Symbols, typography → See axiom-design #### Accessibility - General VoiceOver, Dynamic Type, WCAG → See axiom-accessibility - watchOS-specific (VoiceOver rotor on Digital Crown, AssistiveTouch, Double Tap) → See axiom-accessibility (`skills/watchos-a11y.md`) #### Health and workouts - HealthKit, `HKWorkoutSession`, `HKLiveWorkoutBuilder`, WorkoutKit → See axiom-health - Workout recovery, multi-device coordination → See axiom-health (`skills/workouts.md`) #### iOS-side widgets and App Intents - iOS/iPadOS widgets, configuration intents, App Intents → See axiom-integration - Live Activities on iPhone (initiation + ActivityKit) → See axiom-integration #### Concurrency - Swift 6 concurrency, actors, Sendable → See axiom-concurrency #### New-on-watch frameworks (27 releases) - Foundation Models depth (sessions, @Generable, tools, PCC) → See axiom-ai; watch scoping is in `skills/platform-basics.md` - Vision framework (new on watchOS 27) → See axiom-vision - NowPlaying / MusicUnderstanding (new on watchOS 27) → See axiom-media ## Conflict Resolution **axiom-watchos vs axiom-swiftui**: When building a watchOS SwiftUI app: 1. **Use axiom-watchos** for watch-specific patterns: glanceable UI, constrained navigation, Digital Crown focus, Smart Stack placement 2. **Use axiom-swiftui** for cross-platform SwiftUI: state management, layout primitives, animations 3. **Both may apply**: A watchOS NavigationStack with complications needs axiom-watchos for complication surfaces and axiom-swiftui for NavigationStack basics **axiom-watchos vs axiom-integration**: For widgets and Live Activities: 1. **Use axiom-watchos** for watch complications, Smart Stack placement, watch-side Live Activity presentation, RelevanceKit 2. **Use axiom-integration** for iOS/iPadOS widgets, core ActivityKit API, App Intents **watch-device-diag vs watch-connectivity**: Two independent connections fail in ways that look identical. Decide which before writing any code: 1. **Use watch-device-diag** for the Mac/Xcode → Watch link (CoreDevice): install, launch, LLDB attach, a Watch that is missing or `unavailable` 2. **Use watch-connectivity** for the iPhone app ↔ watchOS app link (`WCSession`): transfer-API choice, delivery semantics, background-task completion 3. **When unsure, start with watch-device-diag.** Run the app without the debugger attached — if it behaves correctly, the fault is the tunnel and no `WCSession` change will help. Redesigning `WCSession` to compensate for a broken debugger tunnel is the most expensive mistake in watchOS work 4. **`isReachable == false` is not a transport failure** — it is the expected value across ordinary lifecycle transitions and routes to watch-connectivity, not here **axiom-watchos vs axiom-health**: For workouts on Apple Watch: 1. **Use axiom-watchos** for watch-specific presentation: Always On display, Smart Stack placement, background mode coordination 2. **Use axiom-health** for `HKWorkoutSession` lifecycle, `HKLiveWorkoutBuilder`, recovery, multi-device mirroring ## Decision Tree ```dot digraph watchos { start [label="watchOS development task" shape=ellipse]; what [label="What area?" shape=diamond]; start -> what; what -> "skills/platform-basics.md" [label="app structure, independent apps, submission"]; what -> "skills/design-for-watchos.md" [label="watch HIG, glanceable UX"]; what -> "skills/smart-stack-and-complications.md" [label="complications, Smart Stack, RelevanceKit"]; what -> "skills/controls-and-live-activities.md" [label="controls, watch Live Activities"]; what -> "skills/watch-connectivity.md" [label="WCSession, paired-device transfer"]; what -> "skills/watch-device-diag.md" [label="Xcode can't reach the Watch"]; what -> "skills/background-and-networking.md" [label="background tasks, BGTaskScheduler, networking limits"]; what -> "skills/platform-basics.md" [label="Foundation Models / PCC on watch"]; what -> "skills/modernization.md" [label="WatchKit/ClockKit migration"]; what -> "axiom-health" [label="workouts, HealthKit, WorkoutKit"]; what -> "axiom-swiftui" [label="general SwiftUI patterns"]; what -> "axiom-accessibility" [label="VoiceOver rotor, AssistiveTouch"]; what -> "axiom-integration" [label="iOS-side widgets, App Intents"]; } ``` ## Resources **WWDC**: 2021-10003, 2022-10133, 2023-10138, 2023-10029, 2023-10309, 2024-10098, 2024-10157, 2024-10205, 2025-334 **Docs**: /watchos-apps/building_a_watchos_app, /watchos-apps/creating-independent-watchos-apps, /watchconnectivity, /widgetkit/creating-accessory-widgets-and-watch-complications, /widgetkit/converting-a-clockkit-app, /relevancekit, /technotes/tn3135-low-level-networking-on-watchos, /technotes/tn3157-updating-your-watchos-project-for-swiftui-and-widgetkit **Skills**: axiom-swiftui, axiom-design, axiom-accessibility, axiom-health, axiom-integration, axiom-concurrency, axiom-ai, axiom-vision, axiom-media [View on SkillFed](https://skillfed.io/CharlesWiltgen/Axiom/axiom-watchos) · [View on GitHub](https://github.com/CharlesWiltgen/Axiom)