flutter-starter

Clean Architecture layer rules, feature folder structure, import direction, and no-backend feature scaffolding for flutter_starter. Use when deciding where a new file belongs, reviewing dependency direction between domain/data/presentation, structuring a feature folder, or building a presentation-only feature (splash, onboarding, info).

Code style rules and anti-patterns for flutter_starter — comment discipline (write only for non-obvious why), SOLID principles, no speculative abstractions, and a concrete anti-patterns table covering dartz vs custom Either, datasource-returns-Either, e.toString() in Failure, emit vs safeEmit, state.navigateToX, Navigator.of(context).push* directly, raw-map route args, hardcoded Colors.white / TextStyle / EdgeInsets, print / AppLogger.debug, @freezed class (non-abstract), TextEditingController in StatefulWidget, AppBar in body widget, setState inside BlocConsumer. Use before finalizing any Dart file in this project.

Rules for the data layer in flutter_starter — RemoteDataSource using ApiClient, RepositoryImpl as the Either boundary with exception-to-Failure mapping, cache-first read patterns, Dio timeouts, and the Failure error-code ranges. Use when creating or editing any file under lib/features/*/data/, or when mapping exceptions to Failure.

Rules for dependency injection with GetIt (sl) in flutter_starter — every feature owns a di/<feature>_dependencies.dart registered in service_locator.dart, with registration order DataSources → Repository → UseCases → Cubit, and lazy-singleton vs factory guidance. Use when creating a new feature's DI file, editing service_locator.dart, or deciding how to register a service.

Rules for the domain layer in flutter_starter — Freezed entities with self-owned fromJson, UseCase + Params pattern, and abstract Repository contracts. Use when creating or editing any file under lib/features/*/domain/, or deciding whether a feature needs a separate Model class beyond its Entity.

Orchestrator for scaffolding a new Flutter Clean Architecture feature end-to-end in flutter_starter — enforces mode selection (quick / detailed), the intake ritual, the strict generation order across layers, and the feature-delivery checklist. Supports two modes — quick (5 basic questions) and detailed (expanded API contracts with exact request / response shapes). Delegates detailed rules to the per-layer skills (architecture / domain-layer / data-layer / presentation-layer / hive-caching / security / di-registration / navigation / translations). Use when the user asks to create a new feature with domain, data, and presentation layers.

Rules for local caching with Hive in flutter_starter — box naming, key strategy, Entity annotation with @HiveType / @HiveField, LocalDataSource pattern, schema migration constraints (typeId/index immutability), and cache invalidation triggers (logout, version change). Use when adding caching to a feature, modifying a LocalDataSource, or editing an entity with @HiveField annotations.

Rules for navigation in flutter_starter — typed route argument classes (no raw Maps), the three-edit rule (AppRoute enum + generateRoute switch + _guardsFor switch), NavigationService API, route guards (AuthGuard / GuestGuard / custom), PageRouteAnimator transitions, and returnOrFallback after guard redirects. Use when adding or modifying any route, writing navigation calls, or creating route guards.

Rules for the presentation layer in flutter_starter — Cubit with safeEmit, Freezed state with Failure (never String), BlocConsumer split between Page (Scaffold + CustomAppBar + BlocProvider) and body widget (content + listener/builder), TextEditingController ownership in the Cubit. Use when creating or editing any file under lib/features/*/presentation/.

Non-negotiable security rules for flutter_starter — encrypted Hive box for tokens/PII, required Dio timeouts, certificate pinning stance, logging prohibitions (no tokens / no PII / no full response bodies), user input sanitization, deep-link argument validation, and FCM / GoogleAuth service lifecycles. Use whenever handling tokens, credentials, PII, external inputs, user-generated content, or push notification / social sign-in logic. Security rules override architecture and style rules on conflict.

Rules for styling and layout in flutter_starter — consume colors / typography / device info through BuildContext extensions (context.colors, context.styles, context.screenWidth, etc.), size fonts with .sp(context), build paddings with num extensions (16.horizontal, 24.all), clamp OS text scale once at MaterialApp.builder, and use AppThemeManager for runtime theme switching. Use when styling any UI element — never hardcode colors, font sizes, or EdgeInsets left/right.

Rules for internationalization in flutter_starter — never hardcode user-facing strings, use LocaleKeys.x.tr(context) with optional args for placeholders, add new keys to assets/translations/translations.json (numbered for shared, named for feature-specific), run the codegen helper, and never edit generated locale files. Covers pluralization via _zero/_one/_two/_few/_many/_other suffixes. Use when adding any user-visible text, validation messages, snackbar content, or dialog content.

Catalog of reusable UI components, snackbars, and dialogs in flutter_starter — CustomButton, CustomTextFormField, CustomAppBar, CustomCachedNetworkImage, OTPInputField, AnimatedDotsLoader, FailureWidget, EmptyWidget, ConfirmBackScope, DoubleBackToExit, MenuAction, RoundedLoadingButton, plus scaffold / overlay snackbars and warning dialog helpers. Use before writing any new widget — check the catalog first. Also covers core utilities (DateFormatter, NumberFormatter, Debouncer, PaginationController, image/file pickers, NetworkMonitor).

UX / UI design principles and quality gates for flutter_starter — hierarchy (one hero per screen), 8pt spacing grid, 60 / 30 / 10 color rule, typography rules, iconography, motion timing, the five required states (empty / loading / loaded / error / stale), form conventions, accessibility requirements (contrast, tap targets, semantics), and RTL / dark-mode correctness. Use when designing any screen or component, reviewing a layout, or deciding spacing / colors / motion values.

Rules for form validation in flutter_starter — always use pre-translated Validator.* methods (validateEmail, validatePassword, validatePhone, validateRequired, validateLength, validateDate, etc.), and add new validation methods inside Validator rather than inlining regex. Use when adding or editing any TextFormField validator, or when validating external arguments from deep links / push payloads.

Read pubspec.yaml and print flutter pub add commands for all packages.