@tyroneross/build-loop 0.30.3

package/skills/build-loop/references/apple-native-planning.md

@@ -0,0 +1,439 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Apple Native Planning Reference
+
+Phase 2 (Plan) guidance for native iOS / macOS / watchOS work. Surfaces the upfront decisions that, when skipped, become Phase 5 (Iterate) emergencies.
+
+Source: build-loop run on a sample timer app alarm-not-firing fix (2026-04-26). Generalized from the specific failure modes that bit that build.
+
+## When this reference fires
+
+`state.json.platform == "apple"` and the goal touches any of:
+- A timed notification, alarm, reminder, or scheduled local push
+- Background session continuity (Pomodoro, fasting, sleep, meditation)
+- Multi-target shared engine (iOS + watchOS, iOS + macOS)
+- Audio + haptic completion routing
+- Focus mode, DND, Time Sensitive, or Critical Alerts behavior
+- Live Activity / Dynamic Island
+
+If ANY apply, the planner MUST resolve every required decision below before dispatching Execute subagents.
+
+## Required upfront decisions
+
+### 1. Targets
+
+State the exact list. Do not assume.
+
+- iOS app
+- watchOS companion (paired? standalone? complication?)
+- macOS Catalyst, native macOS, or no Mac
+- Live Activity / Dynamic Island widget
+- Home Screen widget (iOS), watchOS widget, macOS menu bar item
+
+For each target chosen, the planner adds: deployment target, entitlements list, INFOPLIST keys, code-signing path.
+
+Common trap: the "shared" Swift file is included in only one target's source list (XcodeGen `project.yml`). Build error surfaces only when that target rebuilds.
+
+### 2. Notification strategy
+
+Pick exactly one per use case. Mixing without intent is the root cause of "alarm doesn't fire."
+
+| Strategy | When | Cost |
+|---|---|---|
+| Scheduled `UNTimeIntervalNotificationTrigger` armed at session START | Pomodoro, fasting, meditation — known duration | Need persisted `endDate`, idempotent re-arm on lifecycle events |
+| Scheduled, armed at background only | Foreground-only apps where backgrounding implies "user left" | High failure rate in the source timer-app incident |
+| Reactive (`willPresent` while running) | Foreground-only flows; prefers in-app modal over banner | Doesn't survive force-quit |
+| `interruptionLevel = .timeSensitive` | Most timer apps | Free; user opts in via Focus settings |
+| `interruptionLevel = .critical` | Genuine alarms with Apple-approved Critical Alerts entitlement | Must apply to Apple |
+| BGAppRefreshTask / silent push | Server-driven reminders | Out of scope for local timers |
+
+The planner names the strategy in the Plan output. "Scheduled at session start with idempotent re-arm on resume + cancel on pause/reset/skip/completion" is the canonical safe answer for Pomodoro-style timers.
+
+### 3. Background modes — what NOT to add
+
+Do NOT add `UIBackgroundModes: [audio]` to keep a timer running. App Store rejection is near-certain unless the app is a media player, navigation app, or VOIP. Use scheduled notifications instead. State this constraint explicitly in the plan so Execute subagents don't "fix" silence by adding the mode.
+
+### 4. Haptic strategy
+
+Haptics are platform-split. Each surface gets its own decision.
+
+| Surface | API | Plays through |
+|---|---|---|
+| iPhone | `CHHapticEngine` (rich patterns), `UINotificationFeedbackGenerator` (simple), `UIImpactFeedbackGenerator` | Taptic Engine, bypasses ringer switch |
+| Apple Watch | `WKInterfaceDevice.play(_:)` | Watch haptic motor |
+| iPad | `UINotificationFeedbackGenerator` only on supported models | Limited |
+| macOS | None (no haptic hardware on Mac) | n/a |
+
+CoreHaptics requires a fallback to `UINotificationFeedbackGenerator` for older devices. Audio and haptic paths must be independent — silenced audio should still haptic.
+
+### 5. Audio routing
+
+For chime / alarm sounds:
+
+- `AVAudioSession` category `.playback` with `mixWithOthers` option to bypass the silent switch (still respects ringer volume). Set in app launch BEFORE any AVAudioPlayer creation.
+- Bundled asset in `Bundle.main` with explicit `forResource:withExtension:` lookup.
+- Always provide `UNNotificationSound.default` as fallback when the bundled asset can't resolve. Silent failure at delivery is the worst outcome.
+- Do NOT use `AVAudioSession.Category.ambient` for alarms — it respects the silent switch.
+- For notification sounds: `UNNotificationSound(named:)` looks up files in the app bundle automatically, NOT the Documents directory.
+
+### 6. WatchConnectivity bridge
+
+If iOS + watchOS, pick exactly one transport per message type, with rationale.
+
+| Transport | Use for |
+|---|---|
+| `sendMessage(_:replyHandler:)` | Live, foreground-to-foreground, expects reply |
+| `transferUserInfo` | FIFO queue, delivers when reachable |
+| `updateApplicationContext` | Latest-state-only, replaces prior pending |
+| `transferFile` | Large blobs |
+| `transferCurrentComplicationUserInfo` | Complication-targeted |
+
+Pomodoro state usually wants `updateApplicationContext` (latest state wins) for the timer status, plus `sendMessage` for explicit user actions (start/pause/stop).
+
+### 7. Persistence for active session recovery
+
+When the app is force-killed or crashes mid-session, recovery must work. Pick one:
+
+- `UserDefaults` — simple state (mode, startDate, elapsed, intention). Fits Pomodoro.
+- `SwiftData` / Core Data — complex relational state. Overkill for a single active session.
+- File-based JSON in `Documents/` — when state is JSON-shaped and you want an audit trail.
+
+The persisted record MUST include a wall-clock start time (not relative seconds). Recovery code computes age via `Date().timeIntervalSince(startDate)`. Add a hard cap (e.g., 90 min) past which the recovery prompt is suppressed.
+
+### 8. Authorization timing (notifications)
+
+Three points to choose between:
+
+| When | Pros | Cons |
+|---|---|---|
+| App launch | Simple | Apple HIG discourages; users decline unexplained prompts |
+| First Start tap | Best context: user committed to a session | Need pre-permission UI sheet (HIG: explain value first) |
+| First completion | Worst — first session runs unauthorized and silently fails | Don't do this |
+
+Use the first-Start pattern with a pre-permission sheet that explains why you need it.
+
+## Test matrix templates
+
+### iPhone (15 states)
+
+Reuse the matrix from `build-loop:debugging-memory/references/ios-notification-alarm-playbook.md`. Phase 4 (Review) Validate sub-step references this matrix. Mark every row that requires a real device as `⚠️ device-only` in the scorecard; never claim ✅ on a sim-only verification.
+
+### Apple Watch (11 states)
+
+| # | Scenario | Expected |
+|---|---|---|
+| 1 | Foreground tick to zero | Watch haptic + sound (if not silent) |
+| 2 | Wrist down, watch dimmed | Haptic delivers on wake |
+| 3 | Watch app force-quit | Notification still fires (if scheduled) |
+| 4 | Phone unreachable, watch standalone | Local schedule fires |
+| 5 | Phone reachable, watch+phone both foreground | Single chime, no double |
+| 6 | Mode switch via Watch | iPhone reflects state via WatchConnectivity |
+| 7 | Pause via Watch crown | iPhone pauses, notification cancelled |
+| 8 | Workout running concurrently | Watch app coexists; HRV capture ok |
+| 9 | Always-on display | Tick continues, complication updates |
+| 10 | Charging | Foreground completion still fires |
+| 11 | watchOS Focus mode on | Banner suppressed (expected) |
+
+## Common Apple pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Time Sensitive vs Critical Alerts | "Alarm suppressed in Focus / DND" | Time Sensitive entitlement + `interruptionLevel = .timeSensitive`. Critical Alerts requires Apple approval |
+| Silent switch silences alarm | "Alarm doesn't sound" on iPhone | `AVAudioSession.Category.playback` with explicit activate |
+| AVAudioSession `.ambient` for alarms | Same as above | Use `.playback` |
+| Single-target Swift file in multi-target project | `cannot find 'Foo' in scope` in watchOS only | Add to project.yml watchOS sources, or use `#if !os(watchOS)` |
+| `UNNotificationSetting.badgeSetting` on watchOS | Compile error | `#if os(watchOS)` guard |
+| `UIImpactFeedbackGenerator` on macOS | Compile error | `#if !os(macOS)` guard |
+| Shared iOS/macOS SwiftUI sheet uses `.confirmationAction` for dismissal | iOS shows a top Done button, but macOS can render it in a bottom action area or detach it from scroll content | Split chrome by platform: keep iOS toolbar actions; on macOS use an in-content top header with reserved space for Done/Close and put scrollable content below it |
+| Notification scheduled with stale `timeInterval` after recovery | Alarm fires immediately or never | Recompute `endDate - now`, re-arm, cancel if `<= 0` |
+| Live Activity stale endDate | Lock-screen countdown jumps | Update with authoritative `endDate = phaseStartDate + totalTime + pauseAccumulatedDuration` |
+| TestFlight build with new entitlement but no Apple-approved Critical Alerts | Crash on launch on TestFlight | Apply for entitlement before shipping |
+
+## Plan-output checklist
+
+Phase 2 Plan output for an Apple-native goal should include, in order:
+
+1. **Targets**: explicit list with deployment targets
+2. **Notification strategy**: which row from §2, with rationale
+3. **Background modes added**: explicit "none" if no audio/voip; otherwise list with App Store risk note
+4. **Authorization moment**: which from §8
+5. **Audio + haptic split**: per-surface API choice
+6. **WatchConnectivity transports** (if applicable): per-message-type
+7. **Persistence layer**: one of §7
+8. **Test matrix subset**: which rows are sim-verified vs device-deferred
+9. **Diagnostic logging**: what subsystem/category, what events
+10. **Anti-pattern guard**: explicit "do NOT add UIBackgroundModes audio" if relevant
+11. **Shared SwiftUI modal chrome**: for iOS + macOS sheets, state which controls stay in iOS toolbars and which macOS controls move into persistent top content headers. Verify Done/Close remains visible when content scrolls.
+
+## When to escalate
+
+If Plan can't resolve any of §1-§8 from the goal text + existing repo state, escalate to the user before Execute. These are not safe to assume; the wrong choice becomes a Phase 5 firefight.
+
+## watchOS modernization checklist
+
+Captured from sample timer app build 73 (2026-04-26). Use during Phase 2 Plan when the goal touches a watchOS target — `*.appiconset` decisions, navigation refactors, or Smart Stack work. Each item is a concrete check, not a recommendation.
+
+### Navigation
+
+1. **Vertical `TabView(.verticalPage)` is the post-watchOS-10 canonical root.** Three peers max; first tab gets the large title. `NavigationStack` only inside a tab that drills down (e.g. a Customize tab opening a detail form). Crown rotates between tabs.
+2. **Anti-pattern: horizontal page-based TabView.** Apple deprecated the visual model. If the existing root uses it, refactor before any other UI work — every other change inherits the old chrome.
+3. **Anti-pattern: modal sheets stacked >1 deep.** Replace with NavigationStack push or vertical-tab swap. A watch sheet stacked on a sheet is unnavigable on a 41–49mm screen.
+4. **Tab content can resize on watchOS 10+.** Useful for a "running session" tab that should expand to full-screen during an active timer — opt in by giving the running view a larger ideal size and letting the tab grow.
+
+### Always-On Display (AOD)
+
+5. **Read `\.isLuminanceReduced` in every view that renders accent color, filled shapes, or live private data.** Do not branch on `\.scenePhase` — AOD is a luminance state, not a lifecycle state. UI continues updating at ≤1 Hz under dim.
+6. **Three required AOD adaptations:**
+   - Accent → `.foregroundStyle(.secondary)` (or `HierarchicalShapeStyle.secondary` when binding to a `ShapeStyle` slot).
+   - Filled `Capsule()`/`Circle()`/`RoundedRectangle().fill(...)` → `.stroke(...)` outline.
+   - Hide live biometric or private readouts (heart rate, intention text, anything wrist-down strangers shouldn't see).
+7. **Keep the running countdown legible under AOD.** It's the entire reason a user glances. Lower contrast is fine; hiding it is not.
+8. **Type system note:** ternary across heterogeneous shape styles fails — `ShapeStyle` is not a uniform existential. Wrap with `AnyShapeStyle(HierarchicalShapeStyle.secondary)` vs `AnyShapeStyle(Color.accent)` so Swift can pick a common type.
+
+### Liquid Glass (watchOS 26+)
+
+9. **Use `#available(watchOS 26.0, *)` conditional, never bump deployment target.** Bumping locks out users on watchOS 11–25, which is most of the install base for ~12 months post-release.
+10. **Wrap as a `ViewModifier`** so call sites stay terse:
+    ```swift
+    private struct GlassPrimaryStyle: ViewModifier {
+        func body(content: Content) -> some View {
+            if #available(watchOS 26.0, *) {
+                content.buttonStyle(.glassProminent)
+            } else {
+                content.buttonStyle(.borderedProminent)
+            }
+        }
+    }
+    ```
+11. **Only the primary action per screen gets `.glassProminent`.** Secondary actions use `.glass` (or `.bordered` on fallback). Anti-pattern: glass on every button — defeats the focal weight the material is designed to carry.
+12. **Performance:** if frame drops show on Series 6/7-class hardware under glass, fall back to `.background(.ultraThinMaterial)` (available watchOS 9+) which approximates the look without the blur cost.
+
+### Smart Stack + complications
+
+13. **Compute `var relevance: TimelineEntryRelevance?` on every `TimelineEntry`.** Smart Stack ranks by `score` (Float, 0–100). Idle/stale → 0. Running primary state → 100. Paused → 10. Secondary phase running → 60. Without `relevance`, the system assumes 0 and the complication never surfaces.
+14. **Set `duration:` to the remaining session window** (e.g. `TimeInterval(timeLeft)`). The system ages the entry out automatically when duration elapses; otherwise the stack pins a stale entry.
+15. **Live Activity auto-pickup on watchOS 26+.** If iOS already starts a Live Activity via `Activity.request(...)`, no Watch-side code needed — Smart Stack surfaces it. This is the highest-leverage Watch feature for any session-based app.
+16. **`supportedFamilies` checklist:** `accessoryCircular`, `accessoryCorner`, `accessoryInline`, `accessoryRectangular`. Skipping any reduces the watch faces a user can pin the complication to.
+17. **ClockKit migration check:** `import ClockKit` should appear nowhere. If users had a ClockKit complication pre-watchOS-9, implement `CLKComplicationWidgetMigrator` so they auto-migrate without re-pinning. Fresh apps skip this.
+
+### App icon
+
+18. **Single-size 1024×1024 PNG, sRGB, no alpha.** Xcode 14+ generates per-device sizes at build. The runtime applies the circular mask — design with the center 50%-radius circle in mind, ship a square master.
+19. **Separate watchOS catalog when the iOS catalog already has watch entries.** Keeps the modern `idiom: watch` 1024 entry isolated from the legacy iOS-bundled watch icon roles, and lets the watch art evolve independently.
+20. **Override `ASSETCATALOG_COMPILER_APPICON_NAME` per target.** When iOS uses `AppIcon` and watchOS uses `AppIcon-Watch`, the catalogs can both ship without name collision. Set the watchOS-target setting in `project.yml` (XcodeGen) or per-target build settings.
+21. **Verify post-build with `xcrun assetutil`:**
+    ```bash
+    xcrun assetutil --info path/to/SampleTimer.app/Assets.car | grep -i icon
+    ```
+    Expect to see the icon name you supplied. If not, the catalog isn't being picked up by the target.
+
+### Anti-patterns (Apple-explicit)
+
+- ❌ Horizontal page-based TabView (deprecated visual)
+- ❌ Modal sheets stacked >1 deep
+- ❌ Tables with >5 visible rows (use `ScrollView` + `LazyVStack` or paginate)
+- ❌ Two-finger gestures, long-press menus expecting precision
+- ❌ Bright filled shapes during AOD
+- ❌ ClockKit-only complications (won't ship on new face setups; deprecated watchOS 9)
+- ❌ Group borders on watch — the screen edge is the border
+- ❌ Custom haptic loops outside `WKInterfaceDevice.play(_:)` types
+- ❌ Bumping `WATCHOS_DEPLOYMENT_TARGET` to gain Liquid Glass instead of `#available` conditional
+- ❌ Two `AppIcon.appiconset` directories with the same name — Xcode picks one unpredictably; rename one and override `ASSETCATALOG_COMPILER_APPICON_NAME`
+
+### Verification matrix (should run before claiming done)
+
+| Check | Command | Pass signal |
+|------|---------|-------------|
+| watchOS builds | `xcodebuild -scheme SampleTimer-watchOS build CODE_SIGNING_ALLOWED=NO` | `BUILD SUCCEEDED` |
+| Widget builds | (deps from watchOS scheme) | no widget-specific errors in log |
+| Icon compiled | `xcrun assetutil --info <app>/Assets.car \| grep -i icon` | watch icon name appears |
+| All schemes | iterate iOS/macOS/iOSWidget/watchOS | each `BUILD SUCCEEDED` |
+| Quality | `./quality-check.sh` | pass count unchanged or improved |
+
+Real-device-only (mark ⚠️ in scorecard, never ✅):
+- Liquid Glass rendering at runtime
+- AOD visual under wrist-down
+- Smart Stack relevance ranking on the actual stack
+- Live Activity Smart Stack pickup
+- Home-grid icon appearance
+
+---
+
+## Tab-vs-drill-in path discipline on watchOS
+
+When designing watch IA, every action should have exactly one canonical path.
+
+### Tab vs navigation push — when to choose which
+
+- **Tab** when the destination is a peer top-level surface that users want to reach from any state. Vertical TabView pages on watchOS feel like rooms, not screens.
+- **Navigation push** when the destination is a hierarchical sub-screen of one parent (e.g. editing a single object's properties).
+
+### Redundancy elimination rule
+
+If a feature is reachable as both a tab AND an in-screen drill-in, delete the drill-in. Two paths to the same place fragment muscle memory and violate Calm Precision path-discipline.
+
+Symptom: user discovers feature A via Tab; later discovers same feature A via Push from inside Tab B; now wonders if they're different.
+
+### Worked example — sample timer app WatchModePicker consolidation (build 74)
+
+Build 73 introduced a vertical TabView with a Customize tab listing all modes. The pre-existing `WatchModePicker` view (reachable from Timer idle via "Change mode" navigation push) became redundant. Consolidation steps:
+
+1. Confirm the drill-in's behavior is fully covered by the tab. If not, port the missing behavior first.
+2. Delete the drill-in's source file. Glob-based target sources (xcodegen `path: watchOS`) make this a one-step removal — no manifest edit needed.
+3. Remove the entry-point link from the parent screen. Replace with a small text hint ("swipe up for modes") so the affordance stays discoverable without a competing nav path.
+4. Grep for zero references in `*.swift`, `*.yml`, `*.pbxproj`.
+
+### Tap directness on list items
+
+A tap on a list item that has only one logical follow-action should auto-flow into that action. Don't force tap → tap-edit-button.
+
+- Preset row: single tap = select + return to invoking surface (set tab selection state).
+- Configurable row (e.g. "Custom"): single tap = push the editor directly. Set the selection state in `simultaneousGesture` so when the user finishes editing and pops, the upstream surface already reflects the choice.
+
+The intermediate "select, then tap an Edit button to configure" flow is two-tap UX where one will do.
+
+## Visual delta audit pattern
+
+For native iOS/macOS modernization passes scoped from a prior audit, run a three-pass workflow before opening any file:
+
+1. **Source-code extraction** is load-bearing. The audit must cite `file:line` for every delta with a concrete suggested replacement. Vague reports ("inconsistent typography") force re-extraction during execute and double the cost. The audit doc becomes the spec.
+2. **Canonical reference identification**. Name 2–3 modern reference views in the same repo (e.g. `AlertSettingsView`, `SettingsView`, `ProfileSettingsView`) so the audit's "good" target is in-tree, not abstract HIG.
+3. **Structured delta report**. Group by category (color hardcodes / Dynamic Type / spacing / card pattern / interaction / chart hex), count, and rank by user-impact severity.
+
+### Native visual evidence
+
+Use built-in simulator screenshots and native AX evidence for visual regression after a redesign that changes layout. Those tools do not extract computed SwiftUI font/color/spacing values, so source-code extraction remains load-bearing for metric audits. Use grep + Read for typography, color, spacing, and token claims. IBR native scans are explicit-only auxiliary evidence when the user asks for IBR.
+
+### Three-tier ROI ordering
+
+Sequence fixes by descending impact:
+
+1. **Colors + dark-mode safety** (highest ROI). Replacing `.foregroundColor(.white.opacity(N))` with `.foregroundStyle(.primary/.secondary/.tertiary)` simultaneously fixes dark-mode adaptation, WCAG contrast, and future-proofs against light-mode variants. Small line count, broad effect.
+2. **Typography Dynamic Type**. Replacing `.font(.system(size: N))` with `.font(.caption / .footnote / .subheadline / .body / .headline / .title3)` enables accessibility text-size scaling. Keep hero anchors (28pt+ ultraLight KPIs) fixed and add `// Hero anchor: intentional fixed size` comments so future audits don't re-flag them.
+3. **Tokens + spacing rhythm**. Hex literals → named Theme tokens; off-grid `padding(.vertical, 6/10/14)` → `Spacing.sm/md/lg`. Lowest individual impact, cumulative polish.
+
+### WCAG body-text math for `.white.opacity(N)`
+
+Against the LiquidGradientBackground core `#3A4878` (focus mode steel-blue) — a representative dark gradient core — alpha-composited approximations:
+
+| Foreground | Approx contrast vs `#3A4878` | WCAG 4.5:1 (body) |
+|---|---|---|
+| `.white.opacity(0.9)` | ~10.6:1 | ✅ pass |
+| `.white.opacity(0.7)` | ~5.7:1  | ✅ pass |
+| `.white.opacity(0.5)` | ~3.8:1  | ⚠️ fails |
+| `.white.opacity(0.35)` | ~2.4:1 | ❌ fails |
+| `.white.opacity(0.3)` | ~2.1:1  | ❌ fails |
+
+Anything at or below 0.5 on a dark gradient fails AA body. `.foregroundStyle(.secondary)` resolves to a SwiftUI-managed semantic color that is guaranteed ≥4.5:1 against the backing material in both light and dark color schemes — switch to it instead of tuning opacity by eye.
+
+---
+
+## WatchConnectivity callback wiring — avoiding dead-signal bugs
+
+**Pattern.** When watch sends a signal via `WCSession.sendMessage(_:)`, iPhone's delegate `WCSessionDelegate.session(_:didReceiveMessage:)` decodes the payload and exposes a closure-based published callback on the connectivity manager:
+
+```swift
+var onBiometricBreakSignalReceived: ((BiometricBreakSignal) -> Void)?
+```
+
+A closure variable like this is useless unless something on the iPhone side assigns into it during app launch. The compiler will not catch a missing assignment because optional closures default to `nil` and silently no-op.
+
+**Audit checkpoint.** For every published callback variable on a connectivity manager, grep for at least one assignment site somewhere in iOS code:
+
+```bash
+grep -rn "onMyCallback = " iOS/ Shared/
+```
+
+If grep returns zero hits, the entire feature path is dead — watch detection runs, the message arrives, and nothing happens on iPhone.
+
+**Sample timer app example.** `onBiometricBreakSignalReceived` was declared in build 73 but inspection during build 78 found two related symptoms:
+1. Build 73 wired the closure to `TimerEngine.handleBiometricBreakSignal`, which surfaces an in-app `CheckInData` sheet — but only when the iPhone app is foreground AND a flow session is running ≥15 minutes. In every other state (app backgrounded, no active session, app closed), the signal was effectively dropped.
+2. Build 78 added a second path on the same closure: an opt-in time-sensitive `UNUserNotification` so the signal produces user-visible behavior even when the iPhone app is not in front. Default off; toggle in `AlertSettingsView`.
+
+**Recommended patterns.**
+- Prefer `NotificationCenter` for fan-out when more than one subscriber may need the signal — avoids closure-stomping where a later assignment overwrites an earlier one.
+- Or use Combine `PassthroughSubject<Signal, Never>` for typed reactive flow with multi-subscriber semantics.
+- Or make callback assignment a constructor parameter (`init(onSignal: @escaping (Signal) -> Void)`) so the compiler enforces wiring at instantiation.
+- For closure-variable APIs that intentionally allow only one subscriber, add a unit test that calls `connectivityManager.simulateMessage(...)` and asserts a side effect — this catches dead-signal regressions before TestFlight.
+
+**Coexisting paths.** When extending an existing closure with a second path (e.g. notification + in-app sheet), put both under the same closure body and gate each independently. Don't reassign the closure — the previous path will be silently lost.
+
+
+## Test target wiring on XcodeGen Apple projects
+
+A test target that exists in `project.yml` is only invokable by `xcodebuild test` if it is also a member of a scheme's `test.targets` array. Membership in `targets:` alone makes the bundle compile-clean but unreachable from the test action.
+
+**Symptom.** `xcodebuild test -scheme SampleTimer-iOS -only-testing:SampleTimer-UnitTests` returns:
+
+```
+Cannot test target "SampleTimer-UnitTests"... isn't a member of the specified test plan or scheme
+```
+
+**Fix.** In `project.yml`, the scheme's `test.targets` array must include the test bundle by name:
+
+```yaml
+schemes:
+  SampleTimer-iOS:
+    test:
+      config: Debug
+      targets:
+        - SampleTimer-UnitTests
+        - SampleTimer-UITests
+```
+
+Then regenerate (`xcodegen generate --spec project.yml`).
+
+**Platform alignment is part of the wiring.** The test target's `platform:` must match the scheme's runnable destinations. A `bundle.unit-test` declared `platform: macOS` cannot be run from an `SampleTimer-iOS` scheme via `-destination 'platform=iOS Simulator'` — xcodebuild surfaces:
+
+```
+Cannot test target "SampleTimer-UnitTests" on "iPhone 17 Pro": ... does not support iphonesimulator
+```
+
+If the wiring goal is "iOS scheme runs the unit tests on iPhone simulator," the test target itself must be `platform: iOS` (and any source files it pulls from `Shared/` need to compile cleanly for iOS — which is usually free since the iOS app target already compiles them). When you switch a previously-macOS test target to iOS, audit every scheme that referenced it: the macOS scheme's `test.targets` will silently break unless updated to drop the now-iOS test target or replaced with a separate macOS-platform test bundle.
+
+**Audit checkpoint.** Before TestFlight, run a quick grep over `project.yml` to catch test targets not wired anywhere:
+
+```bash
+# every test target name should appear in at least one scheme's test action
+yq '.targets | to_entries | map(select(.value.type | test("bundle"))) | .[].key' project.yml
+yq '.schemes | to_entries | map(.value.test.targets // []) | flatten' project.yml
+```
+
+If a target name appears in the first list but not the second, the test bundle exists but no scheme can run it.
+
+**Sample timer app example (build 79).** `SampleTimer-UnitTests` had been a `bundle.unit-test` on `platform: macOS`, wired into the macOS scheme's `test.targets` only. Builds 71-78 shipped without exercising any of the new code paths in CI. Build 79 added five test files covering AlertConfig codable, pomodoro notification identifier generation, Local Network permission classification, keychain-cache stability, and biometric break-signal default-off wiring. The test target was migrated to `platform: iOS`, added to `SampleTimer-iOS.schemes.test.targets`, and removed from the macOS scheme (which can no longer host an iOS-platform bundle). Net: `xcodebuild test -scheme SampleTimer-iOS -destination 'platform=iOS Simulator,name=iPhone 17 Pro' -only-testing:SampleTimer-UnitTests` runs 51 tests in ~7 seconds.
+
+**When test isolation must round-trip through `UserDefaults.standard`.** A common pattern in app-level singletons: `init(defaults: UserDefaults = .standard)` reads from injected defaults, but property `didSet` writes target `UserDefaults.standard` unconditionally. Tests that assert "value persists across two store instances" cannot rely on injected defaults for the write path — they have to either snapshot/restore `.standard` in `setUp`/`tearDown`, or refactor production to plumb the same defaults through both read and write. For a test-only access change this is heavier than a simple `private → internal` flip; document the constraint in the test file rather than push a deeper production change.
+
+## SourceKit ghost diagnostics on Xcode 26.x
+
+Discovered: Example-iOS-App Run A + Run A.1 (2026-05-20). Generalized so every Apple-platform build-loop run starts inoculated.
+
+### Pattern
+
+On Xcode 26.x XcodeGen projects, editing `.swift` files and running `xcodegen generate` produces false-positive `<new-diagnostics>` SourceKit errors of the form `Cannot find type 'X' in scope` for types defined in sibling files within the same module. The diagnostics arrive AFTER `xcodebuild` ships `** BUILD SUCCEEDED **`. They are stale index output, not real errors. Upstream tracking: [anthropics/claude-code#46651](https://github.com/anthropics/claude-code/issues/46651).
+
+### Two distinct causes, same symptom
+
+1. **New file not registered in `.pbxproj`** — file exists on disk, `xcodegen generate` not yet run. Both SourceKit and `xcodebuild` fail. Fix by running `xcodegen generate`.
+2. **Xcode 26.x SourceKit cross-file index lag** — `xcodegen generate` has run, `xcodebuild` succeeds, SourceKit's index is 5–30s behind. Fix is wait or ⌘⇧K in Xcode; do not edit code.
+
+Cause 1 is a real problem with a real fix. Cause 2 is a harness/IDE bug; touching code makes things worse.
+
+### What the orchestrator must do
+
+When `state.json.platform == "apple"` and the goal touches existing `.swift` files, the Phase 2 plan output must include this preamble before any Execute dispatch:
+
+> SourceKit `<new-diagnostics>` arriving within ~30s of `xcodegen generate` are presumed stale until `xcodebuild` disagrees. Do not panic-edit a file because the diagnostic stream cannot find a type that grep can.
+
+The same preamble belongs in subagent prompts that touch Swift files, per `feedback_subagent_skill_reactivity` (knowledge in CLAUDE.md alone doesn't reach subagents).
+
+### When to actually act
+
+A SourceKit "Cannot find type" diagnostic is real (not a ghost) when ANY apply:
+- `xcodebuild` produces the same error
+- The named type does not exist anywhere in the module (`grep -rn "<type>" --include="*.swift"` returns nothing)
+- The named type is defined in a different module that is not imported
+- The file was just created and `xcodegen generate` has not been run
+
+Otherwise it's a ghost and the fix is patience.

package/skills/build-loop/references/capability-routing.md

@@ -0,0 +1,181 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Capability Routing (full protocol)
+
+> Loaded from `skills/build-loop/SKILL.md` summary. Contains the full capability routing table, trigger conditions, and plugin/hook/skill/agent mandatory routing rules.
+
+## Capability Routing
+
+Build-loop prefers repo-owned agents and bundled skills for core loop decisions. External plugins are accelerators only when explicitly requested or when a row below names them as secondary. Each capability has three tiers: **preferred** (build-loop-owned surface) → **secondary** (another installed plugin or skill that can partially cover) → **inline fallback** (guidance text from `fallbacks.md`, injected verbatim into subagent prompts).
+
+Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` and writes the result to `.build-loop/state.json` under `availablePlugins`. All routing consults that object.
+
+### Core loop skills/assets (always check)
+
+| Skill | Used In | Fallback |
+|-------|---------|----------|
+| `writing-plans` | Phase 2 (Plan) | Write a structured plan directly: goal, tasks with exact file paths, dependency order, test commands |
+| `subagent-driven-development` | Phase 3 (Execute) | Dispatch parallel agents manually using the host's available delegation tool for independent file groups |
+| `verification-before-completion` | Phase 4 sub-step G (Report) | Run all test/build/lint commands and confirm output before claiming completion |
+| `simplify` (slash: `/simplify`) | Phase 4 sub-step E (Simplify) | Self-review the diff: remove scaffolding, inline single-use helpers, delete dead branches |
+| `complexity_detector.py` (accelerator, not a gate) | Phase 4 sub-step E (Simplify) | Diff-scoped stdlib-AST hotspot detector for changed Python; surfaces high-severity hotspots for a simpler rewrite, apply-vs-advise via existing Review-B + independent-auditor. Optional Python aid — the default Simplify pass reasons over the diff language-agnostically (see `phase-4-review.md` §"Sub-step E: Simplify") |
+| `build-loop:self-improve` | Phase 6 (Learn) | Scan recent runs for recurring patterns, auto-draft experimental skills/agents with A/B tracking, notify user for keep/remove decisions |
+| Intent capability pack | Phases 1-4 | Read `references/intent-capability-pack.md`; write `.build-loop/intent.md`; pass the intent packet to every subagent |
+| Modular systems pack | Phases 1-4 | Read `references/modular-systems-pack.md`; partition files/tasks MECE; prefer modular scalable boundaries unless an exception is documented |
+| Codex subagent adapter | Phase 3 (Execute, Codex only) | Read `references/codex-subagents.md`; use `templates/codex-worker-prompt.md` for authorized Codex workers |
+
+### Phase quick reference
+
+| # | Phase | Purpose | Sub-steps / key actions |
+|---|---|---|---|
+| 1 | **Assess** | Understand state + define goal & criteria | detect tools, map architecture, load memory, write `intent.md` + `goal.md` |
+| 2 | **Plan** | Break work, identify parallel-safe, optimize | writing-plans skill → dependency graph |
+| 3 | **Execute** | Build per plan | parallel subagents, Sonnet default, Opus escalation |
+| 4 | **Review** | Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Auto-Resolve → Report | sub-steps A-G; B-D can route to Iterate; F drains non-destructive items via autonomy_gate; G runs only on final pass |
+| 5 | **Iterate** | Fix Review failures, loop back to Review | max 5x; orchestrator stuck-iteration cascade (evidence-gap repair → memory re-check → parallel assess at 2 fails → causal-tree at 3 fails) |
+| 6 | **Learn** | Cross-build pattern detection + experimental skill drafting | optional; requires `runs[] >= 3`; auto-promote opt-in |
+
+### Capability routing table
+
+| Capability | Preferred | Secondary | Inline fallback section |
+|---|---|---|---|
+| Web UI build | `build-loop:ui-design` + `build-loop:design-contract-specialist` (`trigger_point: phase2-design-direction`) + `calm-precision` + `templates/ui-subagent-prompt.md` | `frontend-design:frontend-design` only when explicitly requested | `fallbacks.md#web-ui` |
+| Web UI validation | `ui-validator` agent + `audit-design-rules.mjs` + browser/screenshot artifact | `showcase:capture` for visual evidence | `fallbacks.md#web-ui` |
+| Orchestrated UI build | `build-loop:ui-design` → build-loop-owned design direction → implementer fan-out → ui-validator/design-contract reconciliation | explicit user-invoked design tool artifacts passed to `design-contract-specialist` | `fallbacks.md#web-ui` |
+| Mobile UI build (`uiTarget: "mobile"` — iOS/watchOS sim) | `build-loop:ui-design` + `build-loop:design-contract-specialist` + `calm-precision` + `apple-dev` | — | `fallbacks.md#mobile-ui` + `fallbacks.md#apple-dev` |
+| Mobile UI validation (iOS sim) | `xcrun simctl io booted screenshot` for static; `idb ui tap` for interaction | `showcase:capture` | `fallbacks.md#mobile-ui` |
+| macOS desktop UI build (`uiTarget: "macos"`) | `build-loop:ui-design` + `build-loop:design-contract-specialist` + `calm-precision` + `apple-dev` | — | `fallbacks.md#mobile-ui` + `fallbacks.md#apple-dev` |
+| macOS desktop UI validation | IBR `scan_macos` when `availablePlugins.ibr == true`; else `native-ax-driver` against the running `.app` (pid-anchored). NEVER `xcrun simctl` (no macOS simulator). NEVER `nm`/`strings` as substitute. | `showcase:capture` for screenshot evidence | `fallbacks.md#mobile-ui` |
+| Design system tokens | `design-contract-specialist` reads project token/theme/component files and records the source in `.build-loop/app-contract/ui.md` | — | `fallbacks.md#design-tokens` (reads consumer project's token files — never hardcodes) |
+| Recent design structures | `design-contract-specialist` reads `references/recent-design-structures.md` and selects by product/workflow/data fit | explicit design-tool artifacts passed as evidence | `fallbacks.md#web-ui` |
+| Screenshot / visual evidence | `showcase:capture`, `showcase:record` | `screenshot` MCP tool | `fallbacks.md#screenshot` |
+| Web content fetching (low LLM) | `scraper-app:web-scraper` SDK | — | `fallbacks.md#web-fetch` (flags LLM cost in report) |
+| Deep debugging | `build-loop:debug-loop` + `build-loop:debugging-memory` native search/store | standalone Coding Debugger only when explicitly installed for cross-project memory | `fallbacks.md#debug` |
+| Bug-pattern memory | `build-loop:debugging-memory` | — | `fallbacks.md#bug-memory` (greps `.build-loop/issues/` + `.bookmark/`) |
+| Agent authoring | `agent-builder:agent-builder-anthropic` | `plugin-dev:agent-development` (if plugin work) | `fallbacks.md#agent-authoring` |
+| DeepAgents / local-LLM agent work | `build-loop:building-with-deepagents` (SubAgent API, middleware stack, per-agent tool scoping, anti-patterns) | — | Read installed `deepagents` source: `python3 -c 'import deepagents, os; print(os.path.dirname(deepagents.__file__))'` then `graph.py` + `middleware/subagents.py` |
+| Structured reports / handoffs | `pyramid-principle:pyramid-short-form` (Review-F reports), `pyramid-long-form` (design docs) | — | `fallbacks.md#structured-writing` (SCQA + MECE skeleton) |
+| Hosted-IDE migration (Replit / Lovable / Bolt / v0) | `replit-migrate:migration-scan`, `migrate-web`, `migrate-ios`; MCP tools `migrate_scan`, `migrate_plan_web`, `migrate_plan_native`, `migrate_map_apis`, `migrate_map_models`, `migrate_check_progress` | — | `fallbacks.md#migration` (manual inventory + stack-translation) |
+| Prompt authoring / review / audit (system prompts, agent prompts, eval judges) | `prompt-builder:prompt-builder` skill; slash commands `/prompt-builder:optimize`, `/score`, `/compare`, `/save`, `/list`. Calibrates to model tier (T1/T2/T3) and deployment (interactive, backend, rag_pipeline, agent, plugin, eval_judge, personal_mobile). Returns 6-Part-Stack prompt + 5-dim score + diagnosis + `[ASSUMED:]` tags + `TEMPERATURE_HINT` | `prompt-builder` (personal skill, same name, loaded via Skill tool) | `fallbacks.md#prompt` |
+| iOS / watchOS / macOS dev + deploy | `apple-dev` personal skill (via `Skill("apple-dev")`) | `replit-migrate:migrate-ios` (when migrating *to* native) | `fallbacks.md#apple-dev` |
+| Web deploy verification (Vercel) | Vercel MCP (`mcp.vercel.com` remote OAuth, only if user adds it to `.mcp.json`) | Vercel CLI via `scripts/verify_deploy.py` | `fallbacks.md#web-deploy-verify` |
+| Strategic frame / PRD grounding (Assess + Review) | `build-loop:prd-bridge` — reads `docs/prd-*.md` frontmatter (`core_principles`, `load_when`) + Navigation Map + Section Index in Phase 1; verifies diff doesn't violate principles in Phase 5 Fact-Check; recommends `prd-builder` skill if no PRD exists. Falls back to grep on principle keywords if frontmatter parser unavailable. | `prd-builder` skill direct invocation | Phase 1 captures north-star + intent fresh into `intent.md` (existing fallback) |
+| Architecture scan / impact trace (Assess + Review) | `build-loop:architecture-scan` (Assess refresh), `build-loop:architecture-impact` (blast-radius), `build-loop:architecture-rules` (Review violation check), `build-loop:architecture-dead` (orphan scan) — read `.navgator/architecture/` JSON; native skills sourced from NavGator with provenance and drift-detection via `build-loop:sync-skills` | `gator:*` commands if installed | Read component → edit → re-read downstream |
+| Debugger memory-first gate (Review + Iterate) | `build-loop:debugging-memory` — verdict gate (`KNOWN_FIX` / `LIKELY_MATCH` / `WEAK_SIGNAL` / `NO_MATCH`) with strict direct-apply triple-gate (file + version + secondary signal) and Review-F outcome feedback. Orchestrator owns the when-to-fire policy (Review-B + every Iterate attempt) and routes to this skill. | `build-loop:debug-loop` direct (when memory says enter the loop or 3 same-criterion failures) | `fallbacks.md#debug` |
+| Runtime visibility / observability (Assess + reactive Review/Iterate) | `build-loop:logging-tracer` — generates stack-appropriate structured logging / OTel with ephemeral-by-default policy (Mechanism A: `DEBUG_TRACE=1` runtime gate; Mechanism B: `git-stash` throwaway). Invoked reactively when an Iterate attempt flags `evidence_gap: true`. Orchestrator runs the passive Assess scan inline (no skill call needed) and only loads this skill when instrumentation is actually being added. | — | `fallbacks.md#logging-fallback` (inline Tier-1 zero-dep JSON logger per stack) |
+| Self-improvement / recurring pattern detection (Phase 6 Learn) | `build-loop:self-improve` — runs after every build; detects recurring failures and manual interventions; drafts experimental skills/agents to `.build-loop/skills/experimental/`. Auto-promote to `.build-loop/skills/active/` requires opt-in (`autoPromote: true`) plus effective non-confounded sample ≥ 8; regressions and inconclusive results write proposals to `.build-loop/proposals/` for user confirmation — never auto-remove. Cross-project promotion via `/build-loop:promote-experiment <name>` | — | Manual review of `.build-loop/state.json.runs[]` |
+| Context recovery after compaction | `bookmark:*` commands | — | Re-read last plan file in `.build-loop/` |
+| Claude Code plugin authoring / review | `plugin-builder` (personal skill), `plugin-dev:*` family | `build-loop:plugin-hygiene-lessons.md` enforces manifest/hook/marketplace rules in Review-D | Read `plugin-hygiene-lessons.md` verbatim |
+
+### Sub-routers (set during Phase 1)
+
+**UI target**: prefer the most specific match — order matters.
+
+1. **macOS desktop (`uiTarget: "macos"`, `platform: "apple"`)** — `*.xcodeproj` or `Package.swift` is present AND any of: (a) project has NO `ios/` directory AND has `Sources/` / `App/` with `*.swift`; (b) Xcode project's `SUPPORTED_PLATFORMS` / deployment target indicates macOS; (c) repo grep shows `import AppKit` or `import SwiftUI` paired with `WindowGroup`/`Window` (macOS scene types) and no `UIKit` import. macOS has no simulator; validation routes to `native-ax-driver` or IBR `scan_macos`, never to `xcrun simctl`.
+2. **iOS/watchOS mobile (`uiTarget: "mobile"`, `platform: "apple"`)** — `ios/` directory present, OR `*.xcodeproj`/`Package.swift` with `UIKit` import / `iOS` deployment target. Validation uses the iOS simulator screenshot path.
+3. **React Native mobile (`uiTarget: "mobile"`, `platform: "react-native"`)** — `app.json` (Expo) or `App.tsx` with `react-native` import.
+4. **Web (`uiTarget: "web"`, `platform: "web"`)** — fallback for everything else with a UI surface.
+
+Tie-breaker: if signals are mixed (an Apple project with both `ios/` and a macOS target), set `uiTarget: "mobile"` and surface a one-line note in Assess; the build can override via `state.json.uiTarget` if the goal targets the macOS surface.
+
+**Migration source**: if `.replit` / `replit.nix` present → `migrationSource: "replit"`. Lovable / Bolt / v0 export markers (e.g. `lovable.config`, `bolt.config`, `v0.dev` in comments) → corresponding source. `replit-migrate` skills generalize — load `migration-scan` for any of the above, override hints as needed.
+
+**Apple deploy**: when `platform: "apple"` AND goal includes "deploy", "TestFlight", or "App Store" → Phase 7/8 invoke `apple-dev` deploy flow using ASC creds per `~/.claude/projects/-Users-tyroneross/memory/reference_asc_credentials.md`. Apply deployment policy first: TestFlight/App Store Connect upload/export defaults to `auto`; App Store production release/submission defaults to `confirm`.
+
+**Web deploy verify**: fires when `.vercel/project.json` or `vercel.json` is present AND the build performed a push/deploy → Phase 4 Review-B invokes `scripts/verify_deploy.py` (preferred-tier upgrade: Vercel MCP only if the user has added it to `.mcp.json`). Infra failures return `skipped`, never block the build.
+
+## Trigger Conditions
+
+Some capabilities should fire proactively based on goal phrasing or files touched. Phase 1 ASSESS sets these flags in `.build-loop/state.json.triggers`, and Phase 4 EXECUTE consults them before dispatching each subagent.
+
+**pyramid-principle** (structured writing)
+
+Fires whenever the build produces user-visible prose or professional writing. Even small text should follow pyramid structure, and the logical ordering principle applies to design flow too.
+
+Trigger if any of:
+
+- Task touches user-visible text inside the app: copy, microcopy, empty-state messages, error messages, onboarding flow, help content, tooltips, toasts, form labels, email templates, notification text.
+- Task creates or edits: `README.md`, `CHANGELOG.md`, `docs/**/*.md`, PR descriptions, release notes, design docs, status updates, exec summaries, handoff documents.
+- Goal contains: "write", "draft", "summarize", "document", "one-pager", "brief", "memo", "deck", "slides", "presentation", "status update".
+- Designing information architecture or section ordering: use the pyramid logic for top-down flow (governing thought, then MECE key lines, then support).
+
+Action: load `pyramid-principle:pyramid-principle-core` first for ground rules, then the specific skill matching length and format. If absent, use `fallbacks.md#structured-writing`.
+
+**prompt-builder** (prompt authoring or audit)
+
+Fires when prompts are a core part of the product, not when prompts appear incidentally in code comments or test fixtures.
+
+Trigger if any of:
+
+- Building or editing prompts that the app sends to an LLM at runtime: document-generation prompts (Example App style), chat-with-user system prompts, voice-interaction prompts (example app style), reranker prompts, eval-judge prompts.
+- Robust agent or prompt pipeline present in the product: multi-step prompts, RAG, tool-use flows.
+- Semantic search over user queries: use `prompt-builder` to revise the query before embedding or retrieval.
+- Authoring a new agent's instructions (the body of an `agents/*.md` file serving as LLM guidance).
+- File signals: `prompts/`, `system-prompt.*`, strings passed to `messages[{role:"system"}]`, `anthropic.messages.create`, `openai.chat.completions.create`, prompt templates in `.prompt` or `.txt` held as product assets.
+- Goal contains: "system prompt", "agent prompt", "prompt engineering", "rewrite this prompt", "improve this prompt", "audit prompts", "eval judge".
+
+Existing prompt guardrail: if the task touches an **existing** in-product prompt (not a new one), pause and ask the user before running `prompt-builder`. Prompts are often tuned against real evals; silent rewrites can regress quality. Offer the option, do not auto-apply.
+
+Action: load `prompt-builder:prompt-builder` (plugin) if installed, else the personal `prompt-builder` skill, else `fallbacks.md#prompt`. For existing-prompt edits, capture before-and-after in `.build-loop/prompts/` with version suffixes so regressions are detectable.
+
+**building-with-deepagents** (DeepAgents / local-LLM agent work)
+
+Fires whenever the project uses the open-source `deepagents` package. DeepAgents has subtle API shape (SubAgent dict, middleware stack, per-agent tool scoping) that makes hand-rolled focus modes and flat-tool-list designs silently wrong — small local models exhibit tool-call hallucinations in ways that scoping fixes and prompt injection doesn't.
+
+Trigger if any of:
+
+- Repo grep: `from deepagents` or `import deepagents` in any Python source file
+- `deepagents` in `pyproject.toml`, `requirements*.txt`, `uv.lock`, or `poetry.lock`
+- Goal mentions: "agent", "sub-agent", "subagent", "planner/researcher/writer", "focus mode", "tool-call hallucination", "LangGraph agent", "ChatOllama", "local LLM agent"
+- File signals: `create_deep_agent`, `SubAgent`, `AGENT_ROLES`, `agent_focus_prompt`
+- Pain symptoms in the conversation: "`<namespace>.<tool>` is not a valid tool", "silent thinking", "model loaded forever", "threads vanish on restart"
+
+Existing-agent guardrail: treat agent definitions like existing prompts — pause before rewriting, capture before-and-after in `.build-loop/agents/` with version suffixes. Tool scoping changes downstream behavior for every query; regressions are expensive to spot.
+
+Action: load `build-loop:building-with-deepagents` before any code edit involving agent construction, tool binding, or streaming. The skill's `references/anti-patterns.md` lists 12 concrete bugs we've hit — verify none of your planned changes reintroduce them.
+
+**Judgment: prompt-builder vs inline prompt**
+
+Not every prompt needs the full engine. Use `prompt-builder` when the prompt is load-bearing. Craft a simple inline prompt when it is throwaway.
+
+Use `prompt-builder` when any of these are true:
+
+- The prompt ships in the product and runs at scale.
+- The prompt is sent to end users or generates user-visible output.
+- The prompt is part of an agent, eval judge, RAG pipeline, or semantic-search query rewriter.
+- Output correctness is measured (evals exist or are planned).
+- The prompt will be reused across features, or maintained over time.
+- Token cost matters because it runs millions of times.
+
+Roll your own inline prompt when all of these are true:
+
+- One-shot usage inside the current build loop (dispatching a subagent, asking Claude to transform a file, generating a migration script).
+- Not persisted to the product codebase.
+- Output is checked once by the orchestrator, not by an eval.
+- A short direct instruction is clearer than a 6-Part Stack.
+
+Default when uncertain: if the prompt text will exist in the repo after the build, use `prompt-builder`. If it only exists as a line in an orchestrator message during this build, inline is fine.
+
+### Plugin / hook / skill / agent work — mandatory
+
+If Phase 1 detects that the task touches plugin components, Phase 3 must map each task to the authoritative skill below and Phase 4 must load that skill. **Do not infer plugin formats from memory or by reading another plugin's config.**
+
+| Task surface | Skill (authoritative) | Fallback |
+|---|---|---|
+| `.claude-plugin/plugin.json` | `plugin-dev:plugin-structure` | Read `RossLabs-AI-Toolkit/LESSONS-LEARNED.md` — paths must start with `./` |
+| `hooks/hooks.json` or hook scripts | `plugin-dev:hook-development` + run `plugin-dev/scripts/hook-linter.sh` | Command hooks default; Stop stdout must be valid JSON; advisory/non-blocking unless an explicit safety/security/integrity gate opts into blocking; NO prompt hooks on PostToolUse/Stop/SessionStart |
+| Slash commands (`commands/*.md`) | `plugin-dev:command-development` | — |
+| Subagents (`agents/*.md`) | `plugin-dev:agent-development` + `RossLabs-AI-Toolkit/agents/` | `fallbacks.md#agent-authoring` |
+| MCP servers (`.mcp.json`) | `plugin-dev:mcp-integration` | `.mcp.json` must NOT wrap with `mcpServers` key (Method 1) |
+| `~/.claude/settings.json` | `plugin-dev:plugin-settings` | — |
+| New skill (SKILL.md) | `plugin-dev:skill-development` + `skill-builder` (personal) | Official skill format; SKILL.md ≤200 lines |
+| New plugin end-to-end | `plugin-builder` (personal) → delegates into `plugin-dev:*` | — |
+
+### External knowledge — check before coding
+
+| Source | When | How |
+|---|---|---|
+| `/cookbook` | Claude API patterns: tool calling, PTC, code execution, Agent SDK, RAG, thinking, structured output, batch, caching | Invoke `/cookbook` or read `~/.claude/projects/-Users-tyroneross/memory/reference_claude_cookbook.md` |
+| `RossLabs-AI-Toolkit/LESSONS-LEARNED.md` | Any plugin work | Read during Phase 1 ASSESS |
+| `context7` MCP | Any library/framework use | `query-docs` / `resolve-library-id` — do NOT code from training data |
+| `research` skill | Factual claims, pricing, versions | Run `scripts/research_trigger.py` first; T1 official docs → T4 forums; 2-source minimum |