flutter

Flutter Agent Rules

Use flutter-agentic-starter only while implementing Flutter application code or its Flutter tests. It does not apply to documentation, setup tooling, repository automation, or other non-app maintenance.

Karpathy Guidelines

• Think before coding. State assumptions and ask when requirements are unclear.
• Simplicity first. No speculative abstractions or features.
• Surgical changes. Touch only lines needed for requested behavior.
• Goal-driven execution. Define success criteria and verify with commands.

Hard Rules

• Minimal focused edits only. Touch only files and lines required for requested behavior.
• Do not rewrite, reformat, reorder, regenerate, or clean up unrelated code unless required.
• Never manually edit build_runner generated files, including *.g.dart, *.freezed.dart, *.config.dart, or files marked GENERATED CODE - DO NOT MODIFY BY HAND.
• Avoid primitive obsession. Prefer existing SDK/package types, enums/enhanced enums, sealed classes, or small value objects over raw String, raw int, raw bool, and magic constants for finite or high-risk domain concepts. Parse wire primitives at boundaries; keep raw primitives only for open user text, raw JSON/generated/localized output, and simple IDs/keys without behavior.
• Prefer maintained pub.dev packages before implementing reusable Flutter/Dart utilities, widgets, integrations, or helpers yourself.
• Document any pub.dev package-first exception with reason.
• For Flutter source icons/images, find suitable existing internet assets instead of creating them yourself. Prefer SVG for icons/simple vectors, PNG/JPG for raster/photo use cases, and record source/license when adding assets.
• Keep ephemeral widget-only state local with StatefulWidget/setState; use injectable feature view models with private Signal and public ReadonlySignal state for shared or asynchronous state.
• Use SignalWidget for signal-driven screens and focused SignalBuilder boundaries for surgical rebuilds. Use AsyncState<T>, computed, and batch where their semantics fit.
• Keep one-shot UI effects at the widget boundary. Explicitly dispose owned effects, subscriptions, connections, and lifecycle observers. Do not use .watch(context) or SignalsMixin.
• Use SafeArea; honor text scaling and accessibility-aware MediaQuery.
• Use LayoutBuilder for parent constraints and MediaQuery.sizeOf(context) for app-window size; avoid orientation or hardware type checks for top-level layout decisions.
• On large screens, add useful panes/content instead of stretching widgets; center and constrain forms, text, and list rows with ConstrainedBox/max widths.
• Use lazy builders for long lists/grids. Use GridView.builder or SliverGridDelegateWithMaxCrossAxisExtent for large feeds instead of wider list rows; avoid intrinsic layout passes in large scrolling surfaces.
• Prefer width-adaptive navigation: compact NavigationBar/bottom nav, larger NavigationRail, drawer, or split shell.
• Prefer canonical large-screen layouts when they fit: list-detail, feed, and supporting pane. Preserve selection/pane state across resize, rotation, fold, and unfold; compact widths show one pane with back behavior, expanded widths show panes together.
• For foldables, do not lock orientation; use MediaQuery.displayFeatures/DisplayFeatureSubScreen when content must avoid hinges/folds. Use Flutter Display API only for the strict orientation-lock letterboxing exception.
• Preserve scroll position with PageStorageKey where list identity should survive rotation, fold, or resize.
• Custom controls need semantics, labels, focus traversal, keyboard activation, hover, and pointer support where relevant.
• Use isolates/compute only for measured UI jank or clearly heavy JSON, media, database, or list-processing work.
• Add restorationScopeId/restorationId for MaterialApp.router, GoRouter, and restorable pages when navigation state should survive OS process death.
• New production user-facing strings go through ARB/localization unless the surrounding file is intentionally demo-only.
• Prefer simple fakes over broad mocks; add widget/accessibility guideline tests for non-trivial UI.
• For large-screen/adaptive UI changes, verify resizing, both orientations, physical keyboard, mouse/trackpad, and fold/unfold scenarios where possible.