gabrielmoreira 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, 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 or React Native toolchain as detected from the project
- Riverpod/Bloc, Dio, 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
- Identify target platform(s), screen/feature, architecture layer, and state boundary.
- Inspect existing mobile patterns and dependencies.
- Determine test level and verification environment.
Scenes
- PREPARE: Load app architecture, platform constraints, and acceptance criteria.
- ACQUIRE: Read existing widgets/screens, providers/blocs, API clients, and tests.
- ACT: Implement mobile UI, state, platform integration, offline handling, and tests.
- VERIFY: Run relevant unit/widget/integration/E2E checks.
- 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 Dio 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 or React Native stack
- Riverpod/Bloc, Dio, platform SDKs, Maestro
- Unit, widget, integration, and E2E test commands
Canonical workflow path
rg --files
rg "Riverpod|Bloc|Dio|Widget|Maestro|dispose\\(|permission" .
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.
- Clean Architecture: domain -> data -> presentation
- Riverpod/Bloc for state management (no raw setState for complex logic)
- Material Design 3 (Android) + iOS HIG (iOS)
- All controllers disposed in
dispose()method - Use the platform transport with auth/retry/logging interception and offline handling: Flutter uses Dio, React Native uses axios behind TanStack Query, and Swift uses generated
Clientmiddleware. - 60fps target; test on both platforms
- Use Maestro for E2E testing of critical user flows
- Swift native: SwiftUI +
@MainActor @Observableview models (Observation framework, iOS 17+) — non-isolated VMs mutating observed state from aTaskare a Swift 6 strict-concurrency error - Swift native: use the generated
Clientfromswift-openapi-generator— never hand-rollURLRequest/JSONDecoderfor API calls - Swift native: cache API responses at the Repository layer via a
ResponseCacheactor overhyperoslo/Cache— cache DECODED models (neverHTTPBody), serve stale-while-revalidate on reads, invalidate keys on writes; view models depend on a protocol seam, not the concrete service (seevariants/swift-ios/snippets.md§10) - Swift native: follow
App/Core/Features/Sharedproject layout - Swift native: iOS Human Interface Guidelines for all UI decisions
- Swift native: XCTest or Swift Testing for units, XCUITest for critical flows; cancel work via structured
.task {}(auto-cancels on disappear) — never indeinit, which is nonisolated and cannot touch@MainActorstate under Swift 6 (isolated deinit requires Swift 6.2+) - 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 aswipeBackDestinationwrapper, not per-screen (seevariants/swift-ios/snippets.md§9) - Flutter: mandate a repository-layer offline-first cache (Drift) — read cached entities then revalidate (stale-while-revalidate), 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) - React Native: server state goes through TanStack Query (the repository-layer cache) with explicit
staleTime/gcTime— invalidate affected query keys on every mutation, persist the cache to MMKV for offline; screens consume query/mutation hooks, never call axios directly (seevariants/react-native/snippets.md)
References
- Execution steps (follow for the selected task):
resources/execution-protocol.md - Code snippets (Swift):
variants/swift-ios/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 (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 (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