flutter-mobx-kit

Add or change a design-system token — GeistTheme colour, GeistTextStyles text style, GeistRadius, GeistDuration, spacing constant or shadow stack. Covers the static vs theme-aware decision, the six edit points a new colour needs, light+dark pairing, WCAG contrast, Gap spacing, design-system codegen, and consuming tokens from lib/. Use whenever a colour, text style, radius, duration, spacing value or shadow is needed and no token exists.

Add a user-visible string via easy_localization — key naming, where it goes in en-US.json, LocaleKeys codegen, plurals, interpolation, enum-keyed strings, and adding a new locale. Use whenever any text will be rendered to a user, including error messages, semantics labels and accessibility hints.

Add a platform channel between Dart and native iOS (Swift) / Android (Kotlin) — one channel per capability named {app_id}/{capability}, the contract written first and matched on all three sides, the Dart wrapper in lib/core/platform_channels/ that catches PlatformException, tracks it and returns a typed result, native registration and threading, and tests with a mock method-call handler. Use when Flutter needs a native API no maintained plugin covers, or when changing an existing MethodChannel / EventChannel.

Register a screen with AutoRoute — the @RoutePage annotation, router entry, path and naming conventions, route parameters, nested routes, guards, modals and dialogs, and the AppNavigator methods states call. Use when adding a screen to the router, adding a guard, or navigating somewhere new.

Write a new Architecture Decision Record in MADR format — when a decision deserves an ADR versus a playbook edit, numbering, real alternatives with honest trade-offs, and the index/AGENTS.md updates that must follow. Use when introducing, changing or superseding an architectural rule.

Add a Retrofit @RestApi provider in packages/api — the _Paths convention, method annotations, request bodies, queries, multipart, paged envelopes, barrel exports, DioService registration, a request-shape test over a fake HttpClientAdapter, and the interceptor chain (order, no-connection fail-fast, retry with backoff, environment-gated logging). Use when adding a new API resource or endpoint, or an interceptor.

Build a reusable component inside packages/design_system — directory layout, barrel exports, named-constructor variants, shared base widgets, token-only styling, and the app-vs-design-system placement decision. Use when adding or changing a widget in the design system package, or deciding whether a widget belongs there at all.

Create a freezed + json_serializable DTO in packages/api — file location under the owning resource provider, sealed class shape, barrel exports, nullable and default handling, enums, and paginated list responses. Use when adding or changing any *_dto.dart or wiring a new API response type.

Scaffold a new feature module in lib/features/ with the correct directory shape, store, state, page, use-case placement, DI registration, route, localization and tests. Use when adding any new screen-owning feature or promoting a sub-module to a peer feature.

Build a page and its MobX page state — Provider root, context.read access, HookWidget for local state, AppNavigator for navigation, Observer for reactive rebuilds, and the loading/empty/error branches. Use when adding or modifying any screen, modal or route-level widget.

Build a MobX store — @readonly observables, @action mutations, DioService access inline vs through a use case, error tracking, optimistic mutations with rollback, pagination, search and filtering with @computed, the @injectable vs @singleton scope decision, and who disposes what. Use when adding or modifying any *_store.dart, or when deciding whether logic belongs in a store or a page state.

Build a *_use_case.dart — what a use case may inject (services, never stores or other use cases), the four types, where to put it by consumer and when to promote it, return and error patterns, anti-patterns, and the extract-or-inline decision. Use when extracting an operation out of a store or state, or when deciding whether logic deserves its own class.

Write a try/catch the house way — which IssueTrackingService method to call (trackIssue / trackHandledError / trackSilentError), the golden rule that every catch tracks or rethrows, what a catch should catch, the five use-case error patterns, restore-then-rethrow for stores, rollback notices for optimistic changes, recovery (retry, fallback, state reset), and how to test it. Use when writing any catch block, a store action or use case that calls the API, background work, or platform-channel code.

Turn a Jira ticket or written task into an approved implementation plan before any code is written. Reads every acceptance criterion, analyses the codebase, produces a file-level plan mapped to ADRs, playbooks and tests, then sizes the work and decides solo vs parallel execution. Use at the start of ANY feature, and whenever a task arrives as a ticket key, a link, or a paragraph of requirements.

Run the QA gate on a finished feature before it can be called done — map every acceptance criterion to a passing test or flow, then walk the happy, failure and edge matrix covering states, input, network, navigation, accessibility, theming and localization. Use at the end of every feature, before opening a PR, and when reviewing someone else's.

Triage and diagnose a user bug report against the code the reporter was actually running. Pins the source to the app version in a detached worktree, gathers evidence from logs, crash reports and screenshots, runs an evidence-versus-code debate through one shared findings file (at most 3 rounds), and produces a draft verdict for a human to post. Creating a ticket is optional and only happens on an explicit yes after a duplicate search. Use when the user says "triage this bug report", "diagnose this crash", "why did the app break for this user", "look at these logs", "investigate this support ticket" or "review new bug reports", or pastes a stack trace, device log, crash-reporter link or error screenshot together with an app version.

Write a Maestro E2E flow for a feature — the mandatory happy/failure/edge trio, file layout, discovery and naming, the APP_ID contract and runner, selecting by TestId and not asserting UI copy, bounded waits, driving error states through the mock interceptor, device-state helpers (offline/online), gestures (percentage coordinates, shared swipe subflows, Dismissible thresholds) and transient UI, subflows, tags, and running locally or in CI. Use when a feature is functionally complete and needs its end-to-end proof.

Write unit and widget tests — the testing pyramid, where each layer is tested, mocktail fakes at the right seam, MobX observable assertions, tracking verified on failure paths, JSON fixtures, widget tests for the loading/error/empty/content branches, keyed rows that survive a removal, overriding the page state (getIt for a whole page, Provider.value for a sub-widget), request-shape tests for API providers, and the "can this fail if the real code is broken?" check. Use whenever adding or changing a store, state, use case, service, platform channel or page.