gracefullight/pkgs / .agents/skills/oma-mobile
oma-mobile
UnverifiedImplement Flutter, React Native, or native Swift apps. Use for mobile screens, widgets, platform integrations, and application data flows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.9 KB |
| resources/checklist.md | markdown | 3.9 KB |
| resources/error-playbook.md | markdown | 10.8 KB |
| resources/execution-protocol.md | markdown | 3.5 KB |
| resources/screen-template.dart | other | 11.0 KB |
| resources/screen-template.swift | script | 8.1 KB |
| resources/screen-template.tsx | other | 5.7 KB |
| resources/tech-stack.md | markdown | 3.8 KB |
| variants/README.md | markdown | 2.0 KB |
| variants/flutter/api-template.dart | other | 18.3 KB |
| variants/flutter/snippets.md | markdown | 41.4 KB |
| variants/flutter/stack.yaml | config | 456 B |
| variants/flutter/tech-stack.md | markdown | 11.4 KB |
| variants/react-native/api-template.ts | script | 16.3 KB |
| variants/react-native/snippets.md | markdown | 30.4 KB |
| variants/react-native/stack.yaml | config | 574 B |
| variants/react-native/tech-stack.md | markdown | 11.2 KB |
| variants/stack.schema.json | config | 2.5 KB |
| variants/swift-ios/api-template.swift | script | 6.8 KB |
| variants/swift-ios/snippets.md | markdown | 35.8 KB |
| variants/swift-ios/stack.yaml | config | 682 B |
| variants/swift-ios/tech-stack.md | markdown | 10.9 KB |
variants/flutter/tech-stack.md
View on GitHub# Mobile Agent - Tech Stack Reference (Flutter)
Starter reference for the selected platform. Preserve existing project choices. The caching implementation below applies only when caching is required; do not add it for an unrelated screen or widget change.
## Framework + State Management
- **Language**: Dart 3.10+
- **UI Framework**: Flutter 3.44+
- **UI Toolkit**: Material Design 3 (Android) + iOS HIG adaptations via `CupertinoAdaptiveTheme` or `Platform.isIOS` guards
- **State Management**: Riverpod 3.x with `@riverpod` code generation (`AsyncNotifier`, `Notifier`, `StreamNotifier`)
- **Concurrency**: Dart async/await, `Stream`, `StreamController`, structured cancellation via `ref.onDispose`
- **Minimum SDK**: Flutter 3.44 / Dart 3.10 / Android API 24 / iOS 16
Riverpod 3.x with `@riverpod` codegen replaces manual `StateNotifierProvider` and hand-written provider constants. The code generator emits typed, cancellation-safe notifier subclasses at build time (`AsyncNotifier` for `Future` builds, `StreamNotifier` for `Stream` builds). Riverpod 3 drops the generated `FooRef` typedefs — provider and notifier build signatures take the unified `Ref` type. Provider state is disposed automatically when the last listener is removed; side-effectful providers use `ref.onDispose` to cancel in-flight requests.
## HTTP / API Client: Dio with Interceptors
| Component | Package |
|-----------|---------|
| HTTP transport | `dio` |
| Auth interceptor | custom `AuthInterceptor` (injects Bearer token) |
| Retry interceptor | custom `RetryInterceptor` (exponential back-off) |
| Logging interceptor | `pretty_dio_logger` (debug builds only) |
Dio is the **transport layer only**. Interceptors handle cross-cutting concerns (auth injection, retry, logging) — they must never cache or interpret domain objects. All Dio interceptors operate on raw `RequestOptions` / `Response` bytes. Domain-level caching belongs exclusively at the Repository layer (see below).
```
Presentation (Riverpod provider)
| calls
v
Repository (data layer) ──reads/writes──► Local Cache (Drift table)
| on miss / revalidate
v
RemoteDataSource (Dio) ──HTTP──► Backend REST API
```
## Response Cache: Offline-First Repository (Drift)
When response caching is required, implement it at the Repository (data) layer, using a Drift database table as the local cache. The cache stores **decoded domain entities** — never raw HTTP bytes or JSON strings. The Dio client and its interceptors are never cache-aware.
**Placement rule — Repository layer, not transport.** Do **not** add a Dio cache interceptor (e.g. `dio_http_cache`, `dio_cache_interceptor`) as the system of record for domain reads. Such interceptors operate on raw bytes, making them invisible to the domain and untestable at the business-logic level. Cache the typed result *after* decoding instead.
```
View (Flutter Widget)
| watches
v
Riverpod StreamNotifier (features/<feature>/presentation/)
| calls
v
Repository interface (features/<feature>/domain/)
| reads/writes (stale-while-revalidate)
+──────────────────► Drift table (local cache of decoded entities)
| on miss / revalidate
v
RemoteDataSource / Dio (features/<feature>/data/)
| HTTP
v
Backend REST API
```
**Mandatory rules:**
1. Every read operation goes through the Repository, which queries Drift first and returns a `Stream` (or `Future`) of cached entities. The Repository then triggers a background network revalidation and upserts the result back into Drift — the stream re-emits automatically.
2. Cache **key** = logical operation ID + a stable hash of its parameters (e.g., `"todos"`, `"todo:$id"`). Never key on URLs or raw path strings.
3. Apply a **stale-while-revalidate** policy: emit the locally-cached rows immediately (instant render), then fetch from the network, upsert into Drift, and let the stream re-emit the fresh rows. Store an explicit `cachedAt` timestamp column; check it against a per-resource TTL before deciding to revalidate.
4. Any **write** (create / update / delete) must upsert or delete the affected Drift rows after a successful network response, so the next stream emission reflects the change immediately without a separate read round-trip.
5. Drift is for transient **server-owned** data caches (and optionally durable user-owned data). **Secrets** (tokens, credentials) still belong in `flutter_secure_storage`. Do not use the cache table as a system of record for user-authored drafts — use a separate Drift table with a different retention policy.
See `snippets.md §3` for the canonical offline-first repository and `snippets.md §4` for the Riverpod `StreamNotifier` consuming it.
## Local Storage
| Library | Purpose |
|---------|---------|
| `drift` | Durable structured persistence (system-of-record user data **and** the offline response cache table) |
| `flutter_secure_storage` | Tokens, credentials, and secrets |
| `shared_preferences` | Lightweight key-value preferences (theme, locale, flags) |
| `hive` / `hive_flutter` | Lightweight alternative to Drift for simple caches where SQL is unnecessary |
**Drift vs Hive for the cache table:** Drift is the default because it provides SQL queries, type-safe DAOs, and Dart `Stream`s that auto-emit on row changes — exactly what the stale-while-revalidate pattern needs. Use Hive when the cached type is a simple flat object and you want to avoid the Drift codegen dependency. Either way, the Repository interface is unchanged; only the impl swaps out. This stack uses Drift (`response_cache: drift-offline-repo`).
## Testing
| Layer | Framework |
|-------|-----------|
| Unit (domain + repository) | `flutter_test` + `mocktail` |
| Widget | `flutter_test` (`WidgetTester`) |
| Integration | `integration_test` package |
| E2E | Maestro (`maestro test`) |
Mock the `Repository` **interface** (abstract class), not the concrete implementation or Dio. `mocktail` stubs are preferred over hand-written fakes for brevity, but both are acceptable. Never mock Drift internals — test the real Drift DB in-memory (`NativeDatabase.memory()`) for repository-layer tests.
Run tests with `flutter test` (unit + widget) and `flutter test integration_test/` (integration). Maestro `.yaml` flow files live in `maestro/` at the project root; see `snippets.md §11` for a runnable launch → add → assert flow.
## Project Layout
```
my_app/
pubspec.yaml # deps + build_runner config
pubspec.lock
build.yaml # build_runner options (riverpod_generator, drift)
maestro/ # Maestro E2E flow files
todos_flow.yaml
lib/
main.dart # runApp entry; ProviderScope at root
core/
di/
providers.dart # App-wide singleton providers (Dio, DB, SecureStorage)
network/
dio_client.dart # Dio factory + AuthInterceptor + RetryInterceptor (all in one file; see §5)
database/
app_database.dart # Drift @DriftDatabase definition
app_database.g.dart # generated
router/
app_router.dart # GoRouter typed routes
app_router.g.dart # generated (go_router_builder)
theme/
app_theme.dart
features/
todos/
domain/
todo.dart # Domain entity (freezed or plain Dart)
todo_repository.dart # Abstract repository interface
data/
dtos/
todo_dto.dart # JSON <-> entity mapping
local/
todos_dao.dart # Drift DAO for todos cache table
todos_dao.g.dart # generated
remote/
todos_remote_data_source.dart # Dio calls
todo_repository_impl.dart # Offline-first impl; cache + remote
presentation/
providers/
todos_provider.dart # @riverpod StreamNotifier
todos_provider.g.dart # generated
screens/
todos_screen.dart
todo_detail_screen.dart
widgets/
todo_list_item.dart
shared/
widgets/
loading_indicator.dart
empty_state.dart
error_view.dart
test/
features/
todos/
todo_repository_impl_test.dart # in-memory Drift DB
todos_provider_test.dart # mocked repository interface
todos_screen_test.dart # WidgetTester
integration_test/
todos_integration_test.dart
```
## Architecture Pattern
```
todos_screen.dart (ConsumerWidget)
| ref.watch(todosProvider)
v
todosProvider (@riverpod StreamNotifier<List<Todo>>)
| ref.watch(todoRepositoryProvider)
v
TodoRepository (abstract interface in domain/)
| watchAll() · findById(id) · create(title) · toggle(id) · delete(id)
| implemented by TodoRepositoryImpl (data/)
|
+──── TodosDao (Drift) ◄──────── local cache of decoded Todo entities
| Stream<List<TodosTableData>> watchAll()
| Future<TodosTableData?> findById(int id)
| Future<void> replaceAll(List<TodosTableCompanion>) // mirrors full server list
| Future<void> upsertOne(TodosTableCompanion)
| Future<void> deleteById(int id)
|
+──── TodosRemoteDataSource (Dio)
Future<List<TodoDto>> fetchAll()
Future<TodoDto> fetchById(int id)
Future<TodoDto> create(String title)
Future<TodoDto> toggle(int id)
Future<void> delete(int id)
```
Each `features/<name>/` folder is a vertical slice owning its domain, data, and presentation sub-layers. `shared/` holds stateless reusable widgets with no feature knowledge. `core/` holds app-wide infrastructure (Dio, Drift DB, GoRouter, DI providers).
The `@riverpod` notifier calls the repository directly — there is no use-case/interactor layer in this stack. Add a `usecases/` class only when a single user action coordinates multiple repositories or carries non-trivial orchestration logic; a straight pass-through to one repository method does not warrant one.
<!-- oma-docs:ignore-start -->
**Sanctioned layering exception (Drift).** `core/database/app_database.dart` imports the feature DAOs (e.g. `features/todos/data/local/todos_dao.dart`) to register them on `@DriftDatabase(daos: [...])`. This is a `core → features` upward import, the reverse of the normal dependency direction. It is the single allowed exception: Drift requires the database class to reference its tables and DAOs for code generation. No other `core` code may import from `features/`.
<!-- oma-docs:ignore-end -->
## Navigation: GoRouter with Typed Routes
<!-- oma-docs:ignore-start -->
`go_router` 17.x with `go_router_builder` (typed route classes generated at build time via `build_runner`) is the navigation layer. Define route classes annotated with `@TypedGoRoute`; the generator emits `.g.dart` files with `push()` / `go()` helpers. `go_router_builder` is a dev-only builder — the `@TypedGoRoute` annotation and `GoRouteData` base class are imported from `package:go_router/go_router.dart`, never from `go_router_builder`.
<!-- oma-docs:ignore-end -->
Route guards (auth checks, onboarding redirects) are handled by `GoRouter.redirect` callbacks, not inside screens. Deep links are declared in `GoRoute.path` and handled by the platform-level `AndroidManifest.xml` / `Info.plist` intent filters.
See `snippets.md §2` for the typed GoRouter setup.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |