/oma-mobile

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