building-flutter-apps

Gate

On skill activation, emit verbatim once:

building-flutter-apps active. Pre-flight required.

Before writing any .dart code, emit verbatim:

Reading building-flutter-apps gate.

After every code change to a .dart file (or to pubspec.yaml / build.yaml / analysis_options.yaml):

1. Run dart analyze from the package root. Block on any ERROR or WARNING.
2. Emit the filled-in Pre-Flight checklist. T0 always. T1 / T2 only if their domain was touched.
3. If dart analyze is not wired with flutter_skill_lints, run Setup before continuing.

Critical Rules

1. Use dart analyze from package root, never flutter analyze and never path-scoped. Copy references/analysis_options.yaml to project root and wire flutter_skill_lints + riverpod_lint under plugins:. flutter analyze lib silently drops plugin diagnostics (flutter#184190).

2. Use @riverpod / @Riverpod codegen for every provider — state, computed, repository, datasource, service, family, stream. Never manual Provider, FutureProvider, StreamProvider, StateProvider, StateNotifierProvider, NotifierProvider, AsyncNotifierProvider, ChangeNotifierProvider. Run dart run build_runner watch --delete-conflicting-outputs.

3. Guard every await in notifiers and repositories with if (!ref.mounted) return;. Guard every await in widgets and State with if (!context.mounted) return;. Inside State, never if (mounted) — always if (!context.mounted) return;. Inside finally, use the guard form if (ref.mounted) { ... } — never if (!ref.mounted) return;.

4. Extract widgets to public classes. No _buildXxx() helpers. No class _Foo extends StatelessWidget | StatefulWidget | ConsumerWidget | ConsumerStatefulWidget | HookWidget | HookConsumerWidget. Mark file-internal widgets @visibleForTesting. _FooState extends State<Foo> stays private (Flutter convention — exempt).

5. Use Object? or a specific type for unknown values. dynamic only for Map<String, dynamic> JSON. Never value! — use if (value case final v?).

6. Use AppLocalizations (gen-l10n) for every user-facing string. Never hardcode UI copy in widgets, notifiers, repositories, or datasources. In widgets, bind final l10n = context.l10n; at the top of build and use l10n.someKey; never chain context.l10n.someKey. *Strings constants only for non-user-facing IDs. For l10n config, put ARB files in arb-dir (lib/l10n by default). Generated Dart is written to ${arb-dir}/${output-localization-file} unless output-dir is set; import app_localizations.dart from that directory.

7. Use sealed class for Freezed unions and states. Never abstract class with @freezed. Match with Dart native switch — never Freezed .when() / .map(). For VOs in /domain/values/, annotate @Freezed(map: FreezedMapOptions.none, when: FreezedWhenOptions.none) to disable codegen of those methods entirely. Lint: freezed_disable_map_when_required.

8. Never prop-drill state. Child widgets read providers directly with ref.watch / ref.read / ref.listen. Do not pass entity / state / notifier instances through constructors. Constructor params allowed: immutable IDs (for routing/lookup), callbacks, Key, and primitive props on leaf atoms. ConsumerState may own lifecycle handles, not provider-derived *Cache/*Source/*DayStart fields; use computed providers or local build values. Lint: riverpod_consumer_state_derived_cache.

9. Use a mixin when the same behavior appears in 2+ classes. Extract to a mixin with an on clause (e.g. mixin RetryMixin on AsyncNotifier<X>). Suffix the name with Mixin. Copy-paste sharing across notifiers, widgets, or services is forbidden — replace with a mixin.

10. Storage SDK calls live in Local Datasource, never in Notifier. Hive (Hive.openBox, box.get/put/delete, Hive.box), SharedPreferences, flutter_secure_storage, dart:io file ops, path_provider directory access — all live behind a Local<X>Datasource interface, called by <X>Repository. Notifiers and widgets never import hive_ce / shared_preferences / flutter_secure_storage / dart:io / path_provider.

11. Primitives → core/extensions/. Never inline. DateTime / String / int / double / num / Duration / Iterable / BuildContext ops (capitalize, timeAgo, currency, percent, clamp, format) in core/extensions/{type}_extensions.dart, barrel extensions.dart. Call .timeAgo / .capitalized / .asCurrency / .clamped(...) / .pluralized(...). Forbidden: '${s[0].toUpperCase()}${s.substring(1)}', DateTime.now().difference(...), DateTime.now().toUtc(), DateTime.timestamp(), DateTimeX.nowLocal().startOfDay, DateTimeX.nowLocal().calendarDaysBefore(...), NumberFormat.currency(...).format(...), inline .clamp(...). Raw executable strings and numbers are magic literals; move them to named constants, Value Objects, or semantic helpers. Current time helpers live in DateTimeX (nowUtc, nowLocal); current-day boundaries such as nowLocalStartOfDay and repeated local calendar windows such as "60 days ago" get semantic DateTimeX helpers. Calendar-day helpers reconstruct date components; they do not subtract Duration(days: ...) across DST-sensitive local dates. Persisted/server timestamps MUST use UTC helpers, and local calendar bucketing of stored timestamps MUST convert to local first. Lints: datetime_now_requires_timezone_intent, avoid_magic_literals (suppress with a comment only when local raw time or literal ownership is intentional and app-specific). Why: SSOT — one fix updates every call site. Apply: 2+ uses → extension. Domain entities NEVER import core/extensions/ (outer dep, arch_domain_import ERROR). Domain derive via entity getter (one-off) OR Value Object (cross-entity — Rule 12). See extensions-utilities.md.

12. Wrap domain primitives in Value Objects. Domain-meaning double/int/String (unit, currency, measure, identity, format) → sealed Freezed VO in /domain/values/. Raw redirects PRIVATE (._meters/._raw); public factories MUST contain explicit guards in body (if (v.isNaN) throw ArgumentError.value(...), if (!v.isFinite) throw ..., domain assertions), NEVER passthrough (factory X.unit(T v) => X._unit(v); is rejected — same risk as a public raw redirect). No named primitive factories on domain entities — convert at data/notifier/import boundaries. No hand-written copyWith in /domain/. Hive collision: Hive Models in /data/models/ hold primitives only; VOs live on domain Entity, mapper bridges. Never change ctor param types or order on a @GenerateAdapters-registered class with shipped user data — silent box corruption, dart analyze blind to disk. Apply: primitive in 2+ entities → VO. Bare double distanceMeters at entity boundary = smell. See value-objects.md, hive-persistence.md. Lints: vo_public_raw_constructor (catches public redirect AND passthrough), domain_entity_primitive_factory, domain_custom_copy_with, hive_field_no_vo_type.

13. Keep typed GoRouter routes as the navigation SSOT. Define routes once with go_router_builder, then navigate with generated route helpers such as SomeRoute(...).go(context) and SomeRoute(...).push<T>(context). Keep route paths inside route definitions and generated helpers. Local sheets/dialogs use semantic helpers and Navigator.pop for dismissal. Navigation lints enforce typed routes, local modal helpers, and typed fallback behavior.

Trigger Map

Before writing code in any row below, output Reading: <ref-name> and read the listed reference(s).

Touching	Read
Notifier, AsyncNotifier, mutation method, ref.read / ref.watch / ref.listen, _ensureRepository, async cancellation, sync Notifier init	state-management.md
Freezed entity, sealed union, fromJson / toJson, copyWith, model vs entity, build.yaml for explicit_to_json	freezed-sealed.md
Provider declaration, @riverpod, family, keepAlive, codegen, Mutation<T> (experimental)	riverpod-codegen.md
Repository, datasource, domain entity, layered architecture, IHttpService, mapping models to entities	architecture.md
Value Object, primitive obsession, Distance/Money/Email/Slug, unit conversion in domain, cross-entity primitive, double distanceMeters/int amountCents/String email smell, arch_domain_import error	value-objects.md
GoRouter, typed route, redirect, context.go, deep link, cold-start, navigation gate	architecture.md + deep-linking.md
HTTP, network, REST, source-of-truth fetch after mutation, transport id vs domain id	networking.md
Atom, molecule, organism, design tokens, atomic widgets, core/widgets/ promotion	atomic-design.md
Showcase, AppShowcaseTarget, startShowCase, replay, ShowcaseKeys, ProviderSubscription lifecycle	showcase-tours.md
Widget test, ProviderContainer.test(), UncontrolledProviderScope, fakes, mocks, AppWidgetKeys, event-contract tests	testing.md
flutter_driver, Dart MCP, E2E, integration_test, semantic selectors, log capture	dart-mcp-e2e-testing.md
Hive, TypeAdapter, TypeId, box, persistence migration, retired field accounting	hive-persistence.md
Crashlytics, error reporting, Crash facade, recoverable error classifier, symbol upload, three-hook wiring (FlutterError.onError + PlatformDispatcher.instance.onError + Isolate.current.addErrorListener), runZonedGuarded legacy (Flutter 3.3+)	crashlytics.md
Mixin, capability vs interface, retry helper, RNG, bulk operation	mixins.md
Service, singleton, fire-and-forget, abstract final class, unawaited(), Future<void> signature	services-and-singletons.md
@Preview, widget_previews.dart, preview fakes, deterministic preview data	widget-previews.md
AppLocalizations, ARB file, gen-l10n, locale fallback, placeholders, plural / select	localization.md
Performance, build cost, .select(), const constructors, ListView.builder, large list compute	performance.md + flutter-optimizations.md
LayoutBuilder, RenderFlex overflow, Expanded / Flexible outside Row / Column, Positioned outside Stack, text-scale clamp	layout-diagnostics.md
Extension, SnackBarUtils, snackbar dispatch from notifier, @visibleForTesting helpers, DateTime format/diff/timeAgo/startOfDay, String capitalize/truncate/titleCase/initials/format, int / double / num clamp/pluralized/asCurrency/percent/toFixed, Duration format, parse/format, NumberFormat, DateFormat, intl, core/extensions/	extensions-utilities.md
Records (x, y), extension type IDs, pattern matching, guard clause case _ when ...	dart-patterns-records.md
analysis_options.yaml, dart analyze, plugin wiring, riverpod_lint pre-release pin, analyzer crash	analysis-options.md + analysis_options.yaml
Common navigation / form / list / debounce / route-param-fallback patterns	common-patterns.md

Core Stack

Version SSOT: README.md → Core Stack.

Package	Version	Purpose
flutter_riverpod + riverpod_annotation + riverpod_generator	^3.3.1 / ^4.0.2 / ^4.0.3	State management (codegen)
freezed + freezed_annotation	^3.2.5 / ^3.1.0	Immutable data classes, unions
go_router + go_router_builder	^17.2.3 / ^4.3.0	Declarative, type-safe routing
json_serializable + build_runner	6.13.0 / ^2.15.0	JSON serialization + code generation
showcaseview	^5.0.2	First-run guided tours
hive_ce + hive_ce_flutter + hive_ce_generator	^2.19.3 / ^2.3.4 / 1.11.0	Local persistence

Architecture

graph LR
  P[Presentation] --> R[Repository]
  R --> Do[Domain]
  R --> Da[Data]
  Da -.-> Do

lib/
├── core/
├── features/
│   └── feature_x/
│       ├── data/           # Models, datasources (API / local)
│       ├── domain/         # Entities (pure Dart, no Flutter imports)
│       ├── repositories/   # Map models → entities
│       └── presentation/   # Notifiers, screens, widgets
└── main.dart

Repository returns Domain entities (never Models). Domain has no Flutter import. Datasource throws typed exceptions, never returns null on failure. try/catch lives in the Notifier — never in Domain or Datasource.

Class Modifiers

Modifier	Extend outside lib	Implement outside lib	Instantiate	Mixin
abstract class	✓	✓	✗	✗
abstract interface class	✗	✓	✗	✗
abstract final class	✗	✗	✗	✗
sealed class	✗	✗	✗	✗
base class	✓	✗	✓	✗
interface class	✗	✓	✓	✗
final class	✗	✗	✓	✗
mixin class	✓	✓	✓	✓

abstract interface class for repository / datasource / service contracts. sealed class for Freezed unions. abstract final class for pure stateless helper namespaces (Crash, Storage).

Code Generation

dart run build_runner watch --delete-conflicting-outputs
dart run build_runner build --delete-conflicting-outputs
dart run build_runner clean && dart run build_runner build --delete-conflicting-outputs

Setup

1. Copy references/analysis_options.yaml to project root. It already wires flutter_skill_lints + riverpod_lint under plugins:.
2. flutter_skill_lints is an analyzer plugin — it lives only in analysis_options.yaml plugins:. Never add it to pubspec.yaml.
3. Run dart pub get. Confirm dart analyze exits 0.
4. Sanity check: write Widget _buildHeader() => const SizedBox(); — dart analyze must flag it.

Per-Tool Hooks

Tool	Auto-install command	Hook source
Claude Code	/plugin marketplace add sgaabdu4/building-flutter-apps then /plugin install building-flutter-apps@building-flutter-apps; run /reload-plugins in the active session	hooks/hooks.json
Codex CLI	codex features enable hooks, codex features enable plugin_hooks, codex plugin marketplace add sgaabdu4/building-flutter-apps, then codex → /plugins → install	hooks/hooks.json
Copilot CLI	copilot plugin marketplace add sgaabdu4/building-flutter-apps then copilot plugin install building-flutter-apps@building-flutter-apps	hooks/hooks.copilot.json

Raw skill installs are guidance-only. They load this file but cannot register runtime hooks or run scanners. Use plugin installs when enforcement matters.

Pre-Flight

Fill T0 always after any .dart write. Fill T1 if state / notifier / mutation touched. Fill T2 if network / E2E / stream / showcase / route touched. Emit before yielding the turn.

T0

• dart analyze exits 0 with flutter_skill_lints + riverpod_lint wired
• if (!ref.mounted) return; after every await in notifiers and repositories
• if (!context.mounted) return; after every await in widgets and State (no bare if (mounted))
• Inside finally, use guard form if (ref.mounted) { ... } — never early-return
• No _buildXxx() and no private widget classes extending Stateless / Stateful / Consumer / Hook widgets (State subclasses exempt)
• No dynamic except Map<String, dynamic> for JSON; no value!
• Widgets bind final l10n = context.l10n; before localized key reads; no chained context.l10n.someKey
• All providers @riverpod codegen; no manual Provider(...) family
• No prop-drilling: children watch providers directly. No entity / state / notifier in constructors
• Shared behavior across 2+ classes lives in a mixin (suffixed Mixin), not copy-pasted
• No hive_ce / shared_preferences / flutter_secure_storage / dart:io / path_provider imports in notifier or widget files — storage goes through Local<X>Datasource → <X>Repository
• No inline primitive ops outside core/extensions/ — use .capitalized / .timeAgo / .asCurrency / .clamped(...) / .pluralized(...) / DateTimeX.nowUtc(). Forbidden: '${s[0].toUpperCase()}...', date now/diff/UTC/timestamp chains, local calendar windows, ad-hoc NumberFormat, inline .clamp(...), raw key/id/limit/threshold literals
• Domain entity imports = freezed_annotation + /domain/ paths only. Zero core/, data/, presentation/, package:flutter, dart:ui
• Domain primitives with unit / currency / measure / identity wrapped in VO (Distance/Money/Email) — no bare double distanceMeters / int amountCents / String email at entity boundary
• VO raw redirects PRIVATE (._meters / ._raw); only validated factories public (vo_public_raw_constructor)
• No named primitive factories on @freezed domain entities (factory User.fromPrimitives(...) forbidden — convert at data/notifier/import boundary) (domain_entity_primitive_factory)
• No hand-written copyWith in /domain/ — let Freezed generate from the redirect (domain_custom_copy_with)

T1 — State / Notifier / Mutation

• Mutation methods (create*, update*, delete*, set*, reorder*) init deps via _ensureRepository() / _ensureDependencies() lazily
• Sync Notifier.build() does not read state before first return; seed via constructor; defer async with Future.microtask
• ref.onDispose() cancels every subscription / controller / timer
• No provider-derived *Cache/*Source/*DayStart/*TodayStart fields in ConsumerState; use computed providers or local build values
• Notifier owns snackbar dispatch — widgets do not call SnackBarUtils.show* or ScaffoldMessenger.of(context)
• Long-running sync / auth / import flows guard stale async writes
• No ref.watch inside notifier method body — ref.watch in build() only; ref.read in callbacks

T2 — Network / E2E / Stream / Showcase / Route

• Source-of-truth fetch after mutation when backend generates / normalizes / reorders / derives values
• Observer + writer E2E proof present for shared / realtime / collaborative state
• All ValueKey from central AppWidgetKeys registry — no inline string ValueKey('...')
• E2E entrypoint deterministic (lib/main_dev.dart or equivalent); test overrides isolated from main.dart
• GoRouter redirect logic in pure resolveAppRedirect(...), matrix-tested; nullable by-id provider for route params with fallback UI; call sites use generated typed route helpers
• startShowCase() receives full ordered ShowcaseKeys.*Tour list; ProviderSubscription stored and closed in disposeShowcase()
• Cross-runtime constants / schema / function contracts have drift tests
• No MediaQuery.withClampedTextScaling in MaterialApp builder

Recap

1. dart analyze from package root, never flutter analyze. Plugin wired in analysis_options.yaml plugins:, never pubspec.yaml.
2. No _buildXxx(). No private widget classes extending Stateless / Stateful / Consumer / Hook. Public + @visibleForTesting if file-internal. _FooState extends State<Foo> stays private.
3. if (!ref.mounted) return; after EVERY await in notifiers and repositories. if (!context.mounted) return; after EVERY await in widgets and State. Never bare if (mounted). Inside finally blocks, use if (ref.mounted) { ... } guard form, never if (!ref.mounted) return;.
4. Every mutation method inits deps via _ensureRepository() / _ensureDependencies(). Never rely on build() / _init() timing.
5. sealed class with Freezed, never abstract class. Dart native switch, never .when() / .map().
6. No prop-drilling. Child widgets watch providers directly. No entity / state / notifier as constructor params.
7. Shared behavior across 2+ classes → mixin XxxMixin on Y. No copy-paste sharing.
8. Storage SDK (Hive, SharedPreferences, secure_storage, dart:io, path_provider) lives in Local<X>Datasource. Notifiers and widgets never import storage SDKs directly.
9. Primitives → core/extensions/. SSOT. Inline forbidden. Missing? Add to barrel, then call. Domain never imports core/extensions/ — entity getter (one-off) or VO (cross-entity).
10. Domain primitives with unit / currency / measure / identity → sealed Freezed VO in /domain/. See value-objects.md.
11. Typed GoRouter route classes are the navigation SSOT. Call generated route helpers directly; local modal helpers own sheet/dialog presentation and dismissal.