buildanything 1.7.1 → 1.8.0

package/protocols/ios-frameworks-map.md

@@ -0,0 +1,323 @@
+# iOS Frameworks Capability Map
+
+_**Reference file** — agents READ this on demand when hitting a "user wants X → which Apple framework?" question. **NOT injected into agent prompts** (323 lines would waste ~400k tokens across a build). The orchestrator cites this file by path; agents open it, grep for their capability, extract the 1-2 relevant rows. Authoritative source for framework selection. When in doubt, consult apple-docs-mcp to confirm current API status._
+
+## Purpose
+
+This is a **framework-selection index**, not a best-practices guide. It answers: "the user described capability X, which Apple framework should I import?" The rule is: **prefer Apple's native framework over custom code or third-party libraries whenever one exists.**
+
+---
+
+## 1. Capability Index (user intent → framework)
+
+### Health & Fitness
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Log workouts, steps, heart rate, sleep | HealthKit | `com.apple.developer.healthkit` | — |
+| Start/control workout sessions, build workout plans | WorkoutKit (iOS 17+) | HealthKit | — |
+| Pull clinical records (labs, allergies, meds) | HealthKit ClinicalHealth | `health-records` | — |
+| Mindful minutes / state of mind | HealthKit (iOS 17+) | HealthKit | — |
+
+### Calendar & Reminders
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Create/read calendar events | EventKit | `NSCalendarsFullAccessUsageDescription` | Deprecated: `NSCalendarsUsageDescription` (iOS 17+ splits read/write) |
+| Pre-built event editor UI | EventKitUI | Calendar | — |
+| Create/read reminders | EventKit | `NSRemindersFullAccessUsageDescription` | — |
+
+### Photos & Media
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Pick photos/videos from library | PhotosUI (`PhotosPicker`) | — (no permission prompt needed for picker) | Deprecated: `UIImagePickerController` |
+| Full library access, albums, assets | PhotoKit | `NSPhotoLibraryUsageDescription` | — |
+| Camera capture, audio/video record | AVFoundation | `NSCameraUsageDescription`, `NSMicrophoneUsageDescription` | — |
+| Play video with controls | AVKit (`VideoPlayer`) | — | Deprecated: `MPMoviePlayerController` |
+| Play user's music, now-playing info | MediaPlayer | `NSAppleMusicUsageDescription` | — |
+| Apple Music catalog, playback | MusicKit | MusicKit capability | — |
+| Song ID (Shazam) | ShazamKit | Microphone | — |
+| Classify sounds on-device | SoundAnalysis | Microphone | — |
+| Speech-to-text | Speech | `NSSpeechRecognitionUsageDescription` | — |
+| View/annotate/render PDF | PDFKit | — | — |
+| Preview documents inline | QuickLook | — | — |
+| Thumbnails for any file type | QuickLookThumbnailing | — | — |
+| Image filters, Core Image | CoreImage | — | — |
+| Low-level audio engine/effects | AVAudioEngine | — | Prefer over `AudioToolbox` for new code |
+
+### Maps & Location
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Show a map, annotations, overlays | MapKit (SwiftUI `Map` iOS 17+) | — | Deprecated for SwiftUI: `MKMapView` wrapper |
+| User location / geofencing | CoreLocation | `NSLocationWhenInUseUsageDescription`, `NSLocationAlwaysAndWhenInUseUsageDescription` | — |
+| Weather forecast / historical | WeatherKit | WeatherKit capability | — |
+| Directions, search, POI, lookAround | MapKit | — | — |
+
+### Identity & Auth
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Sign in with Apple, passkeys, OAuth web flow | AuthenticationServices | `com.apple.developer.applesignin` | Deprecated: custom `WKWebView` OAuth |
+| Face ID / Touch ID / passcode | LocalAuthentication | `NSFaceIDUsageDescription` | — |
+| Keychain storage | Security | — | Avoid: `UserDefaults` for secrets |
+| Crypto primitives (AES, ChaCha, SHA, EC) | CryptoKit | — | Deprecated: `CommonCrypto` in new Swift code |
+
+### Payments & Commerce
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| In-app purchases, subscriptions | StoreKit 2 | In-App Purchase capability | Deprecated: StoreKit 1 (`SKPayment*`) |
+| Apple Pay, Wallet passes | PassKit | `com.apple.developer.in-app-payments`, merchant IDs | — |
+
+### Communication & Notifications
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Local + remote push notifications | UserNotifications | `aps-environment` (remote) | Deprecated: `UILocalNotification`, `UIUserNotification*` |
+| VoIP push | PushKit + CallKit | VoIP capability | — |
+| System call UI, CallKit directory | CallKit | — | — |
+| iMessage app extensions, stickers | Messages | — | — |
+| Peer-to-peer device networking | MultipeerConnectivity | Local network | — |
+| Bonjour / local network discovery | Network | `NSLocalNetworkUsageDescription` | Deprecated: `NetService` |
+| Email / SMS compose sheets | MessageUI | — | — |
+
+### AR / Vision / ML
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| World-tracking AR, plane detection | ARKit | Camera | — |
+| 3D rendering for AR | RealityKit | Camera | Deprecated in AR: `SceneKit+ARKit` combo |
+| Room scanning (LiDAR) | RoomPlan | Camera | — |
+| Text recognition, face/body detect, barcode | Vision | — | — |
+| Document scanner, data-scanner UI | VisionKit | Camera | — |
+| Run custom ML models | CoreML | — | — |
+| Train models on-device | CreateML | — | — |
+| On-device LLM (text gen, summarize) | **FoundationModels (iOS 26+)** | — | iOS 26 only; check availability |
+| Visual Intelligence interactions | **Visual Intelligence (iOS 26+)** | — | iOS 26 only |
+| Natural-language tokenization, tagging | NaturalLanguage | — | — |
+| Live Text / Data scanner | VisionKit `DataScannerViewController` | Camera | — |
+
+### Contacts & People
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Read/write contacts | Contacts | `NSContactsUsageDescription` | Deprecated: `AddressBook` |
+| Contact picker UI | ContactsUI | Contacts (picker-only: not required) | — |
+
+### System & Device
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Background fetch, background processing | BackgroundTasks | `BGTaskSchedulerPermittedIdentifiers` | Deprecated: `performFetchWithCompletionHandler` |
+| Background asset download at install | BackgroundAssets | Background Assets capability | — |
+| VPN / content filter / packet tunnel | NetworkExtension | NetworkExtension capability | — |
+| Device attestation / anti-abuse | DeviceCheck / AppAttest | — | — |
+| IDFA / tracking consent | AppTrackingTransparency | `NSUserTrackingUsageDescription` | — |
+| File Provider extension (cloud drive) | FileProvider | File Provider capability | — |
+| Share sheet / activity items | UIKit `UIActivityViewController` (SwiftUI `ShareLink`) | — | Prefer SwiftUI `ShareLink` |
+| Drag & drop, pasteboard | UniformTypeIdentifiers + SwiftUI `Transferable` | — | Deprecated: `kUTType*` constants |
+
+### Home & IoT
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| HomeKit accessories | HomeKit | `NSHomeKitUsageDescription` | — |
+| Matter accessory pairing | MatterSupport | Matter capability | — |
+| BLE peripherals & centrals | CoreBluetooth | `NSBluetoothAlwaysUsageDescription` | — |
+| Ultra-wideband ranging | NearbyInteraction | — | — |
+| Car key | CarKey | CarKey entitlement | — |
+| CarPlay apps / audio / nav | CarPlay | CarPlay entitlement (Apple approval) | — |
+
+### Wearables & Companions
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| iPhone ↔ Apple Watch messaging | WatchConnectivity | — | — |
+| Watch workouts | WorkoutKit + HealthKit | HealthKit | — |
+
+### Intents, Widgets & Automation
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Siri / Shortcuts / App Intents | AppIntents | — | Deprecated: `SiriKit` custom intents (keep only for domains AppIntents doesn't cover) |
+| Home/Lock-Screen widgets | WidgetKit | App Groups (usually) | — |
+| Live Activities / Dynamic Island | ActivityKit | `NSSupportsLiveActivities` Info.plist | — |
+| Control Center widgets (iOS 18+) | WidgetKit `ControlWidget` | — | — |
+| System-style alarms (iOS 26+) | **AlarmKit** | — | iOS 26 only |
+
+### Web & Content
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| In-app Safari tab (SFSafariVC) | SafariServices | — | — |
+| Full web view / JS bridge | WebKit | — | Deprecated: `UIWebView` |
+| SwiftUI-native web view (iOS 26+) | SwiftUI `WebView` | — | iOS 26 only |
+| Rich URL preview cards | LinkPresentation | — | — |
+
+### Graphics & Games
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| 2D game engine | SpriteKit | — | — |
+| 3D scene graph | SceneKit | — | (Maintenance mode; prefer RealityKit for new 3D) |
+| GPU rendering | MetalKit / Metal | — | Deprecated: OpenGL ES |
+| 3D model I/O (USDZ) | ModelIO | — | — |
+| Game Center, leaderboards, matches | GameKit | Game Center capability | — |
+| Controller input | GameController | — | — |
+
+### Accessibility & Input
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| VoiceOver/Switch Control labels | Accessibility (SwiftUI modifiers) | — | — |
+| Dictation / speech recognition | Speech | Speech recognition | — |
+| Hand/pencil input | PencilKit | — | — |
+
+### Persistence
+
+| User intent | Framework(s) | Entitlement needed | Deprecation note |
+|---|---|---|---|
+| Model persistence (new projects) | SwiftData | — | — |
+| Model persistence (legacy) | CoreData | — | Prefer SwiftData for new work |
+| Tiny prefs (≤ a few KB) | Foundation `UserDefaults` | — | Do not use for secrets or large blobs |
+| iCloud key-value | Foundation `NSUbiquitousKeyValueStore` | iCloud Key-Value | — |
+| iCloud Drive documents | CloudKit + UIDocument | iCloud (CloudKit) | — |
+| CloudKit sync | CloudKit | iCloud (CloudKit) | — |
+
+---
+
+## 2. Selection Rules (multi-choice disambiguation)
+
+When multiple frameworks can solve a problem, pick the most modern:
+
+- **Photos:** PhotosUI `PhotosPicker` (iOS 16+) > PhotoKit `PHPickerViewController` (iOS 14+) > `UIImagePickerController` (deprecated).
+- **Auth:** AuthenticationServices (Sign in with Apple, passkeys, OAuth) > manual `WKWebView` OAuth flows.
+- **Audio:** `AVAudioEngine` (modern graph) > `AVAudioPlayer` (simple file playback) > `AudioToolbox` (low-level CoreAudio).
+- **Notifications:** UserNotifications (local + remote, iOS 10+) > legacy `UIUserNotification*` (removed).
+- **Maps:** SwiftUI `Map` (iOS 17+) > `MKMapView` via `UIViewRepresentable`.
+- **On-device AI:** FoundationModels (iOS 26+, text) > CoreML (custom models) > MLX (low-level experimental).
+- **Persistence:** SwiftData > Core Data (legacy only) > `UserDefaults` (tiny prefs only).
+- **3D:** RealityKit (AR + general 3D) > SceneKit (maintenance mode).
+- **Web view:** SwiftUI `WebView` (iOS 26+) > `WKWebView` via `UIViewRepresentable` > `SFSafariViewController` (if you just need a browser tab).
+- **Background work:** BackgroundTasks (`BGAppRefreshTask`, `BGProcessingTask`) > deprecated background-fetch.
+- **Networking:** `URLSession` + async/await > `Network` framework (sockets, Bonjour) > third-party HTTP clients.
+- **JSON:** `Codable` > `JSONSerialization`.
+- **Share:** SwiftUI `ShareLink` > `UIActivityViewController` wrapper.
+- **Crypto:** CryptoKit > `CommonCrypto`.
+
+---
+
+## 3. Framework Combinations (common pairings)
+
+- **Push notifications** = UserNotifications + APNs + `aps-environment` entitlement.
+- **VoIP** = CallKit + PushKit + VoIP background mode + CallKit entitlement.
+- **Sign in with Apple** = AuthenticationServices + "Sign in with Apple" capability.
+- **Widgets** = WidgetKit + App Groups + shared SwiftData container.
+- **Live Activities** = ActivityKit + UserNotifications push + `NSSupportsLiveActivities` in Info.plist.
+- **App Intents in widgets** = AppIntents + WidgetKit + shared target membership.
+- **HealthKit workouts** = HealthKit + WorkoutKit + HealthKit entitlement + `NSHealthShareUsageDescription` + `NSHealthUpdateUsageDescription`.
+- **ARKit 3D scene** = ARKit + RealityKit + `NSCameraUsageDescription`.
+- **Document scanning** = VisionKit `VNDocumentCameraViewController` + `NSCameraUsageDescription`.
+- **Barcode / text scanner** = VisionKit `DataScannerViewController` + Camera.
+- **Passkeys** = AuthenticationServices + Associated Domains (`webcredentials:`).
+- **Universal Links** = Associated Domains (`applinks:`) + `onOpenURL` / `NSUserActivity`.
+- **CloudKit-synced SwiftData** = SwiftData + iCloud (CloudKit) capability + follow CloudKit-compatible model rules (no `.unique`, all relationships optional).
+- **Matter pairing** = MatterSupport + HomeKit + Matter entitlement.
+- **Apple Pay** = PassKit + Merchant ID + in-app-payments entitlement.
+
+---
+
+## 4. Entitlement Mapping (feeds ios-entitlements-generator)
+
+| Framework | Entitlement key | Info.plist keys | Setup notes |
+|---|---|---|---|
+| HealthKit | `com.apple.developer.healthkit` | `NSHealthShareUsageDescription`, `NSHealthUpdateUsageDescription` | Add access types to entitlement plist |
+| HomeKit | — | `NSHomeKitUsageDescription` | HomeKit capability on target |
+| EventKit | — | `NSCalendarsFullAccessUsageDescription`, `NSRemindersFullAccessUsageDescription` | iOS 17+ split access model |
+| Contacts | — | `NSContactsUsageDescription` | — |
+| Photos | — | `NSPhotoLibraryUsageDescription`, `NSPhotoLibraryAddUsageDescription` | Not needed for `PhotosPicker` |
+| Camera | — | `NSCameraUsageDescription` | AVFoundation, Vision, ARKit, VisionKit |
+| Microphone | — | `NSMicrophoneUsageDescription` | AVFoundation, Speech, ShazamKit |
+| Speech | — | `NSSpeechRecognitionUsageDescription` | — |
+| Face ID | — | `NSFaceIDUsageDescription` | LocalAuthentication |
+| CoreLocation | — | `NSLocationWhenInUseUsageDescription`, `NSLocationAlwaysAndWhenInUseUsageDescription`, `NSLocationTemporaryUsageDescriptionDictionary` | — |
+| Bluetooth | — | `NSBluetoothAlwaysUsageDescription` | — |
+| Local Network | — | `NSLocalNetworkUsageDescription`, `NSBonjourServices` | Multipeer, Bonjour |
+| Music | — | `NSAppleMusicUsageDescription` | MediaPlayer, MusicKit |
+| Tracking (IDFA) | — | `NSUserTrackingUsageDescription` | AppTrackingTransparency |
+| Sign in with Apple | `com.apple.developer.applesignin` | — | — |
+| Push (remote) | `aps-environment` | — | `development` / `production` |
+| Associated Domains | `com.apple.developer.associated-domains` | — | `applinks:`, `webcredentials:`, `activitycontinuation:` |
+| App Groups | `com.apple.security.application-groups` | — | Share data with widgets/extensions |
+| iCloud (CloudKit) | `com.apple.developer.icloud-services`, `com.apple.developer.icloud-container-identifiers` | — | CloudKit + iCloud Drive |
+| Keychain Sharing | `keychain-access-groups` | — | Share keychain items across apps |
+| In-App Purchase | `com.apple.developer.in-app-payments` (Apple Pay) | — | IAP capability on target for StoreKit |
+| HealthKit Clinical | `com.apple.developer.healthkit.access` | — | Array of clinical record types |
+| WeatherKit | `com.apple.developer.weatherkit` | — | Register service in developer portal |
+| MusicKit | `com.apple.developer.musickit` | — | — |
+| CarPlay | `com.apple.developer.carplay-*` | — | Requires Apple entitlement approval |
+| CarKey | `com.apple.developer.car-key` | — | — |
+| NetworkExtension | `com.apple.developer.networking.networkextension` | — | Packet tunnel, content filter, DNS proxy |
+| BackgroundAssets | `com.apple.developer.background-assets` | — | — |
+| Matter | `com.apple.developer.matter.allow-setup-payload` | — | — |
+| DriverKit / USB / HID | various | — | Specialized — usually not needed in consumer apps |
+| Live Activities | — | `NSSupportsLiveActivities`, `NSSupportsLiveActivitiesFrequentUpdates` | Info.plist only |
+| Background modes | `com.apple.developer.background-modes` (via Xcode UI) | — | audio, location, voip, fetch, processing, remote-notification |
+
+---
+
+## 5. Deprecation Flags (avoid in new code)
+
+- `UIImagePickerController` → use PhotosUI `PhotosPicker`.
+- `UIUserNotification*` / `UILocalNotification` → use UserNotifications.
+- Core Data in new projects → use SwiftData.
+- `UIAlertView` / `UIActionSheet` → use SwiftUI `alert` / `confirmationDialog` (or `UIAlertController` in UIKit).
+- `MKMapView` wrapped in SwiftUI → use SwiftUI `Map` (iOS 17+).
+- `ObservableObject` / `@Published` / `@StateObject` → use `@Observable` macro.
+- `DispatchQueue.main.async` for UI → use `@MainActor` + async/await.
+- `Timer` / GCD timers → use async `Task.sleep` / `AsyncTimerSequence`.
+- `DateFormatter` / `NumberFormatter` → use `FormatStyle` (`.formatted(...)`).
+- `replacingOccurrences(of:with:)` → `.replacing("a", with: "b")`.
+- `foregroundColor` → `foregroundStyle`.
+- `cornerRadius` → `clipShape(.rect(cornerRadius:))`.
+- `NavigationView` → `NavigationStack`.
+- `tabItem` on TabView → new `Tab` API (iOS 18+).
+- `UIWebView` → `WKWebView` (or SwiftUI `WebView` iOS 26+).
+- `AddressBook` → Contacts.
+- `CommonCrypto` in Swift → CryptoKit.
+- `SKPayment*` (StoreKit 1) → StoreKit 2.
+- `kUTType*` → UniformTypeIdentifiers `UTType`.
+- `NetService` → Network framework.
+- `UIScreen.main.bounds` for layout → SwiftUI geometry APIs.
+- `performFetchWithCompletionHandler` → BackgroundTasks.
+- SiriKit custom intents → AppIntents (keep SiriKit only for domains AppIntents doesn't cover: messaging, payments, ride-booking, car-commands).
+- OpenGL ES → Metal.
+
+---
+
+## 6. The Reach-for-the-Kit Rule (enforcement)
+
+When the user describes a capability that an Apple framework already solves, you **MUST** use the Apple framework. Custom implementations of these are anti-patterns:
+
+- Rolling your own photo picker instead of `PhotosPicker`.
+- Rolling your own calendar event storage instead of EventKit.
+- Rolling your own notification scheduler instead of UserNotifications.
+- Rolling your own keychain wrapper instead of the Security framework.
+- Rolling your own biometric auth instead of LocalAuthentication.
+- Rolling your own OAuth / sign-in flow instead of AuthenticationServices.
+- Rolling your own map tiles instead of MapKit.
+- Scraping weather APIs instead of WeatherKit.
+- Rolling your own workout tracker instead of HealthKit + WorkoutKit.
+- Rolling your own barcode scanner instead of Vision / VisionKit.
+- Rolling your own PDF renderer instead of PDFKit.
+- Rolling your own share sheet instead of `ShareLink` / `UIActivityViewController`.
+- Rolling your own crypto primitives instead of CryptoKit.
+- Rolling your own in-app purchase layer instead of StoreKit 2.
+
+If unsure whether a framework covers a use case, query `apple-docs-mcp` **before** writing custom code.
+
+---
+
+_See also: `ios-context.md` (Senior iOS Engineer persona + §2 Core Stack rules)._

package/protocols/ios-phase-branches.md

@@ -0,0 +1,162 @@
+# iOS Phase Branches
+
+_Loaded into orchestrator session context when `project_type=ios`. Contains per-phase iOS-specific instructions. Mode-agnostic phase scaffolding lives in `commands/build.md`._
+
+## iOS Mode Tool Stack
+
+When `project_type=ios` is set in `docs/plans/.build-state.md`, use this stack in place of the web defaults:
+
+- Project creation: Xcode New Project dialog (user-guided — no Tuist, no XcodeGen)
+- Structure changes: XcodeBuildMCP primary / user-assisted Add Files fallback
+- Swift code edits: direct file writes (Claude via Edit/Write tools)
+- Build, diagnostics, SwiftUI Preview capture: XcodeBuildMCP
+- E2E tests: Maestro (`.yaml` flows — agent-friendly)
+- OAuth / web-views on simulator: agent-browser `-p ios` (Mobile Safari only, not native UI)
+- Design references: Apple HIG + SF Symbols + Liquid Glass (iOS 26+)
+- Code signing / TestFlight / App Store: fastlane (optional — Phase 7 only)
+
+**Architecture default for iOS:** vanilla SwiftUI + `@Observable`. TCA is opt-in only (user explicitly requests it, or existing TCA codebase detected). Do not propose TCA by default.
+
+All iOS implementation agents inherit the `protocols/ios-context.md` persona (Senior iOS Engineer) — pass it into every agent prompt in Phases 4, 5, 6, 7 when `project_type=ios`.
+
+## Phase 0 additions (iOS-specific)
+
+When Phase 0 classifier sets `project_type=ios`:
+- Load `protocols/ios-context.md` into orchestrator session context — it holds the Senior iOS Engineer persona inherited by every iOS implementation agent (injected into agent prompts).
+- Reference `protocols/ios-frameworks-map.md` by **path only** — do NOT load its 323 lines into session context or inject into agent prompts. It is a lookup reference: agents `Read` it on-demand when they hit a "user wants X → which Apple framework?" question, grep for their capability, extract the 1-2 relevant rows. The orchestrator cites it by path when dispatching the architect, entitlements-generator, and impl agents; those agents open it themselves.
+- Use the iOS Mode Tool Stack above — not the web defaults.
+- Phase 3 skips `/design-system` (no web style guide). Phase 6 dispatches to iOS twins of `/verify` + `/ux-review` + `/fix`.
+- If greenfield (no `.xcodeproj` exists), **Phase -1 Bootstrap** runs before Phase 1.
+
+## Phase -1 — iOS Bootstrap (iOS-only, greenfield only)
+
+**Runs ONLY if** `project_type=ios` AND no `.xcodeproj` exists in the project root. Skip entirely for `project_type=web` OR when an Xcode project already exists.
+
+**Goal:** verify the iOS toolchain, create the Xcode project, wire MCP servers, install test tooling — so Phase 1 planning starts against a real, buildable Xcode project.
+
+### Step -1.1 — Environment Check
+
+Verify (or guide the user to install):
+- **Xcode 26.3+** (hard requirement — no fallback). If missing or older, direct user to Mac App Store update. Requires macOS 26 Tahoe + Apple Silicon.
+- **XcodeBuildMCP** server configured in Claude settings.
+- **apple-docs-mcp** server configured (for iOS 26 API lookups during architecture).
+- **Maestro CLI** (`brew install maestro`) for E2E tests.
+- **fastlane** — defer to Phase 7, do NOT install now (optional, ship-only).
+
+### Step -1.2 — Xcode Project Creation (user-guided)
+
+Dispatch the `ios-bootstrap` skill (or inline the prompt if the skill isn't available):
+
+Call the Agent tool — description: "iOS bootstrap" — mode: "bypassPermissions" — prompt: "Guide the user through creating a new Xcode project via Xcode's New Project dialog (File > New > Project > iOS App). Target: iOS 26.0+, Swift 6.2+, SwiftUI interface, SwiftData storage (if data persistence is in the design). Do NOT use Tuist or XcodeGen. After the user confirms project creation, verify: `.xcodeproj` exists, the project builds clean via XcodeBuildMCP, and the app launches on a simulator. Also create the canonical `maestro/` directory at the project root (for Phase 4 flow stubs + Phase 5 smoke tests) — no leading dot, committed to git. Report the project path and bundle identifier."
+
+### Step -1.3 — Bootstrap Verification
+
+Confirm all of: Xcode version OK, `.xcodeproj` exists, XcodeBuildMCP responds, apple-docs-mcp responds, Maestro installed, first build+launch on simulator succeeded. Log status to `docs/plans/.build-state.md` under `## iOS Bootstrap`. If any check fails, STOP and surface the blocker — do NOT proceed to Phase 1.
+
+**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format in `commands/build.md`.
+
+## Phase 1 — Plan (iOS additions)
+
+Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 1. Planning agent = `ios-swift-architect` (not the generic web planner). Market/tech-feasibility research agents must check App Store category landscape, TestFlight constraints, and iOS 26 API availability (via apple-docs-mcp) in addition to standard research.
+
+## Phase 2 — Architecture (iOS additions)
+
+Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 2. Architecture agents must select iOS 26 APIs via apple-docs-mcp (verify availability, deprecations, minimum OS). Replace "Backend architecture" / "Frontend architecture" with: (1) SwiftUI view hierarchy + navigation model, (2) SwiftData schema + CloudKit strategy, (3) Swift Concurrency / actor isolation plan, (4) iOS-specific security (Keychain, entitlements, ATS). Implementation blueprint lists Swift files + Xcode targets, not web modules.
+
+### Feature Flag Resolution (end of Phase 2)
+
+Before leaving Phase 2, resolve the `ios_features` flag block (schema in `protocols/ios-context.md` §iOS Feature Flag Schema) and WRITE it to `docs/plans/.build-state.md` under the `ios_features:` key. Determine each flag from the brainstorm + architecture outputs:
+
+- `widgets` — true if Home/Lock Screen widgets mentioned.
+- `liveActivities` — true if Live Activities / Dynamic Island mentioned.
+- `appIntents` — true if Siri / Shortcuts / App Intents mentioned.
+- `foundationModels` — true if on-device LLM / Foundation Models mentioned.
+- `storekit` — true if IAP / subscriptions mentioned.
+- `healthkit` — true if health / fitness data mentioned.
+- `push` — true if remote/local push notifications mentioned.
+- `cloudkit` — true if cross-device sync mentioned.
+- `siri` — true if Siri voice integration mentioned.
+- `location` — true if Maps / geolocation / geofencing mentioned.
+- `background` — true if background fetch / processing / BGTaskScheduler mentioned.
+- `cameraPhoto` — true if camera or photo picker mentioned.
+- `microphone` — true if audio recording / Speech mentioned.
+- `contacts` — true if Contacts framework mentioned.
+- `calendar` — true if EventKit / calendar / reminders mentioned.
+- `appleWatch` — true if watchOS companion mentioned.
+
+Resolution rule: keyword-match the brainstorm transcript + architecture doc; in autonomous mode default to `false` on ambiguous flags and log the assumption to `build-log.md`; in interactive mode confirm ambiguous flags with the user. These flags gate Phase 5 skill loading and Phase 4 entitlement generation.
+
+## Phase 3 — Design (iOS branch)
+
+Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 3. Do **NOT** build `/design-system` (web-only). Instead:
+
+- **Step 3.1 iOS** — agent-browser (`-p desktop`) harvests iOS UI references from **free** sources: screenlane.com (iOS screenshots), App Store web listings for top apps in the product category, Apple HIG pages, SF Symbols browser. No Mobbin (paid). Fallback: vibe-only design board if scraping blocked.
+- **Step 3.2 iOS** — synthesize an **iOS Design Board** (`docs/plans/ios-design-board.md`) grounded in Apple HIG + Liquid Glass (iOS 26+) + SF Symbols + the harvested references + the user's stated app vibe. Cover: typography (Dynamic Type scale), color (semantic + dark mode), spacing (HIG-compliant), navigation pattern (TabView / NavigationStack / sheets), iconography (SF Symbols).
+- **Skip Step 3.3** (Living Style Guide) — no web route.
+- **Step 3.4 iOS** — visual QA loop uses XcodeBuildMCP SwiftUI Preview captures (not Playwright screenshots). Exit criterion = user-approved pass/fail (not a 0-100 rubric). **Max 3 iterations** (tighter than web's 5). On stall: present captures + remaining issues to user for accept/reject decision.
+- Save final artifact to `docs/plans/ios-design-board.md` (Phase 4 gate reads this file instead of `visual-design-spec.md`).
+
+Phase 4 HARD-GATE: iOS mode requires `docs/plans/ios-design-board.md` to exist before Phase 4 starts. If missing, return to Phase 3.
+
+## Phase 4 — Foundation (iOS branch)
+
+Load phase-specific iOS skill bundle per `protocols/ios-context.md` §Phase 4.
+
+Dispatch `ios-entitlements-generator` (Info.plist + entitlements based on features: push, background, HealthKit, etc.) and `ios-info-plist-hardening` (ATS config, privacy usage strings, URL schemes).
+
+- **Step 4.1 (iOS):** Scaffolding is already done by Phase -1 Bootstrap. Instead, create the app target's folder structure (`Views/`, `Models/`, `Services/`, `Resources/`) via XcodeBuildMCP.
+- **Step 4.2 (iOS):** Implement iOS-native design tokens from `docs/plans/ios-design-board.md` (SwiftUI `Color` extensions, `Font` extensions, `ShapeStyle` tokens, spacing constants) — NOT web CSS.
+- **Step 4.2b (iOS):** Replace Playwright acceptance scaffolds with Maestro YAML flow stubs in `maestro/` directory.
+- **Step 4.3 (iOS):** Metric Loop on scaffold health — builds clean via XcodeBuildMCP, Swift Testing `@Test`s pass, structure matches architecture. Max 3 iterations.
+- **Step 4.4 (iOS):** Verification Gate via XcodeBuildMCP build + test. Do not proceed to Phase 5 until it passes.
+
+## Phase 5 — Build (iOS branch)
+
+Load full iOS skill bundle per `protocols/ios-context.md` §Phase 5. Every implementation agent inherits the `ios-context.md` Senior iOS Engineer persona. Bundle includes: `swiftui-pro`, `swift-concurrency`, `swiftdata-pro`, `swift-security-expert`, `swift-accessibility`.
+
+**Feature-flag gated skill loading** — before dispatching any gated skill, the orchestrator MUST read `ios_features` from `docs/plans/.build-state.md`. Load a gated skill only when its flag is `true`:
+- `widgets: true` → load `skills/ios/widgetkit/`
+- `liveActivities: true` → `skills/ios/activitykit/`
+- `appIntents: true` → `skills/ios/app-intents/`
+- `foundationModels: true` → `agents/ios-foundation-models-specialist.md`
+- `storekit: true` → `agents/ios-storekit-specialist.md`
+
+**Other Apple frameworks** (HealthKit, GameKit, ARKit, RealityKit, Vision, CoreML, MapKit, PhotoKit, WeatherKit, MusicKit, Contacts, EventKit, CallKit) — **available via iOS 26 SDK `import`**; agent uses `apple-docs-mcp` lookups + `ios-context.md` persona + `ios-entitlements-generator` for capability wiring. No dedicated mentor-skill yet — add one only if a specific framework becomes friction during dogfooding.
+
+### Step 5.1 — Implement (iOS)
+
+Call the Agent tool — description: "[task name]" — mode: "bypassPermissions" — prompt: "TASK: [task description + acceptance criteria]. HANDOFF — Architecture section: [paste]. Design section: [paste relevant section from `docs/plans/ios-design-board.md`]. Previous task output: [if relevant]. For UI tasks: consult `docs/plans/ios-design-board.md` for visual tokens + HIG patterns, and `skills/ios/swiftui-design-principles/` for the 10-rule polish checklist. Match the design board's tokens exactly. Implement fully with real Swift code, Swift Testing `@Test`s, and XcodeBuildMCP validation. Commit: 'feat: [task]'. Report what you built, files changed, and test results."
+
+Implementation agents edit Swift files directly and build/diagnose via XcodeBuildMCP. Set `[COMPLEXITY: S/M/L]` based on the task's Size from sprint-tasks.md.
+
+### Step 5.2 — Metric Loop (iOS)
+
+Metric loop uses XcodeBuildMCP SwiftUI Preview captures for UI verification (not agent-browser). Max 5 iterations.
+
+### Step 5.3b — Behavioral Smoke Test (iOS)
+
+Executes the task's **Maestro** flow from `maestro/` against a booted simulator (via XcodeBuildMCP `BuildAndRun` → `maestro test maestro/<flow>.yaml`) — NOT agent-browser or localhost. Evidence = Maestro run log + Preview/simulator screenshots. For OAuth/web-view flows on the simulator only, use agent-browser `-p ios`.
+
+## Phase 6 — Harden (iOS branch)
+
+Phase 6 does NOT run the web audit bundle. Instead, **dispatch to the three iOS twin commands in sequence**:
+
+1. `/buildanything:verify` (iOS twin — functional correctness, XcodeBuildMCP diagnostics, Maestro E2E)
+2. `/buildanything:ux-review` (iOS twin — HIG audit via SwiftUI Preview captures + Apple HIG checklist)
+3. `/buildanything:fix` (iOS twin — dispatches specialist iOS agents for each finding)
+
+Each twin owns its own scope and reviewer — they are NOT merged into a single loop. After all three twins complete, run **Step 6.4 Reality Check** (in `commands/build.md`) with iOS evidence (Maestro run logs, Preview captures, HIG findings).
+
+Skip Steps 6.1, 6.1b, 6.2, 6.2b, 6.2c (Playwright E2E), 6.2d (agent-browser dogfood), 6.2e (web fake-data patterns).
+
+## Phase 7 — Ship (iOS branch, optional)
+
+Ship pipeline is **optional** (simulator-only is a valid end-state — no Apple Developer account required).
+
+If the user opts to ship: run the iOS `asc-*` pipeline:
+- `asc-metadata-generator` (App Store Connect listing + keywords + description)
+- `asc-screenshot-generator` (generate App Store screenshots via XcodeBuildMCP at all required device sizes)
+- `asc-privacy-manifest` (PrivacyInfo.xcprivacy)
+- Then `fastlane` for code signing + TestFlight upload.
+
+This is SEPARATE from the web ship pipeline — do NOT run web README/deployment steps. Documentation = README with simulator run instructions + TestFlight invite link (if shipped). Skip Step 7.1 web docs and web deployment notes.

package/protocols/ios-preflight.md

@@ -0,0 +1,27 @@
+# iOS Preflight Protocol
+
+_Shared preflight steps for iOS-mode commands. Included by `/verify`, `/ux-review`, `/fix` iOS twins._
+
+## Preflight Checks
+
+Before running any iOS-branch command flow, verify:
+
+1. **`.xcodeproj` exists** in project root (use `ls *.xcodeproj` or equivalent). If not, HALT and prompt user to run `/buildanything:build` Phase -1 Bootstrap first.
+
+2. **XcodeBuildMCP reachable** — dispatch a simple `xcodebuild -version` or MCP health check. If unreachable, HALT with instructions to re-add MCP config per `skills/ios/ios-bootstrap/references/xcode-mcp-config.md`.
+
+3. **Simulator bootable** — list available iOS 26 simulators via XcodeBuildMCP. If none available, HALT and instruct user to install via Xcode.
+
+4. **`docs/plans/.build-state.md` exists** with `project_type: ios` and `ios_features:` populated. If missing, HALT.
+
+5. **apple-docs-mcp reachable** (non-blocking) — if unreachable, log warning; commands proceed with degraded docs lookup (WebFetch fallback per `protocols/ios-context.md` §apple-docs fallback rule).
+
+## Usage
+
+At the top of any iOS-twin command's iOS branch, insert:
+
+```
+**Run iOS preflight:** see `protocols/ios-preflight.md`.
+```
+
+Then proceed with command-specific steps.

package/protocols/metric-loop.md

@@ -0,0 +1,93 @@
+# Metric Loop Protocol
+
+You are the orchestrator. You are about to run a metric-driven iteration loop on an artifact (code, architecture, docs, etc.) to drive it toward a quality target.
+
+## Step 0: Define Your Metric
+
+Before iterating, YOU define the metric for this specific context. Consider:
+- What is the artifact? (a task implementation, a security audit, an architecture doc, etc.)
+- What does "good" look like? (all tests pass, zero critical vulns, all acceptance criteria met, etc.)
+- Is the metric quantitative (test pass rate, vuln count, coverage %) or qualitative (architecture completeness, doc clarity)?
+
+Write a **Metric Definition** block to `docs/plans/.build-state.md`:
+
+```
+## Active Metric Loop
+Phase: [current phase]
+Artifact: [what you're iterating on]
+Metric: [what you're measuring, in one sentence]
+How to measure: [what the measurement agent should do — run tests, audit code, check criteria, etc.]
+Target: [score 0-100 at which you stop]
+Max iterations: [hard cap, default 5]
+```
+
+Then create a score log table:
+
+```
+| Iter | Score | Delta | Top Issue | Files |
+|------|-------|-------|-----------|-------|
+```
+
+When starting a new metric loop, REPLACE the previous Active Metric Loop section (if any). There is only ever ONE active metric loop. Previous loop results should already be recorded in their phase's section above. When the loop completes (Step 2 exit), rename the section header from `## Active Metric Loop` to `## Completed Metric Loop — [Phase N]` and leave it for historical reference.
+
+If you are in Phase 5, also record the current sub-step for the overall task cycle (not all of these are within the metric loop itself):
+```
+Sub-step: [5.1 Implement | 5.1b Cleanup | 5.2 Metric Loop | 5.3 Loop Exit | 5.4 Verify]
+```
+This tells the orchestrator exactly where to resume after context compaction.
+
+## Step 1: MEASURE
+
+Call the Agent tool — description: "Measure [metric]" — prompt:
+
+"[How to measure, from your metric definition]. Score the current state 0-100. Return your response with a clear SCORE: [number] line, a list of FINDINGS, and the single TOP ISSUE most likely to improve the score if fixed."
+
+Read the agent's response. You need: the SCORE, the TOP ISSUE, and the file paths for diagnosis in Step 3. Record the score to `docs/plans/.build-state.md`. The full findings list is useful for diagnosis but does NOT need to persist in your context across iterations — once you've picked the top issue, the details of lower-priority findings can go. Append a row to the score log in `docs/plans/.build-state.md`:
+
+| Iter | Score | Delta | Top Issue | Files |
+|------|-------|-------|-----------|-------|
+
+## Step 2: CHECK EXIT
+
+Stop the loop if ANY of these:
+
+- **Score >= target** → done. Log "Target met at iteration [N]."
+- **Iteration >= max** → done. Log "Max iterations reached. Final score: [N]."
+- **Stall: last 2 scores show no improvement** (delta <= 0 twice in a row) → done. Log "Stalled at score [N]."
+
+On stall or max iterations:
+- **Interactive mode:** present score history + top remaining issue to user. Ask for direction.
+- **Autonomous mode:** if score >= 60% of target, accept with warning. Otherwise skip. Log to `docs/plans/build-log.md`.
+
+If not exiting, continue to Step 3.
+
+## Step 3: DIAGNOSE
+
+Look at the findings from Step 1. Pick the ONE highest-impact issue — the single fix most likely to move the score. Do not try to fix everything at once. This is the autoresearch insight: one targeted change per iteration, measured impact.
+
+## Step 4: IMPROVE
+
+Call the Agent tool — description: "Fix [top issue]" — mode: "bypassPermissions" — prompt:
+
+"TARGETED FIX: [specific issue to fix, from diagnosis]. CONTEXT: [relevant architecture/criteria]. Make this specific change. Do not refactor unrelated code. Commit: 'fix: [description]'."
+
+> **Do NOT pass the measurement agent's full findings to this agent. Only pass the single diagnosed issue and relevant file paths.**
+
+## Step 5: LOOP
+
+Return to Step 1. Re-measure the artifact after the fix.
+
+---
+
+## Rules
+
+<HARD-GATE>
+AUTHOR-BIAS ELIMINATION: The measurement agent and the fix agent must NEVER share context.
+- They MUST be separate Agent tool calls (separate subprocesses, separate context windows).
+- The fix agent receives ONLY: (a) the single top issue diagnosed in Step 3, (b) the relevant file paths, (c) the acceptance criteria. It does NOT receive the measurement agent's full findings, score breakdown, or other issues.
+- The measurement agent in the next iteration does NOT know what the fix agent did — it measures the artifact fresh.
+</HARD-GATE>
+- One fix per iteration. Measure its impact before fixing the next thing.
+- Track ALL scores in `docs/plans/.build-state.md` so the history survives context compaction.
+- If context was compacted mid-loop: read `docs/plans/.build-state.md`, find the Active Metric Loop section, resume from the last recorded iteration.
+- CONTEXT HYGIENE: Measurement agents are analysis agents — read their full output for diagnosis. But once you've picked the top issue (Step 3) and dispatched the fix (Step 4), the detailed findings from THAT iteration are spent. Don't accumulate findings across iterations — each measurement is fresh.