oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-market/resources/output-laws.md

@@ -0,0 +1,53 @@
+# Output LAWs — oma-market
+
+The upstream `last30days` engine owns the output contract: it emits the badge
+as the first line of `--emit=compact` output and its SKILL.md defines LAWs
+1–8 (no `Sources:` block, no invented title, no em/en-dash, no `##` headers in
+a GENERAL-query body, inline `[name](url)` citations, engine footer, …). Read
+them there — they are the authority and change with each release.
+
+This file lists only the oma-side obligations that sit on top.
+
+## O1 — Pass the engine's structure through
+
+Badge first line, cluster structure, and footer come from the engine. Do not
+re-title, re-section, or reorder them. Framework sections are appended
+**after** the engine body and **before** nothing else — the engine footer stays
+last only if the upstream contract says so; otherwise place frameworks after
+the footer under the exact headers `## SWOT`, `## Porter's Five Forces`,
+`## PESTEL` (these `##` headers are the one sanctioned exception to LAW 4, as
+COMPARISON sections already are upstream).
+
+## O2 — Frameworks cite clusters, never invent
+
+Every framework cell references a cluster or representative that exists in
+the engine output, as `[name](url)`. Missing URL → plain text, never `[name]()`.
+
+## O3 — Coverage transparency
+
+If the engine footer or stderr lists skipped / failed sources, keep that list
+visible in the brief and say it in the chat summary.
+
+## O4 — One brief, one date
+
+`.agents/results/market/{topic-slug}-{YYYYMMDD}.md`. Same-day rerun overwrites.
+
+## O5 — Personal-data refuse
+
+Refuse research that targets a private individual's personal data before
+running the engine. Founders, creators, and public handles are allowed
+(upstream person mode).
+
+## Self-check (after writing the draft)
+
+```bash
+# Write the candidate brief first; these checks read its actual bytes.
+f=".agents/results/market/<slug>-<date>.md"
+head -1 "$f" | grep -q '^🌐 last30days v'          || echo "FAIL: badge not first line"
+grep -nE '—|–' "$f"                               && echo "FAIL: em/en-dash"
+grep -niE '^(Sources|References|Citations):' "$f" && echo "FAIL: sources block"
+grep -nE '\[[^]]+\]\(\)' "$f"                     && echo "FAIL: empty citation"
+```
+
+Check the newly written draft, not an older output at the same path. Fix and re-check until clean; do not deliver a brief that fails the badge or
+empty-citation checks.

package/skills/oma-mobile/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: oma-mobile
+description: Implement Flutter, React Native, native Swift, or native Kotlin
+  Android apps. Use for mobile screens, widgets, platform integrations, and
+  application data flows.
+---
+
+# Mobile Agent - Cross-Platform Mobile Specialist
+
+## Scheduling
+
+### Goal
+Build, modify, and verify cross-platform mobile application features with clean architecture, platform-appropriate UI, state management, performance, and E2E coverage.
+
+### Intent signature
+- User asks for mobile app, Flutter, Dart, React Native, iOS, Android, Jetpack Compose, Kotlin, Riverpod, widgets, camera, GPS, push notifications, or offline-first work.
+- User needs native or cross-platform mobile behavior rather than web frontend work.
+
+### When to use
+- Building native mobile applications (iOS + Android)
+- Mobile-specific UI patterns
+- Platform features (camera, GPS, push notifications)
+- Offline-first architecture
+
+### When NOT to use
+- Web frontend -> use Frontend Agent
+- Backend APIs -> use Backend Agent
+
+### Expected inputs
+- Target screen, widget, feature, platform capability, or mobile flow
+- Existing app architecture, state management pattern, API contract, and platform constraints
+- Test expectations for unit, widget, integration, or Maestro E2E coverage
+
+### Expected outputs
+- Mobile code changes in domain, data, presentation, platform, or test files
+- UI aligned with Material Design 3 and iOS HIG as applicable
+- Verification results from mobile checks and critical-flow tests
+
+### Dependencies
+- Flutter/Dart, React Native, Swift, or Kotlin/Gradle toolchain as detected from the project
+- Riverpod/Bloc, Dio, Hilt, Ktor, platform SDKs, and Maestro where applicable
+- `resources/execution-protocol.md`, examples, snippets, checklist, and screen template
+
+### Control-flow features
+- Branches by platform, state management pattern, offline requirement, native permission, and test level
+- Reads and writes mobile codebase files
+- May call build, test, simulator, emulator, or E2E commands
+
+## Structural Flow
+
+### Entry
+1. Identify target platform(s), screen/feature, architecture layer, and state boundary.
+2. Inspect existing mobile patterns and dependencies.
+3. Determine test level and verification environment.
+
+### Scenes
+1. **PREPARE**: Load app architecture, platform constraints, and acceptance criteria.
+2. **ACQUIRE**: Read existing widgets/screens, providers/blocs, API clients, and tests.
+3. **ACT**: Implement mobile UI, state, platform integration, offline handling, and tests.
+4. **VERIFY**: Run relevant unit/widget/integration/E2E checks.
+5. **FINALIZE**: Report behavior, platforms covered, and verification results.
+
+### Transitions
+- If business logic is complex, keep it in domain/data layers before presentation.
+- If network calls are needed, use the variant transport (Dio / axios / generated Swift `Client` / generated Kotlin `*Api` over Ktor) with interceptors and offline handling.
+- If a critical user flow changes, add or update Maestro E2E coverage.
+- If backend contracts are missing, coordinate with backend/API work.
+
+### Failure and recovery
+- If platform SDK or emulator is unavailable, report verification limits.
+- If a permission or native capability is missing, add explicit platform configuration or document blocker.
+- If tests fail, fix before handoff or report the failing check.
+
+### Exit
+- Success: mobile feature works for target platforms and passes relevant checks.
+- Partial success: platform, simulator, dependency, or verification gaps are explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Inspect mobile architecture | `READ` | Domain/data/presentation files |
+| Select state and platform strategy | `SELECT` | Riverpod/Bloc and platform constraints |
+| Implement mobile code | `WRITE` | Widgets, screens, providers, clients |
+| Validate lifecycle and permissions | `VALIDATE` | Dispose, permissions, offline behavior |
+| Call verification tools | `CALL_TOOL` | Tests, builds, Maestro |
+| Report result | `NOTIFY` | Final summary |
+
+### Tools and instruments
+- Flutter/Dart, React Native, Swift, or Kotlin Android stack
+- Riverpod/Bloc, Dio, Hilt, Ktor, platform SDKs, Maestro
+- Unit, widget, integration, and E2E test commands
+
+### Canonical workflow path
+Use the configured code-intelligence provider to locate files and inspect symbols
+or content. For Serena, use `find_file`, `search_for_pattern`,
+`get_symbols_overview`, and `find_symbol`. Native search is limited to the
+provider exclusions and non-code paths permitted by the project's search policy.
+
+
+Then run the project's mobile verification commands, typically unit/widget tests and Maestro E2E for critical flows.
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `CODEBASE` | Mobile source, tests, platform config |
+| `LOCAL_FS` | Templates, snippets, resources |
+| `PROCESS` | Build, test, emulator, simulator, E2E commands |
+| `NETWORK` | Backend APIs when the feature integrates remotely |
+
+### Preconditions
+- Target mobile feature and platform scope are identifiable.
+- Required SDKs, permissions, and API contracts are available or assumptions are stated.
+
+### Effects and side effects
+- Mutates mobile source, tests, and platform configuration.
+- May affect permissions, app lifecycle, offline data, or performance.
+
+### Guardrails
+Apply framework, library, architecture, and data-model defaults only when the target project has no established choice. Scoped edits do not authorize a stack migration or unrelated infrastructure.
+1. Clean Architecture: domain -> data -> presentation
+2. Riverpod/Bloc for state management (no raw setState for complex logic)
+3. Material Design 3 (Android) + iOS HIG (iOS)
+4. All controllers disposed in `dispose()` method
+5. Use the platform transport with auth/retry/logging interception and offline handling: Flutter uses Dio, React Native uses axios behind TanStack Query, Swift uses generated `Client` middleware, and Kotlin uses Ktor plugins on the generated `*Api` client.
+6. 60fps target; verify supported target platforms (Swift iOS needs iOS only; Kotlin Android needs Android only)
+7. Use Maestro for E2E testing of critical user flows
+8. Swift native: SwiftUI + `@MainActor @Observable` view models (Observation framework, iOS 17+) — non-isolated VMs mutating observed state from a `Task` are a Swift 6 strict-concurrency error
+9. Swift native: use the existing API layer. When the project adopts OpenAPI generation, use its generated Client for covered endpoints; a UI-only edit does not introduce a generator.
+10. Swift native: when response caching is required, use the existing Repository cache; for a new hyperoslo/Cache implementation, use a ResponseCache actor — cache DECODED models (never `HTTPBody`), serve stale-while-revalidate on reads, invalidate keys on writes; view models depend on a protocol seam, not the concrete service (see `variants/swift-ios/snippets.md` §10)
+11. Swift native: follow `App/Core/Features/Shared` project layout
+12. Swift native: iOS Human Interface Guidelines for all UI decisions
+13. Swift native: XCTest or Swift Testing for units, XCUITest for critical flows; cancel work via structured `.task {}` (auto-cancels on disappear) — never in `deinit`, which is nonisolated and cannot touch `@MainActor` state under Swift 6 (isolated deinit requires Swift 6.2+)
+14. Swift native: restore edge swipe-back at the route layer — nav-bar-hidden screens (`.toolbar(.hidden, for: .navigationBar)`) lose it, so register push routes via a `swipeBackDestination` wrapper, not per-screen (see `variants/swift-ios/snippets.md` §9)
+15. Flutter: when offline response caching is required, use the existing repository cache; if adding Drift, read cached entities then revalidate (stale-while-revalidate), and invalidate/refresh affected rows on every write; cache decoded entities at the data layer, never at the Dio transport (see `variants/flutter/snippets.md` §3, §10)
+16. React Native: preserve the existing server-state layer; for TanStack Query with explicit `staleTime`/`gcTime` — invalidate affected query keys on every mutation, persist account-scoped cache to MMKV only when offline persistence is required; screens consume query/mutation hooks, never call axios directly (see `variants/react-native/snippets.md`)
+17. Kotlin native: Jetpack Compose + `@HiltViewModel` exposing one `StateFlow<UiState>` collected with `collectAsStateWithLifecycle`; network work in `viewModelScope`, `CancellationException` always rethrown
+18. Kotlin native: use the existing API layer. When the project adopts OpenAPI generation (`org.openapi.generator`, `kotlin` / `jvm-ktor`), call the generated `*Api` for covered endpoints and keep the Ktor engine (OkHttp on device, `MockEngine` in tests) injected where the client is constructed — Ktor is an engine-agnostic layer, not an OkHttp replacement; a UI-only edit does not introduce a generator (see `variants/kotlin-android/snippets.md` §1, §3)
+19. Kotlin native: when response caching is required, use the existing repository cache; for a new Room implementation cache DECODED models with explicit TTL, stale-while-revalidate on reads, upsert/delete on writes — never OkHttp `Cache` or Ktor `HttpCache`; view models depend on an interface seam, not the concrete repository (see `variants/kotlin-android/snippets.md` §8)
+20. Kotlin native: follow the `app/{ui,data,di}` + `api-client` layout; type-safe Navigation Compose routes; Material Design 3; JUnit + `ktor-client-mock` contract tests, Compose UI tests or Maestro for critical flows
+
+## References
+- Execution steps (follow for the selected task): `resources/execution-protocol.md`
+- Code snippets (Swift): `variants/swift-ios/snippets.md`
+- Code snippets (Kotlin Android): `variants/kotlin-android/snippets.md`
+- Code snippets (Flutter): `variants/flutter/snippets.md`
+- Code snippets (React Native): `variants/react-native/snippets.md`
+- Checklist (run before handoff): `resources/checklist.md`
+- Error recovery: `resources/error-playbook.md`
+- Tech stack index (all platforms): `resources/tech-stack.md`
+- Tech stack (Swift): `variants/swift-ios/tech-stack.md`
+- Tech stack (Kotlin Android): `variants/kotlin-android/tech-stack.md`
+- Tech stack (Flutter): `variants/flutter/tech-stack.md`
+- Tech stack (React Native): `variants/react-native/tech-stack.md`
+- Screen template (Flutter): `resources/screen-template.dart`
+- Screen template (Swift): `resources/screen-template.swift`
+- Screen template (React Native): `resources/screen-template.tsx`
+- API service template (Swift): `variants/swift-ios/api-template.swift`
+- API service template (Kotlin Android): `variants/kotlin-android/api-template.kt`
+- API service template (Flutter): `variants/flutter/api-template.dart`
+- API service template (React Native): `variants/react-native/api-template.ts`
+- Variant registry: `variants/README.md`
+- Context loading: `../_shared/core/context-loading.md`
+- Clarification: `../_shared/core/clarification-protocol.md`
+- Context budget: `../_shared/core/context-budget.md`
+- Lessons learned: `../_shared/core/lessons-learned.md` (matching prior failure or requested retrospective)
+- Observability handoff: `../oma-observability/SKILL.md` §Integrations — offline queuing, crash analytics, battery-aware sampling

package/skills/oma-mobile/resources/checklist.md

@@ -0,0 +1,77 @@
+# Mobile Agent - Self-Verification Checklist
+
+Run through every item before submitting your work.
+
+## Architecture
+- [ ] Clean Architecture layers: domain -> data -> presentation (App/Core/Features/Shared on Swift; `app/{ui,data,di}` + `api-client` on Kotlin)
+- [ ] Entities/models are framework-free (pure Dart / plain TS types / plain Swift structs / plain Kotlin data classes)
+- [ ] Repository pattern with interface + implementation (RN: TanStack Query hooks are the repository layer)
+- [ ] Variant state solution used (Flutter: Riverpod/Bloc; RN: Zustand + TanStack Query; Swift: `@MainActor @Observable`; Kotlin: `@HiltViewModel` + `StateFlow`) — no ad-hoc state for complex logic
+
+## Platform
+- [ ] Material Design 3 for Android
+- [ ] iOS Human Interface Guidelines followed
+- [ ] Platform-specific code guarded (Flutter: `Platform.isIOS`/`Platform.isAndroid`; RN: `Platform.OS`)
+- [ ] Tested on supported target platforms (iOS only for native Swift; Android only for native Kotlin)
+- [ ] Dark mode supported
+
+## Performance
+- [ ] 60fps scrolling (no jank)
+- [ ] Controllers disposed in `dispose()` method
+- [ ] No memory leaks (listeners, subscriptions cleaned up)
+- [ ] Images cached and sized appropriately
+- [ ] Cold start < 2s
+
+## API Integration
+- [ ] Transport client with interceptors for auth/error handling (Flutter: Dio; RN: axios; Swift: generated Client middleware; Kotlin: Ktor plugins on the generated `*Api` client)
+- [ ] Loading states shown during API calls
+- [ ] Error states with retry action
+- [ ] Offline handling (graceful degradation or offline-first)
+- [ ] Tokens/secrets in secure storage (flutter_secure_storage / Keychain / react-native-keychain / Android Keystore-backed storage) — never plain prefs or MMKV
+
+## Testing
+- [ ] Unit tests for domain logic and providers
+- [ ] Widget tests for key screens
+- [ ] E2E tests with Maestro for critical user flows
+- [ ] Edge cases: empty lists, error states, offline mode
+- [ ] Applicable tests pass on supported target platforms
+
+## React Native
+> Applies when `package.json` declares a `react-native` dependency. Skip for Flutter/Swift native.
+- [ ] Server state via TanStack Query hooks (query key factory shared between queries and mutations); screens never import axios directly
+- [ ] Explicit `staleTime`/`gcTime` on queries; `gcTime` >= persister `maxAge` so the MMKV-persisted cache survives restarts
+- [ ] Every mutation invalidates affected query keys (list AND detail); optimistic updates roll back on error and never fabricate cache entries
+- [ ] `onlineManager` wired to NetInfo so offline pause/resume works
+- [ ] Client state (auth/UI) in Zustand stores under `src/store/`; tokens hydrated from `react-native-keychain`, held in memory — never plain MMKV
+- [ ] Typed React Navigation v7 routes (`RootStackParamList`); no `any` in navigation props
+- [ ] `npx tsc --noEmit` and `npx jest --ci` pass
+- [ ] Maestro flow updated for critical user flows (`e2e/`)
+
+## Swift Native (iOS)
+> Applies when the project is Swift native (`Package.swift` / `.xcodeproj` present). Skip for Flutter/RN.
+- [ ] `App/Core/Features/Shared` layout respected (App = entry/DI, Core = networking/generated client, Features = view+`@Observable` VM slices, Shared = reusable UI/util)
+- [ ] API access goes through the generated `Client` from `swift-openapi-generator` — no hand-rolled `URLRequest`/`JSONDecoder` for spec-covered endpoints
+<!-- oma-docs:ignore-start -->
+- [ ] OpenAPI document present at `Core/Networking/openapi.yaml` and synced from the backend before build
+<!-- oma-docs:ignore-end -->
+- [ ] SwiftUI state via `@MainActor @Observable` (Observation framework); async work cancelled via structured `.task {}` (not `deinit` — see `variants/swift-ios/snippets.md`)
+- [ ] Loading / error (with retry) / empty / data states handled in views
+- [ ] iOS Human Interface Guidelines followed
+- [ ] Push routes registered via a `swipeBackDestination` wrapper (not bare `navigationDestination`), so nav-bar-hidden screens keep edge swipe-back; guarded pops (unsaved edits) override explicitly — see `variants/swift-ios/snippets.md` §9
+- [ ] Run build/generation only when the user explicitly requested a build. Otherwise perform authorized checks without triggering compilation and report verification limits; do not run swift test when it would require a prohibited build.
+- [ ] XCTest/XCUITest coverage for critical flows
+
+## Kotlin Native (Android)
+> Applies when the project is Kotlin native (`settings.gradle.kts` + `com.android.application` plugin, no `pubspec.yaml` / `react-native`). Skip for Flutter/RN/Swift.
+- [ ] `app/{ui,data,di}` + `api-client` layout respected (ui = Compose screens + `@HiltViewModel` slices, data = repositories/Room/failures, di = Hilt modules, api-client = generated srcDir + shared `Json` + contract tests)
+- [ ] API access goes through the generated `*Api` from `openapi-generator` (`kotlin` / `jvm-ktor`) — no hand-assembled URL paths or JSON bodies for spec-covered endpoints
+- [ ] Ktor engine is injected where the `*Api` is constructed (OkHttp in the app's Hilt module, `MockEngine` in tests) — repositories and composables never reference an engine
+- [ ] Shared `Json` codec registers the `BigDecimal` contextual serializer and is the same instance in DI and contract tests
+- [ ] `preBuild` depends on `openApiGenerate`; generated sources under `build/generated/openapi` are never committed or hand-edited
+- [ ] Compose state via `collectAsStateWithLifecycle` on a single `StateFlow<UiState>`; network work lives in `viewModelScope`, never `GlobalScope`
+- [ ] Loading / error (with retry) / empty / data states handled in composables; `CancellationException` is rethrown, never swallowed
+- [ ] Material Design 3 followed; dark theme and dynamic color honoured
+- [ ] Type-safe Navigation Compose routes (`@Serializable` + `composable<Route>`); screens receive callbacks, not the `NavController`
+- [ ] When caching is required: Room repository caches DECODED models with explicit TTL, stale-while-revalidate on reads, upsert/delete on writes — never OkHttp `Cache` or Ktor `HttpCache` (see `variants/kotlin-android/snippets.md` §8)
+- [ ] Run Gradle test/compile tasks only when the user explicitly authorised a build or test run; otherwise report the verification limit
+- [ ] `:api-client:test` contract test exercises the generated client against `MockEngine`; Compose UI test or Maestro flow for critical flows

package/skills/oma-mobile/resources/error-playbook.md

@@ -0,0 +1,198 @@
+# Mobile Agent - Error Recovery Playbook
+
+When you encounter a failure, find the matching scenario and follow the recovery steps.
+Use the relevant recovery steps. If required information or authority is missing, pause the dependent action and continue independent work.
+
+---
+
+## Dart Analysis Error
+
+**Symptoms**: `flutter analyze` errors, type mismatch, null safety issues
+
+1. Read the error: file, line, expected type vs actual
+2. Null safety issue: add `?` for nullable, `!` only if you're certain it's non-null
+3. Type mismatch: check the model class to see if it matches the API response
+4. Missing override: add `@override` annotation
+5. **NEVER do this**: `// ignore:` comments to suppress analysis warnings
+
+---
+
+## Build Failure
+
+**Symptoms**: `flutter build` fails, Gradle/Xcode errors
+
+1. **Gradle (Android)**:
+   - `Could not resolve`: dependency version conflict → check `pubspec.yaml`
+   - `minSdkVersion`: update `android/app/build.gradle` minimum SDK
+2. **Xcode (iOS)**:
+   - `Pod install` failure: note in result; may need `pod repo update`
+   - Minimum deployment target: check `ios/Podfile`
+3. Clean and retry: `flutter clean && flutter pub get`
+4. If persists: note in result with full error; may be an environment issue
+
+---
+
+## Test Failure
+
+**Symptoms**: `flutter test` FAILED, widget test assertion errors
+
+1. Read the error: which test, which widget, expected vs actual
+2. Widget test: check if `pumpAndSettle()` is needed (async operations)
+3. Provider not found: wrap test widget with `ProviderScope` (Riverpod)
+4. Mock missing: ensure all dependencies are mocked
+5. Re-run specific test: `flutter test test/path/to_test.dart`
+6. **After 3 failures**: Try a different approach
+
+---
+
+## State Management Issue
+
+**Symptoms**: UI not updating, stale state, provider errors
+
+1. **Riverpod**: Check provider type (`StateNotifierProvider` vs `FutureProvider` vs `AsyncNotifierProvider`)
+2. Is the widget watching correctly? (`ref.watch` not `ref.read` for UI)
+3. Is the state being mutated instead of replaced? (create new state object)
+4. Add debug print in provider to trace state changes
+5. Check: is `dispose` being called prematurely?
+
+---
+
+## Platform-Specific Crash
+
+**Symptoms**: Works on one platform, crashes on another
+
+1. Check for `Platform.isIOS` / `Platform.isAndroid` guards
+2. Check permissions: camera, location, storage (different per platform)
+3. Check native plugin compatibility; some plugins don't support both platforms
+4. If plugin issue: note in result with platform and version info
+5. Test on emulator for the failing platform
+
+---
+
+## Memory Leak
+
+**Symptoms**: App slows down over time, `flutter run` shows increasing memory
+
+1. Check: are all controllers disposed? (`TextEditingController`, `AnimationController`)
+2. Check: are streams closed? (`StreamSubscription.cancel()`)
+3. Check: are listeners removed? (`removeListener` in `dispose`)
+4. Check: are `Timer` / `Timer.periodic` cancelled?
+5. Use `DevTools` memory tab to identify leak source
+
+---
+
+## API Integration Error
+
+**Symptoms**: Dio errors, `DioException`, wrong response parsing
+
+1. **Connection refused**: backend running? correct URL/port?
+2. **401**: auth interceptor sending token? token expired?
+3. **Parse error**: `response.data` shape doesn't match model → log raw response
+4. **Timeout**: increase Dio timeout or check network conditions
+5. If backend issue: document expected contract in result
+
+---
+
+## React Native: Metro / Build Failure
+
+**Symptoms**: Metro bundler errors, `Unable to resolve module`, pod install failures, Gradle errors
+
+1. **Unable to resolve module**: check the import path and `tsconfig.json`/`babel.config.js` path aliases (`@api`, `@store`, ...) agree; then `npx react-native start --reset-cache`
+2. **iOS pod failure**: `cd ios && pod install --repo-update`; New Architecture (0.76+) requires up-to-date pods for Nitro/TurboModules (e.g., react-native-mmkv v4 needs RN 0.76+)
+3. **Gradle failure**: check `android/build.gradle` versions match the RN release template; clean with `cd android && ./gradlew clean`
+4. **Native module mismatch after upgrade**: rebuild the app binary — JS-only reload cannot load new native modules
+5. If persists: note in result with full error; may be an environment issue
+
+---
+
+## React Native: TypeScript / Test Failure
+
+**Symptoms**: `npx tsc --noEmit` errors, jest failures, RNTL matcher errors
+
+1. Read the error: file, line, expected vs actual type
+2. Navigation typing: screens must use the typed props from `RootStackParamList` — never `any`
+3. Matcher not found (`toBeOnTheScreen` etc.): matchers are built into `@testing-library/react-native` ≥12.4 — remove any `@testing-library/jest-native` residue from jest setup
+4. Query hook tests: wrap in a fresh `QueryClientProvider` per test (`retry: false`); async UI needs `await screen.findBy...`, not `getBy...`
+5. **NEVER**: `@ts-ignore` / `as any` to silence type errors
+
+---
+
+## React Native: Stale Cache / Offline Issues
+
+**Symptoms**: UI shows old data, mutations don't refresh lists, cache gone after restart
+
+1. Mutation missing invalidation? Every mutation must invalidate the affected query keys (list AND detail) via the shared key factory
+2. Cache not surviving restart: `gcTime` must be >= the persister's `maxAge` (default 24h); a short `gcTime` lets GC prune entries from the persisted MMKV snapshot
+3. Offline behavior dead: confirm `onlineManager.setEventListener` is wired to NetInfo — RN has no default online detection
+4. Optimistic update ghosts: `setQueryData` must return `old` unchanged when the cache entry is absent — never fabricate `[]`
+5. Persisted schema drift after model changes: bump the persister `buster` string to drop the old snapshot
+
+---
+
+## Rate Limit / Quota / Memory Fallback
+
+Same as the backend playbook: see `../../oma-backend/resources/error-playbook.md` §"Rate Limit / Quota Error (LLM runtime)" and the configured code-intelligence or memory fallback guidance.
+
+---
+
+## Swift: `swift build` Fails — Missing or Invalid OpenAPI Document
+
+**Symptoms**: Build error from the `swift-openapi-generator` plugin such as `error: openapi.yaml not found` or YAML parse error; the build fails before any Swift file is compiled.
+
+<!-- oma-docs:ignore-start -->
+1. Confirm the spec exists at `Core/Networking/openapi.yaml` — this is where the build plugin looks.
+<!-- oma-docs:ignore-end -->
+2. If the file is absent: re-sync it from the backend (`curl -o Sources/Core/Networking/openapi.yaml https://<backend>/api-docs/openapi.yaml` or copy from the CI artifact). The iOS project is a **consumer** of the spec; never edit `openapi.yaml` directly.
+3. If the file is present but the error is a parse error: validate the YAML (`python3 -c "import yaml, sys; yaml.safe_load(open(sys.argv[1]))" Sources/Core/Networking/openapi.yaml`); fix the upstream spec and re-sync.
+4. After syncing, `swift build` will regenerate `Client`, `Operations`, and `Components` automatically — no manual code-gen step needed.
+5. **NEVER**: commit a placeholder or empty `openapi.yaml` just to silence the build; it will produce an incomplete `Client` and cause compile errors downstream.
+
+---
+
+## Swift: Generated `Client`/`Operations` Symbols Not Found
+
+**Symptoms**: Compile errors such as `cannot find type 'Client' in scope` or `use of unresolved identifier 'Operations'`; the generator plugin appears not to have run.
+
+1. Confirm the build plugin is attached in `Package.swift`:
+   - The target must list `.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")` under its `plugins:` key.
+   - The target's dependencies must include `OpenAPIRuntime` and `OpenAPIURLSession`.
+2. Confirm `openapi-generator-config.yaml` exists **in the same directory** as `openapi.yaml` (`Core/Networking/`). Without this file the plugin silently skips generation.
+3. Check that both config files are inside the target's declared source directory (the directory that contains the `.target` in `Package.swift`). Files outside the source root are invisible to the build plugin.
+4. Run `swift package clean && swift build` to force a full regeneration.
+5. If Xcode is used: Product → Clean Build Folder, then build again. Derived data caching sometimes hides generation failures.
+
+---
+
+## Swift: Compile Error for Undocumented Response Case
+
+**Symptoms**: Compile error such as `expression pattern of type 'Operations.CreateTodo.Output.conflict' cannot match values of type '...'`; a response case (e.g., `.conflict`, `.created`, `.unprocessableContent`) referenced in the Swift code does not exist on the generated `Output` enum.
+
+1. The root cause is that the OpenAPI spec does not declare that HTTP status code for the operation. The generator only emits cases for status codes listed in the spec.
+2. Do NOT add the case manually to the generated file — it will be overwritten on the next `swift build`.
+3. Ask the backend team to add the missing status code to the spec (e.g., add `409: description: Conflict` under the operation's `responses:`).
+<!-- oma-docs:ignore-start -->
+4. Re-sync `Core/Networking/openapi.yaml` once the spec is updated.
+<!-- oma-docs:ignore-end -->
+5. Run `swift build` to regenerate; the new response case will appear and the compile error will resolve.
+6. Update the Swift `switch` in the service layer to handle the new case explicitly.
+
+---
+
+## Swift: `@Observable` State Not Updating the SwiftUI View
+
+**Symptoms**: Mutating a property on the view model has no visual effect; the view does not re-render even though the value changed.
+
+1. Confirm the view model class is annotated with `@Observable` (Observation framework, **not** `ObservableObject`). Without the macro the view has no tracking infrastructure.
+2. Check framework availability against supported OS versions. SwiftUI Observation integration requires iOS 17+. Preserve an older target using its supported observation mechanism or availability-gated implementation; changing minimum support requires a product decision.
+3. Check that body reads the observable properties that should trigger an update and that those properties are not @ObservationIgnored. Plain let/var references to @Observable models can be observed. Use @State when the view owns the instance lifetime.
+4. Use @Bindable when the child needs bindings such as $viewModel.title. Passing an observable reference as a plain argument does not prevent property observation or direct mutation.
+5. Confirm properties are mutated on the **main actor**. Mutations from a background `Task` without `await MainActor.run { … }` (or `@MainActor` on the method) can update state off-main and miss the SwiftUI render pass.
+6. When adapting an existing ObservableObject boundary, verify which layer owns and publishes the values read by the view instead of assuming the mechanisms automatically bridge.
+
+---
+
+## General Principles
+
+- **After 3 failures**: If same approach fails 3 times, must try a different method
+- **Blocked**: If no progress after 5 turns, save current state, `Status: blocked`
+- **Out of scope**: Backend/frontend issues; only record in result

package/skills/oma-mobile/resources/execution-protocol.md

@@ -0,0 +1,47 @@
+# Mobile Agent - Execution Protocol
+
+## Preparation
+Use the task's scope, existing project conventions, and acceptance criteria. Follow `../../_shared/core/execution-policy.md` when it has not already been supplied. Read only references needed by the selected operation; consult lessons or recovery guides for an observed issue. Expand planning depth only when the change requires it.
+
+## Step 1: Analyze
+- Read the task requirements carefully
+- Identify target platform: check for `Package.swift` (Swift iOS), `settings.gradle.kts` + `com.android.application` plugin (Kotlin Android), `pubspec.yaml` (Flutter), or `package.json` + `react-native` dep (React Native)
+<!-- oma-docs:ignore-start -->
+- **If Swift (Package.swift detected)**: identify which `Features/` modules are affected; check for `Core/Networking/openapi.yaml`
+<!-- oma-docs:ignore-end -->
+- **If Kotlin Android**: identify which `ui/<feature>` slices are affected; read the `openApiGenerate {}` block in `app/build.gradle.kts` for the spec path and generated packages; find the Hilt module that constructs the generated `*Api` (Ktor engine lives there, not in repositories)
+- **If Flutter**: identify screens, widgets, and Riverpod/Bloc providers
+- **If React Native**: identify screens, query/mutation hooks (`src/features/*/queries.ts`), Zustand stores, and navigation types
+- Explore existing code through the configured `code_intelligence` capability. If it is unavailable or times out, do not native-search feature roots. Native search is only for paths outside this project or ignored paths; record that limit.
+- Determine platform-specific requirements (iOS HIG vs Material Design 3)
+- List assumptions; ask if unclear
+
+## Step 2: Plan
+- **Swift**: plan using `App/Core/Features/Shared` layers; define the `@Observable` view model state enum; identify which `Operations` + `Components` types the feature needs from the generated `Client`
+- **Kotlin Android**: plan using `app/{ui,data,di}`; define the sealed `UiState` the `@HiltViewModel` exposes through `StateFlow`; identify which generated `*Api` operations and `…generated.model` types the feature needs; decide whether a Room-backed repository cache is required
+- **Flutter**: decide on feature structure using Clean Architecture; define entities (domain) and repository interfaces; plan state management (Riverpod providers); identify navigation routes (GoRouter)
+- **React Native**: define the query key factory and query/mutation hooks (TanStack Query = repository layer); decide Zustand store shape for client state; plan typed React Navigation routes; decide persistence needs (MMKV persister, keychain for secrets)
+- Plan offline-first strategy if required
+- Note platform differences (iOS HIG vs Material Design 3)
+
+## Step 3: Implement
+- **Honor the task's `test_approach`** (see `../../_shared/core/test-approach.md`): for `tdd` tasks, write and run the focused test first (record the RED failure), make the minimal change (GREEN), then continue
+- Create/modify files in this order (Flutter shown; Swift maps to Core → Features → Tests, Kotlin to data → di → ui/<feature> → ui/navigation → tests, RN to api → queries/mutations → store → ui → navigation → tests):
+  1. Domain: entities and repository interfaces
+  2. Data: models, API clients (Dio / axios / generated Client / generated `*Api`), repository implementations
+  3. Presentation: providers/hooks/view models, screens, widgets, composables
+  4. Navigation: GoRouter routes / typed React Navigation routes / router-owned NavigationStack / `@Serializable` Navigation Compose routes
+  5. Tests: unit + widget/component tests
+- Use the platform's template as reference: `resources/screen-template.dart` (Flutter), `resources/screen-template.swift` (Swift), `resources/screen-template.tsx` (React Native); Kotlin uses `variants/kotlin-android/snippets.md` §5–§6 (view model + screen)
+- Follow Clean Architecture layers strictly
+
+## Step 4: Verify
+- Check applicable items in `resources/checklist.md`
+- Use `../../_shared/core/common-checklist.md` only for cross-domain verification
+- For `tdd` tasks, append the `TDD_EVIDENCE` block (test command, RED, GREEN) to the result file per `../../_shared/core/test-approach.md`
+- Verify supported target platforms; native Swift iOS does not require Android checks and native Kotlin Android does not require iOS checks. Respect the build policy when selecting tests (Gradle test tasks compile Kotlin).
+- Verify 60fps performance (no jank)
+- Check dark mode support
+
+## On Error
+See `resources/error-playbook.md` for recovery steps.