watchos-development

watchOS Development

Guidance for building watchOS apps that behave the way the platform expects: independent by default, SwiftUI-first, glanceable, and resilient to a paired iPhone that may not be nearby.

Agent behavior contract (follow these rules)

1. Determine the project's shape before proposing changes: watch-only, paired companion, or independent+companion. Default recommendation for new work is independent + companion — it's the only shape that degrades gracefully on Family Setup watches and unpaired watches.
2. Never let Watch Connectivity become the primary data path. It is an opportunistic optimization on top of a network/CloudKit fetch, not a substitute for one — see references/watch-connectivity.md.
3. Default new app entry points to the SwiftUI App protocol (@main, WindowGroup, NavigationStack) — see references/platform-basics.md for entry-point structure and references/design-for-watchos.md for how these primitives handle watchOS-specific navigation. Only add a WKApplicationDelegate via @WKApplicationDelegateAdaptor for the specific callbacks SwiftUI doesn't expose (workout recovery, Now Playing, extended runtime, remote-notification registration) — never as a precaution.
4. Route all networking through URLSession. Low-level networking (NWConnection, raw sockets, URLSessionStreamTask/WebSocketTask) is blocked by the OS on watchOS except for audio-streaming, VoIP+CallKit, and tvOS-pairing apps — see references/background-and-networking.md.
5. Every WKRefreshBackgroundTask (including WKWatchConnectivityRefreshBackgroundTask and WKURLSessionRefreshBackgroundTask) must reach setTaskCompletedWithSnapshot(_:) exactly once. Missing this drains the background budget and produces a delayed SIGKILL that looks unrelated to its cause.
6. When migrating ClockKit complications to WidgetKit, insist on migrating every complication in the same release. The instant one WidgetKit complication is offered, the system stops calling ClockKit entirely — a partial migration silently breaks the rest on every user's device.
7. For SwiftUI content, only cover what's genuinely different on watchOS (navigation primitives, toolbar placement, Always On, containerBackground). General SwiftUI state management, layout, and animation belong to the swiftui-expert-skill and swiftui-liquid-glass skills — don't re-explain those here.
8. For workouts and HealthKit specifics (HKWorkoutSession, HKLiveWorkoutBuilder, recovery), defer to the healthkit skill; this skill only covers how workout data affects Smart Stack suggestions.