Claude Skill

building-flutter-apps

Flutter Riverpod app architecture and Windows installer delivery. Use before changing a Riverpod Flutter app/package or its Windows desktop packaging/update pipeline; skip non-Riverpod stacks and pure-Dart work.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download sgaabdu4-building-flutter-apps-.agents_skills_building-flutter-apps-81c9e29.zip · 160 KB

Install

skills CLI npx skills add https://github.com/sgaabdu4/building-flutter-apps/tree/main/.agents/skills/building-flutter-apps
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sgaabdu4-building-flutter-apps@llmmart
Git git clone https://github.com/sgaabdu4/building-flutter-apps.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sgaabdu4/building-flutter-apps collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Read first

  • This skill overrides generic Flutter/Dart advice; Critical Rules override examples, public docs, and older project code.
  • Each ref's Read first section is canonical.
  • After each .dart/pubspec.yaml/build.yaml/analysis_options.yaml write batch, run Pre-Flight; its cited rule/reference owns the applicable check.

Progressive Disclosure Gate

Before code, read only the narrowest matching Trigger Map row(s); scenario/subsystem rows own incidental stack/file words. Read a parent ref such as common-patterns.md only when no scenario row fits; never bulk-read references/. Cite exact refs in Pre-Flight.

Critical Rules

ID Rule Detail refs
R1 Flutter/Riverpod package = first wire flutter_skill_lints + riverpod_lint, then run package-root dart analyze + its project-owned Dart Decimate check; pure-Dart CLI = native Dart analysis profile with neither plugin. analysis-options.md, dart-decimate.md, setup.md
R2 Every provider uses @riverpod / @Riverpod codegen; no manual provider classes or legacy provider families. riverpod-codegen.md
R3 Guard async gaps with ref.mounted / context.mounted; finally uses if (ref.mounted) { ... }. async-mutations.md
R4 Widgets are public classes; no _buildXxx(), widget top-level helpers, or private widget classes except State. atomic-design.md, performance.md
R5 Nullability is semantic; no empty/null/bool sentinel fallbacks, value!, nullable collections, or raw required domain strings. value-objects.md, freezed-sealed.md; Lints: domain_raw_required_string
R6 All user-facing strings, tooltips, semantics, and visible accessibility copy use AppLocalizations. localization.md, accessibility.md
R7 Immutable state/entities use sealed Freezed, one declaration per file, native switch, and VO map/when disabled. freezed-sealed.md, value-objects.md
R8 presentation/widgets/ renders immutable inputs + emits typed callbacks; screens/routes/notifiers own navigation, workflow, domain state, and infrastructure. presentation-widgets.md
R9 Duplicate behavior in 2+ classes becomes a small stateless *Mixin with an on clause. mixins.md
R10 Storage SDK calls live in local datasources behind repositories; production Hive imports use hive_ce_flutter. hive-persistence.md, architecture.md
R11 Primitive/context/collection operations live in core/extensions/; domain never imports those extensions. context-ui.md, primitive-formatting.md, collections-helpers.md
R12 Domain primitives with meaning become validated Freezed Value Objects; Hive models keep primitives and mappers bridge. value-objects.md, hive-persistence.md; Lints: domain_unit_primitive
R13 Typed GoRouter routes are navigation SSOT; redirects are pure resolver logic with nullable by-id fallback UI. deep-linking.md, routing-app-shell.md
R14 Dialogs/sheets render immutable snapshots, pop results, and leave mutations/teardown to notifiers. modals-navigation.md, state-management-lifecycle.md
R15 Debounce, gate, and batch high-frequency UI, sync, persistence, remote-function, reset, and lookup boundaries. debounce-gate-batch.md
R16 App shell stays declarative; bootstrap listeners live in a sibling root ConsumerWidget. routing-app-shell.md
R17 Keep control flow flat after exits; remove unnecessary else after return / throw / break / continue. Lint: avoid_unnecessary_else_after_control_flow
R18 Use onReorderItem post-removal indexes directly; never add legacy onReorder adapter math. Lint: use_on_reorder_item_index_semantics
R19 Android exact alarms use flutter_local_notifications permission APIs, not manual settings intents. Lint: use_local_notifications_exact_alarm_permission_api
R20 Resolve nullable platform-specific plugin implementations before calling platform members. Lint: resolve_platform_specific_implementation_before_use
R21 Widget previews are preview-only with deterministic fakes; no real HTTP/Firebase/Hive/native plugins. widget-previews.md
R22 Runtime E2E proves behavior with stable selectors, failure-sensitive scenarios/logs, subject-matched evidence, source-of-truth verification, cleanup, and multi-actor proof when needed. dart-mcp-e2e-testing.md
R23 Accessibility is UI correctness: localized tooltips/semantic labels, 48x48 targets, contrast, text scale, Text.rich. accessibility.md, flutter-optimizations.md
R24 If remote error reporting is accepted or already present, use one app-owned Crash boundary and one reporting owner per operation; otherwise add no provider/facade. Scrub sensitive data + reconcile ambiguous remote outcomes before telemetry. error-reporting.md, networking.md
R25 Windows installer delivery = one semantic engine + typed app config/capabilities + minimal-step exact-SHA diagnostic → one publisher; keep cheap guards before one build, isolate synthetic preservation proof, and activate only verified immutable bytes. windows-installer-pipeline.md, workflow scaffold, inno_bundle pubspec scaffold, Inno settlement sentinel, Defender scanner
R26 Pause-sensitive Riverpod state starts only after its durable owner/listener exists; projections watch base state directly; switching auth/form modes clears transient errors. notifier-structure.md, state-management-lifecycle.md, testing.md
R27 Native/custom links use one URI contract across producer, platform registration, Flutter delivery, and typed router; prove cold/warm + signed-state delivery on the target device. deep-linking.md, dart-mcp-e2e-testing.md

Trigger Map

Touching Read
New app/project scaffolding with incidental stack/package mentions, main.dart, ProviderScope, MaterialApp.router, app startup shell setup.md + architecture.md + routing-app-shell.md
Notifier/AsyncNotifier shape, sync Notifier.build() init, paused route/listener startup, provider projection, auth/form mode error reset, loading/progress, AsyncValue, cleanup notifier-structure.md + state-management-lifecycle.md + testing.md
Mutation method, ref.read / ref.watch / ref.listen, _ensureRepository, async cancellation, ref.mounted, optimistic update, duplicate fetch async-mutations.md + state-management-lifecycle.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, auth-protected route, router provider, context.go, deep link, custom URI scheme, native extension/activity link, cold-start, navigation gate routing-app-shell.md + deep-linking.md
HTTP, network, REST, source-of-truth fetch after mutation, long-running remote function, async-start + reconcile, transport id vs domain id networking.md + debounce-gate-batch.md
Atom, molecule, organism, design tokens, atomic widgets, core/widgets/ promotion atomic-design.md
Reusable presentation/widgets/, widget-owned navigation/page stack/selected entity/workflow state, direct repository/service/provider access presentation-widgets.md
Accessibility, semantics, tooltip, semanticLabel, image alt text, tap target, contrast, text scaling accessibility.md + flutter-optimizations.md
Widget test, ProviderContainer.test(), UncontrolledProviderScope, fakes, mocks, AppWidgetKeys, event-contract tests testing.md
flutter_driver, Dart MCP, Marionette MCP, E2E, integration_test, semantic selectors, scenario validation, screenshot/media proof, log capture, native integration builds but fails on device, runtime permissions, plugin hangs, release-only runtime failure dart-mcp-e2e-testing.md
Hive, TypeAdapter, TypeId, box, persistence migration, retired field accounting hive-persistence.md
Crashlytics, FirebaseCrashlytics, Sentry, sentry_flutter, DSN, error reporting, Crash.init, Crash.error, Crash.log, symbol upload error-reporting.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
Pagination, infinite scroll, cursor loading, search debounce, registration/form validation and submission, batch processing, pull-to-refresh lists-forms-workflows.md + async-mutations.md
BuildContext helpers, ModalRoute current-route checks, dialogs, SnackBarUtils, snackbar dispatch from notifier context-ui.md
DateTime format/diff/timeAgo/startOfDay, String capitalize/truncate/titleCase/initials/format, int / double / num clamp/pluralized/asCurrency/percent/toFixed, Duration format, NumberFormat, DateFormat, intl primitive-formatting.md
Iterable lookup/indexing, widget list helpers, Debouncer, validators, Result, extension types, core/extensions/ barrel export collections-helpers.md
Records (x, y), extension type IDs, pattern matching, primary/concise constructors, new(), factory(), dot shorthand such as .center, @RecordUse dart-patterns-records.md
Flutter/Riverpod analysis_options.yaml, dart analyze, plugin wiring, riverpod_lint version pin, analyzer crash analysis-options.md + analysis_options.yaml
Skill setup, Git pre-push, hook/scanner registration setup.md
build_runner, missing generated parts, clean checkout, Xcode selection, Flutter SwiftPM generated package, Apple device build, local-vs-CI mismatch build-reproducibility.md + core-stack.md
Package constraints, dependency upgrade, generator/analyzer compatibility core-stack.md
Flutter Windows desktop packaging, GitHub Actions Windows installer, Inno Setup, inno_bundle, updater/auto-update, CRT DLLs, PowerShell/native installer process, installer/version/AppId failure windows-installer-pipeline.md + build-reproducibility.md + core-stack.md
Dart Decimate, dead code, circular dependency, duplicate code, complexity, dependency hygiene, full zero-finding scan dart-decimate.md
Navigation / form / list / debounce / route-param-fallback pattern that no narrower row covers common-patterns.md
Incremental remote pull, delta token, per-table sync date, merge/delete reconciliation delta-sync.md
Route-param safety, wizard sequencing, guarded next-step navigation navigation-flow.md
Dialog / sheet / modal, snapshot value object, post-await teardown, dismiss-then-route, pop fallback, nested navigator dismissal modals-navigation.md + state-management-lifecycle.md
Debounce / throttle / coalesce — TextField.onChanged, Slider.onChanged, scroll listener, sync saveAll, full-collection rewrite after subset mutation, persistence helper, reset/clear sentinel preservation, _userTapped gate, WebView / VideoPlayer in build, _storage.read in service, ref.listenManual ban, keepAlive collection watch, datasource batch loader, zero-value save guard, primitive→VO at notifier boundary, routeSettings on modal helper debounce-gate-batch.md

Pre-Flight

Internal check after each .dart / pubspec.yaml / build.yaml / analysis_options.yaml write batch: T0 always; + T1 for state/notifier/mutation changes; + T2 for network/E2E/stream/route changes. Edit loop = analyze only the edited files per analysis-options.md; the full package-root run is once before handoff.

  • Failed item → report it promptly with its rule ID or ref.
  • Handoff → report the completed verification: refs read + checks run + results.

T0 — Core

  • Flutter/Riverpod package: edited files analyze clean in the edit loop; once before handoff, package-root dart analyze --fatal-infos exits 0 with flutter_skill_lints + riverpod_lint; setup changes prove one diagnostic from each plugin. Pure-Dart CLI: native Dart analysis profile applies; both plugins are N/A.
  • A current same-scope project-owned Dart Decimate result is green per dart-decimate.md; cite scan scope.
  • Async gaps are guarded: ref.mounted / context.mounted, no bare mounted, and finally uses if (ref.mounted) { ... }.
  • Providers, state, and widgets follow Rules 2-8 and 14: reusable widgets own UI lifecycle only; screens/routes/notifiers own navigation, workflow branching, selected domain records, provider state, and infrastructure.
  • Domain/data/platform follow Rules 7, 10-13, 17-24, 26-27: sealed Freezed, VOs, datasource/repo storage, core extensions, typed routes, debounce/batch, platform APIs, previews, E2E, pause-safe state, native links, and a11y; if error reporting is accepted/present, it uses one scrubbed once-only boundary, otherwise N/A.
  • Rule 25 = N/A unless Windows packaging/updater delivery is touched; when applicable, its diagnostic/publisher proof is green.
  • Any row touched in Trigger Map was read; exact lint names are cited when a scanner should enforce the rule.

T1 — State / Notifier / Mutation

  • Mutation deps resolve lazily via stateless helper/mixin; no notifier-local repo/service cache except disposable lifecycle owners.
  • Sync Notifier.build() avoids pre-return state reads; async primary state uses AsyncNotifier.build; durable sync startup does not depend on microtask timing before its owner/listener exists.
  • ref.onDispose() cancels subscriptions/controllers/timers; durable status/snackbar/teardown belongs to notifier state.
  • Long-running sync/auth/import guards stale writes; no ref.watch inside notifier methods.
  • Pause-sensitive projections watch base state directly; route pause/resume keeps the first update; auth/form mode changes clear transient errors.

T2 — Network / E2E / Stream / Route

  • Source-of-truth fetch/reconcile after generated, normalized, reordered, destructive, or remote-function mutations.
  • Shared/realtime state has writer + observer E2E proof without manual refresh.
  • Selectors use stable text/semantics/tooltips or central AppWidgetKeys; no inline string keys or coordinate primary taps.
  • E2E scenario state is deterministic and isolated from production behaviour; Marionette runs use the debug-gated binding in lib/main.dart, Flutter Driver runs a separate driver-extension entrypoint; unknown scenarios fail; critical logs fail the run; evidence shows the asserted screen before app exit; cleanup is verified.
  • GoRouter redirects use pure matrix-tested resolver, nullable by-id providers/fallback UI, and generated typed route helpers.
  • Native/custom URI producer, Android/iOS registration, Flutter delivery, and typed router share one tested scheme/host/path contract; cold/warm + signed-state device paths pass.
  • Cross-runtime constants, schemas, and function contracts have drift tests; no app-root text-scale clamp.
Files (building-flutter-apps)
  • agents
    • openai.yaml 273 B
      Loading…
  • assets
    • defender-installer-scan.ps1 11.3 KB · in bundle
    • inno-bundle-pubspec.yaml 645 B
      Loading…
    • inno-uninstall-settlement-sentinel.ps1 9.7 KB · in bundle
    • windows-installer-workflow.yml 15.8 KB
      Loading…
  • references
    • atomic-design
      • accessibility.md 1.7 KB
        Loading…
    • common-patterns
      • debounce-gate-batch.md 9.6 KB
        Loading…
      • delta-sync.md 4.2 KB
        Loading…
      • lists-forms-workflows.md 8.5 KB
        Loading…
      • modals-navigation.md 7.4 KB
        Loading…
      • navigation-flow.md 2.5 KB
        Loading…
      • routing-app-shell.md 13.8 KB
        Loading…
    • extensions
      • collections-helpers.md 2.6 KB
        Loading…
      • context-ui.md 2.2 KB
        Loading…
      • primitive-formatting.md 2.2 KB
        Loading…
    • state-management
      • async-mutations.md 3 KB
        Loading…
      • notifier-structure.md 3.1 KB
        Loading…
    • analysis-options.md 6.7 KB
      Loading…
    • analysis_options.yaml 1.2 KB
      Loading…
    • architecture.md 20.3 KB
      Loading…
    • atomic-design.md 13.8 KB
      Loading…
    • build-reproducibility.md 3.5 KB
      Loading…
    • common-patterns.md 6.6 KB
      Loading…
    • core-stack.md 4.6 KB
      Loading…
    • dart-decimate.md 1.3 KB
      Loading…
    • dart-mcp-e2e-testing.md 26.8 KB
      Loading…
    • dart-patterns-records.md 5.9 KB
      Loading…
    • deep-linking.md 7.3 KB
      Loading…
    • error-reporting.md 7.1 KB
      Loading…
    • flutter-optimizations.md 12.3 KB
      Loading…
    • freezed-sealed.md 12.4 KB
      Loading…
    • hive-persistence.md 17.3 KB
      Loading…
    • layout-diagnostics.md 5.9 KB
      Loading…
    • localization.md 5.6 KB
      Loading…
    • mixins.md 7 KB
      Loading…
    • networking.md 8.6 KB
      Loading…
    • performance.md 15.7 KB
      Loading…
    • presentation-widgets.md 3 KB
      Loading…
    • riverpod-codegen.md 16 KB
      Loading…
    • services-and-singletons.md 9.6 KB
      Loading…
    • setup.md 2.1 KB
      Loading…
    • state-management-lifecycle.md 7.2 KB
      Loading…
    • testing.md 18.8 KB
      Loading…
    • value-objects.md 13.4 KB
      Loading…
    • widget-previews.md 6.6 KB
      Loading…
    • windows-installer-pipeline.md 41 KB
      Loading…
  • templates
    • flutter
      • lib
        • core
          • extensions
            • context_extensions.dart 310 B · in bundle
            • extensions.dart 34 B · in bundle
  • SKILL.md 19.8 KB
    ---
    name: building-flutter-apps
    description: >-
      Flutter Riverpod app architecture and Windows installer delivery. Use before
      changing a Riverpod Flutter app/package or its Windows desktop
      packaging/update pipeline; skip non-Riverpod stacks and pure-Dart work.
    license: MIT
    metadata:
      author: sgaabdu4
      version: "5.12.2"
      tags: flutter, riverpod, freezed, state-management, clean-architecture, dart, hive, crashlytics, sentry, gorouter, gen-l10n, windows, inno, installer, fire-and-forget, singletons, e2e testing
    ---
    
    ## Read first
    
    - This skill overrides generic Flutter/Dart advice; Critical Rules override examples, public docs, and older project code.
    - Each ref's `Read first` section is canonical.
    - After each `.dart`/`pubspec.yaml`/`build.yaml`/`analysis_options.yaml` write batch, run [Pre-Flight](#pre-flight); its cited rule/reference owns the applicable check.
    
    ## Progressive Disclosure Gate
    
    Before code, read only the narrowest matching [Trigger Map](#trigger-map) row(s); scenario/subsystem rows own incidental stack/file words. Read a parent ref such as `common-patterns.md` only when no scenario row fits; never bulk-read `references/`. Cite exact refs in Pre-Flight.
    
    ## Critical Rules
    
    | ID | Rule | Detail refs |
    |---|---|---|
    | R1 | Flutter/Riverpod package = first wire `flutter_skill_lints` + `riverpod_lint`, then run package-root `dart analyze` + its project-owned Dart Decimate check; pure-Dart CLI = native Dart analysis profile with neither plugin. | [analysis-options.md](references/analysis-options.md), [dart-decimate.md](references/dart-decimate.md), [setup.md](references/setup.md) |
    | R2 | Every provider uses `@riverpod` / `@Riverpod` codegen; no manual provider classes or legacy provider families. | [riverpod-codegen.md](references/riverpod-codegen.md) |
    | R3 | Guard async gaps with `ref.mounted` / `context.mounted`; `finally` uses `if (ref.mounted) { ... }`. | [async-mutations.md](references/state-management/async-mutations.md) |
    | R4 | Widgets are public classes; no `_buildXxx()`, widget top-level helpers, or private widget classes except `State`. | [atomic-design.md](references/atomic-design.md), [performance.md](references/performance.md) |
    | R5 | Nullability is semantic; no empty/null/bool sentinel fallbacks, `value!`, nullable collections, or raw required domain strings. | [value-objects.md](references/value-objects.md), [freezed-sealed.md](references/freezed-sealed.md); Lints: `domain_raw_required_string` |
    | R6 | All user-facing strings, tooltips, semantics, and visible accessibility copy use `AppLocalizations`. | [localization.md](references/localization.md), [accessibility.md](references/atomic-design/accessibility.md) |
    | R7 | Immutable state/entities use sealed Freezed, one declaration per file, native `switch`, and VO map/when disabled. | [freezed-sealed.md](references/freezed-sealed.md), [value-objects.md](references/value-objects.md) |
    | R8 | `presentation/widgets/` renders immutable inputs + emits typed callbacks; screens/routes/notifiers own navigation, workflow, domain state, and infrastructure. | [presentation-widgets.md](references/presentation-widgets.md) |
    | R9 | Duplicate behavior in 2+ classes becomes a small stateless `*Mixin` with an `on` clause. | [mixins.md](references/mixins.md) |
    | R10 | Storage SDK calls live in local datasources behind repositories; production Hive imports use `hive_ce_flutter`. | [hive-persistence.md](references/hive-persistence.md), [architecture.md](references/architecture.md) |
    | R11 | Primitive/context/collection operations live in `core/extensions/`; domain never imports those extensions. | [context-ui.md](references/extensions/context-ui.md), [primitive-formatting.md](references/extensions/primitive-formatting.md), [collections-helpers.md](references/extensions/collections-helpers.md) |
    | R12 | Domain primitives with meaning become validated Freezed Value Objects; Hive models keep primitives and mappers bridge. | [value-objects.md](references/value-objects.md), [hive-persistence.md](references/hive-persistence.md); Lints: `domain_unit_primitive` |
    | R13 | Typed GoRouter routes are navigation SSOT; redirects are pure resolver logic with nullable by-id fallback UI. | [deep-linking.md](references/deep-linking.md), [routing-app-shell.md](references/common-patterns/routing-app-shell.md) |
    | R14 | Dialogs/sheets render immutable snapshots, pop results, and leave mutations/teardown to notifiers. | [modals-navigation.md](references/common-patterns/modals-navigation.md), [state-management-lifecycle.md](references/state-management-lifecycle.md) |
    | R15 | Debounce, gate, and batch high-frequency UI, sync, persistence, remote-function, reset, and lookup boundaries. | [debounce-gate-batch.md](references/common-patterns/debounce-gate-batch.md) |
    | R16 | App shell stays declarative; bootstrap listeners live in a sibling root `ConsumerWidget`. | [routing-app-shell.md](references/common-patterns/routing-app-shell.md) |
    | R17 | Keep control flow flat after exits; remove unnecessary `else` after `return` / `throw` / `break` / `continue`. | Lint: `avoid_unnecessary_else_after_control_flow` |
    | R18 | Use `onReorderItem` post-removal indexes directly; never add legacy `onReorder` adapter math. | Lint: `use_on_reorder_item_index_semantics` |
    | R19 | Android exact alarms use `flutter_local_notifications` permission APIs, not manual settings intents. | Lint: `use_local_notifications_exact_alarm_permission_api` |
    | R20 | Resolve nullable platform-specific plugin implementations before calling platform members. | Lint: `resolve_platform_specific_implementation_before_use` |
    | R21 | Widget previews are preview-only with deterministic fakes; no real HTTP/Firebase/Hive/native plugins. | [widget-previews.md](references/widget-previews.md) |
    | R22 | Runtime E2E proves behavior with stable selectors, failure-sensitive scenarios/logs, subject-matched evidence, source-of-truth verification, cleanup, and multi-actor proof when needed. | [dart-mcp-e2e-testing.md](references/dart-mcp-e2e-testing.md) |
    | R23 | Accessibility is UI correctness: localized tooltips/semantic labels, 48x48 targets, contrast, text scale, `Text.rich`. | [accessibility.md](references/atomic-design/accessibility.md), [flutter-optimizations.md](references/flutter-optimizations.md#semantics) |
    | R24 | If remote error reporting is accepted or already present, use one app-owned `Crash` boundary and one reporting owner per operation; otherwise add no provider/facade. Scrub sensitive data + reconcile ambiguous remote outcomes before telemetry. | [error-reporting.md](references/error-reporting.md), [networking.md](references/networking.md) |
    | R25 | Windows installer delivery = one semantic engine + typed app config/capabilities + minimal-step exact-SHA diagnostic → one publisher; keep cheap guards before one build, isolate synthetic preservation proof, and activate only verified immutable bytes. | [windows-installer-pipeline.md](references/windows-installer-pipeline.md), [workflow scaffold](assets/windows-installer-workflow.yml), [`inno_bundle` pubspec scaffold](assets/inno-bundle-pubspec.yaml), [Inno settlement sentinel](assets/inno-uninstall-settlement-sentinel.ps1), [Defender scanner](assets/defender-installer-scan.ps1) |
    | R26 | Pause-sensitive Riverpod state starts only after its durable owner/listener exists; projections watch base state directly; switching auth/form modes clears transient errors. | [notifier-structure.md](references/state-management/notifier-structure.md), [state-management-lifecycle.md](references/state-management-lifecycle.md), [testing.md](references/testing.md) |
    | R27 | Native/custom links use one URI contract across producer, platform registration, Flutter delivery, and typed router; prove cold/warm + signed-state delivery on the target device. | [deep-linking.md](references/deep-linking.md), [dart-mcp-e2e-testing.md](references/dart-mcp-e2e-testing.md) |
    
    ## Trigger Map
    
    | Touching | Read |
    |---|---|
    | New app/project scaffolding with incidental stack/package mentions, `main.dart`, `ProviderScope`, `MaterialApp.router`, app startup shell | [setup.md](references/setup.md) + [architecture.md](references/architecture.md) + [routing-app-shell.md](references/common-patterns/routing-app-shell.md) |
    | Notifier/AsyncNotifier shape, sync `Notifier.build()` init, paused route/listener startup, provider projection, auth/form mode error reset, loading/progress, `AsyncValue`, cleanup | [notifier-structure.md](references/state-management/notifier-structure.md) + [state-management-lifecycle.md](references/state-management-lifecycle.md) + [testing.md](references/testing.md) |
    | Mutation method, `ref.read` / `ref.watch` / `ref.listen`, `_ensureRepository`, async cancellation, `ref.mounted`, optimistic update, duplicate fetch | [async-mutations.md](references/state-management/async-mutations.md) + [state-management-lifecycle.md](references/state-management-lifecycle.md) |
    | Freezed entity, sealed union, `fromJson` / `toJson`, `copyWith`, model vs entity, `build.yaml` for `explicit_to_json` | [freezed-sealed.md](references/freezed-sealed.md) |
    | Provider declaration, `@riverpod`, family, `keepAlive`, codegen, `Mutation<T>` (experimental) | [riverpod-codegen.md](references/riverpod-codegen.md) |
    | Repository, datasource, domain entity, layered architecture, `IHttpService`, mapping models to entities | [architecture.md](references/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](references/value-objects.md) |
    | GoRouter, typed route, redirect, auth-protected route, router provider, `context.go`, deep link, custom URI scheme, native extension/activity link, cold-start, navigation gate | [routing-app-shell.md](references/common-patterns/routing-app-shell.md) + [deep-linking.md](references/deep-linking.md) |
    | HTTP, network, REST, source-of-truth fetch after mutation, long-running remote function, async-start + reconcile, transport id vs domain id | [networking.md](references/networking.md) + [debounce-gate-batch.md](references/common-patterns/debounce-gate-batch.md) |
    | Atom, molecule, organism, design tokens, atomic widgets, `core/widgets/` promotion | [atomic-design.md](references/atomic-design.md) |
    | Reusable `presentation/widgets/`, widget-owned navigation/page stack/selected entity/workflow state, direct repository/service/provider access | [presentation-widgets.md](references/presentation-widgets.md) |
    | Accessibility, semantics, tooltip, semanticLabel, image alt text, tap target, contrast, text scaling | [accessibility.md](references/atomic-design/accessibility.md) + [flutter-optimizations.md](references/flutter-optimizations.md#semantics) |
    | Widget test, `ProviderContainer.test()`, `UncontrolledProviderScope`, fakes, mocks, `AppWidgetKeys`, event-contract tests | [testing.md](references/testing.md) |
    | `flutter_driver`, Dart MCP, Marionette MCP, E2E, `integration_test`, semantic selectors, scenario validation, screenshot/media proof, log capture, native integration builds but fails on device, runtime permissions, plugin hangs, release-only runtime failure | [dart-mcp-e2e-testing.md](references/dart-mcp-e2e-testing.md) |
    | Hive, `TypeAdapter`, TypeId, box, persistence migration, retired field accounting | [hive-persistence.md](references/hive-persistence.md) |
    | Crashlytics, FirebaseCrashlytics, Sentry, `sentry_flutter`, DSN, error reporting, `Crash.init`, `Crash.error`, `Crash.log`, symbol upload | [error-reporting.md](references/error-reporting.md) |
    | Mixin, capability vs interface, retry helper, RNG, bulk operation | [mixins.md](references/mixins.md) |
    | Service, singleton, fire-and-forget, `abstract final class`, `unawaited()`, `Future<void>` signature | [services-and-singletons.md](references/services-and-singletons.md) |
    | `@Preview`, `widget_previews.dart`, preview fakes, deterministic preview data | [widget-previews.md](references/widget-previews.md) |
    | `AppLocalizations`, ARB file, gen-l10n, locale fallback, placeholders, plural / select | [localization.md](references/localization.md) |
    | Performance, build cost, `.select()`, `const` constructors, `ListView.builder`, large list compute | [performance.md](references/performance.md) + [flutter-optimizations.md](references/flutter-optimizations.md) |
    | `LayoutBuilder`, `RenderFlex` overflow, `Expanded` / `Flexible` outside `Row` / `Column`, `Positioned` outside `Stack`, text-scale clamp | [layout-diagnostics.md](references/layout-diagnostics.md) |
    | Pagination, infinite scroll, cursor loading, search debounce, registration/form validation and submission, batch processing, pull-to-refresh | [lists-forms-workflows.md](references/common-patterns/lists-forms-workflows.md) + [async-mutations.md](references/state-management/async-mutations.md) |
    | `BuildContext` helpers, `ModalRoute` current-route checks, dialogs, `SnackBarUtils`, snackbar dispatch from notifier | [context-ui.md](references/extensions/context-ui.md) |
    | `DateTime` format/diff/timeAgo/startOfDay, `String` capitalize/truncate/titleCase/initials/format, `int` / `double` / `num` clamp/pluralized/asCurrency/percent/toFixed, `Duration` format, `NumberFormat`, `DateFormat`, `intl` | [primitive-formatting.md](references/extensions/primitive-formatting.md) |
    | `Iterable` lookup/indexing, widget list helpers, `Debouncer`, validators, `Result`, extension types, `core/extensions/` barrel export | [collections-helpers.md](references/extensions/collections-helpers.md) |
    | Records `(x, y)`, extension type IDs, pattern matching, primary/concise constructors, `new()`, `factory()`, dot shorthand such as `.center`, `@RecordUse` | [dart-patterns-records.md](references/dart-patterns-records.md) |
    | Flutter/Riverpod `analysis_options.yaml`, `dart analyze`, plugin wiring, `riverpod_lint` version pin, analyzer crash | [analysis-options.md](references/analysis-options.md) + [analysis_options.yaml](references/analysis_options.yaml) |
    | Skill setup, Git pre-push, hook/scanner registration | [setup.md](references/setup.md) |
    | `build_runner`, missing generated parts, clean checkout, Xcode selection, Flutter SwiftPM generated package, Apple device build, local-vs-CI mismatch | [build-reproducibility.md](references/build-reproducibility.md) + [core-stack.md](references/core-stack.md) |
    | Package constraints, dependency upgrade, generator/analyzer compatibility | [core-stack.md](references/core-stack.md) |
    | Flutter Windows desktop packaging, GitHub Actions Windows installer, Inno Setup, `inno_bundle`, updater/auto-update, CRT DLLs, PowerShell/native installer process, installer/version/AppId failure | [windows-installer-pipeline.md](references/windows-installer-pipeline.md) + [build-reproducibility.md](references/build-reproducibility.md) + [core-stack.md](references/core-stack.md) |
    | Dart Decimate, dead code, circular dependency, duplicate code, complexity, dependency hygiene, full zero-finding scan | [dart-decimate.md](references/dart-decimate.md) |
    | Navigation / form / list / debounce / route-param-fallback pattern that no narrower row covers | [common-patterns.md](references/common-patterns.md) |
    | Incremental remote pull, delta token, per-table sync date, merge/delete reconciliation | [delta-sync.md](references/common-patterns/delta-sync.md) |
    | Route-param safety, wizard sequencing, guarded next-step navigation | [navigation-flow.md](references/common-patterns/navigation-flow.md) |
    | Dialog / sheet / modal, snapshot value object, post-await teardown, dismiss-then-route, pop fallback, nested navigator dismissal | [modals-navigation.md](references/common-patterns/modals-navigation.md) + [state-management-lifecycle.md](references/state-management-lifecycle.md#state-teardown-belongs-in-the-notifier) |
    | Debounce / throttle / coalesce — `TextField.onChanged`, `Slider.onChanged`, scroll listener, sync `saveAll`, full-collection rewrite after subset mutation, persistence helper, reset/clear sentinel preservation, `_userTapped` gate, `WebView` / `VideoPlayer` in `build`, `_storage.read` in service, `ref.listenManual` ban, keepAlive collection watch, datasource batch loader, zero-value save guard, primitive→VO at notifier boundary, `routeSettings` on modal helper | [debounce-gate-batch.md](references/common-patterns/debounce-gate-batch.md) |
    
    ## Pre-Flight
    
    Internal check after each `.dart` / `pubspec.yaml` / `build.yaml` / `analysis_options.yaml` write batch: T0 always; + T1 for state/notifier/mutation changes; + T2 for network/E2E/stream/route changes. Edit loop = analyze only the edited files per [analysis-options.md](references/analysis-options.md#edit-loop); the full package-root run is once before handoff.
    
    - Failed item → report it promptly with its rule ID or ref.
    - Handoff → report the completed verification: refs read + checks run + results.
    
    ### T0 — Core
    
    - [ ] Flutter/Riverpod package: edited files analyze clean in the edit loop; once before handoff, package-root `dart analyze --fatal-infos` exits 0 with `flutter_skill_lints` + `riverpod_lint`; setup changes prove one diagnostic from each plugin. Pure-Dart CLI: native Dart analysis profile applies; both plugins are N/A.
    - [ ] A current same-scope project-owned Dart Decimate result is green per [dart-decimate.md](references/dart-decimate.md); cite scan scope.
    - [ ] Async gaps are guarded: `ref.mounted` / `context.mounted`, no bare `mounted`, and `finally` uses `if (ref.mounted) { ... }`.
    - [ ] Providers, state, and widgets follow Rules 2-8 and 14: reusable widgets own UI lifecycle only; screens/routes/notifiers own navigation, workflow branching, selected domain records, provider state, and infrastructure.
    - [ ] Domain/data/platform follow Rules 7, 10-13, 17-24, 26-27: sealed Freezed, VOs, datasource/repo storage, core extensions, typed routes, debounce/batch, platform APIs, previews, E2E, pause-safe state, native links, and a11y; if error reporting is accepted/present, it uses one scrubbed once-only boundary, otherwise N/A.
    - [ ] Rule 25 = N/A unless Windows packaging/updater delivery is touched; when applicable, its diagnostic/publisher proof is green.
    - [ ] Any row touched in Trigger Map was read; exact lint names are cited when a scanner should enforce the rule.
    
    ### T1 — State / Notifier / Mutation
    
    - [ ] Mutation deps resolve lazily via stateless helper/mixin; no notifier-local repo/service cache except disposable lifecycle owners.
    - [ ] Sync `Notifier.build()` avoids pre-return `state` reads; async primary state uses `AsyncNotifier.build`; durable sync startup does not depend on microtask timing before its owner/listener exists.
    - [ ] `ref.onDispose()` cancels subscriptions/controllers/timers; durable status/snackbar/teardown belongs to notifier state.
    - [ ] Long-running sync/auth/import guards stale writes; no `ref.watch` inside notifier methods.
    - [ ] Pause-sensitive projections watch base state directly; route pause/resume keeps the first update; auth/form mode changes clear transient errors.
    
    ### T2 — Network / E2E / Stream / Route
    
    - [ ] Source-of-truth fetch/reconcile after generated, normalized, reordered, destructive, or remote-function mutations.
    - [ ] Shared/realtime state has writer + observer E2E proof without manual refresh.
    - [ ] Selectors use stable text/semantics/tooltips or central `AppWidgetKeys`; no inline string keys or coordinate primary taps.
    - [ ] E2E scenario state is deterministic and isolated from production behaviour; Marionette runs use the debug-gated binding in `lib/main.dart`, Flutter Driver runs a separate driver-extension entrypoint; unknown scenarios fail; critical logs fail the run; evidence shows the asserted screen before app exit; cleanup is verified.
    - [ ] GoRouter redirects use pure matrix-tested resolver, nullable by-id providers/fallback UI, and generated typed route helpers.
    - [ ] Native/custom URI producer, Android/iOS registration, Flutter delivery, and typed router share one tested scheme/host/path contract; cold/warm + signed-state device paths pass.
    - [ ] Cross-runtime constants, schemas, and function contracts have drift tests; no app-root text-scale clamp.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.