Create watchOS Version

Analyzes existing Apple platform projects and creates detailed, phased implementation plans for watchOS apps that are elegant, top-tier experiences—not naive skins of the parent app.

Workflow

1. Project Discovery - Analyze project structure, patterns, architecture
2. Feature Mapping - Identify watchOS-suitable features and priorities
3. API Compatibility - Search web for current watchOS API availability
4. Architecture Planning - Design watchOS-specific architecture
5. Plan Generation - Create phased plan with warnings and alternatives
6. User Review - Present plan for approval before implementation

Phase 1: Project Discovery

Run the bundled analyzer first — it reports architecture, dependencies, existing targets, and watchOS-incompatible frameworks as JSON:

python3 scripts/analyze_project.py <project_path>

Use its watchos_incompatible list to seed Phase 3. If the script fails or the project layout is unusual, fall back to scanning manually for:

├── App Architecture (SwiftUI, UIKit, AppKit, hybrid)
├── Data Layer (Core Data, SwiftData, Realm, custom)
├── Networking (URLSession, Alamofire, custom)
├── State Management (ObservableObject, TCA, Redux-like)
├── Navigation (NavigationStack, Coordinator)
├── Shared Frameworks (SPM packages, shared targets)
├── Assets (colors, images, SF Symbols)
├── Existing Watch Target (if any)
└── Minimum iOS Version (affects watchOS targeting)

Key files: *.xcodeproj, Package.swift, Info.plist, App entry points, ViewModels, Models.

Phase 2: Feature Mapping

Glanceable (High Priority): Status displays, counters, progress, recent items, quick stats

Quick Actions (High Priority): Single-tap toggles, shortcuts, haptic confirmations

Complications/Widgets (Critical): Map data to WidgetKit families—accessoryCircular, accessoryRectangular, accessoryInline, accessoryCorner. Consider Smart Stack relevance.

Background: HealthKit integration, background refresh, Watch Connectivity sync

Defer/Exclude: Complex data entry, long-form content, sustained screen time features

Phase 3: API Compatibility

CRITICAL: Always search web for current watchOS docs before finalizing. APIs change frequently.

Search: [FrameworkName] watchOS availability site:developer.apple.com

Quick Reference

Available: SwiftUI, SwiftData (10+), WidgetKit (9+), HealthKit, WorkoutKit, CoreLocation (limited), WatchConnectivity, CloudKit, CoreMotion, AVFoundation (audio), CoreBluetooth, Combine, Swift Concurrency

Unavailable/Limited: UIKit, WebKit, MapKit (limited), CoreImage (limited), ARKit, RealityKit, StoreKit (limited), Background URLSession (limited)

See references/api-compatibility.md for detailed compatibility matrix.

Phase 4: Architecture

Version Targeting

Each iOS release has a paired watchOS release. Derive the target from the project's existing minimum iOS version rather than assuming the latest:

iOS 16+ → watchOS 9+  (WidgetKit complications)
iOS 17+ → watchOS 10+ (SwiftData, Smart Stack)
iOS 18+ → watchOS 11+ (Live Activities on Watch)

This mapping is a starting point, not an authority — newer OS versions ship every year. Confirm the current pairing and any newer capabilities on developer.apple.com before committing to a deployment target.

Structure

Shared/
├── Models/           # Pure Swift, shared via target membership
├── Services/         # Platform-agnostic logic
└── Utilities/

WatchApp/
├── App.swift
├── Views/
├── ViewModels/
├── Complications/
└── WatchConnectivity/

Design Principles

1. Glanceability - Visible within 2 seconds
2. Minimal Interaction - 1-3 taps max
3. Context Awareness - Time, location, activity
4. Battery Conscious - Efficient refresh, TimelineSchedule
5. Haptic Feedback - Confirm actions appropriately

SwiftUI Gotchas

• Avoid nested TabViews (memory leaks)
• Use TimelineSchedule for efficient metric updates
• Check isLuminanceReduced to reduce work when dimmed
• Don't use data-driven high-frequency UI refreshes

Phase 5: Plan Generation

Use template in references/plan-template.md to generate:

1. Executive Summary
2. ⚠️ API Compatibility Warnings table
3. Phased implementation tasks
4. Testing checklist

Phase 6: User Review

Present plan and ask for approval before implementing:

"I've analyzed your project and created a watchOS plan. Before proceeding:
1. API Warnings: [N] APIs unavailable—alternatives documented.
2. Recommended Features: [list] prioritized for Watch.
3. Scope: [N] phases.

Proceed with implementation, or adjust the plan?"

Do not implement until user approves.

Best Practices Reference

Watch Connectivity

guard WCSession.default.activationState == .activated else { return }
// sendMessage: immediate, requires reachability
// transferUserInfo: queued, guaranteed
// transferCurrentComplicationUserInfo: complication priority

Complications

// Use appropriate reload policy
Timeline(entries: entries, policy: .after(nextUpdateDate))
// Use .never for static complications

Battery Efficiency

• Timeline-based over active refresh
• Check isLuminanceReduced
• Batch Watch Connectivity transfers
• Significant location change vs continuous updates