aymansalkhatib

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.

Add an HTTP endpoint to an existing module — updates the audience-scoped controller (creates one if needed), DTO, service method, and i18n keys for any new error messages. Triggers: "add an endpoint", "expose endpoint X on module Y", "add a route to <module>", "/add-endpoint".

Add a TypeORM entity to an existing module — entity file, repository, TypeOrmModule.forFeature registration, generated migration. Triggers: "add an entity", "add a table", "add <Entity> to module X", "/add-entity".

Add mirrored Arabic + English translation keys to src/infrastructure/i18n/translations/{ar,en}/<feature>.json, then regenerate translation-keys.ts via npm run i18n:sync. Triggers: "add a translation", a Translator.tr('<key>') call without a matching JSON key, "/add-i18n-keys".

Generate a new role-scoped controller for an existing module (e.g. admin-foo.controller.ts next to user-foo.controller.ts). Wires @Protected(Role.X), the path/version, and registers in the module. Triggers: "expose this module to admins/users", "add an admin controller for <module>", "/add-protected-controller".

Diagnose and break a circular dependency between NestJS modules or providers — without reaching for forwardRef. Triggers: Nest "circular dependency" / "can't resolve dependencies" startup error, "ModuleA imports ModuleB and back", a new cross-module service injection, "how do I avoid a cycle", "/circular-deps".

Apply when writing, reviewing, or removing comments. Triggers: /comments, "should I comment this", "is this comment good", "explain why this code does X".

Generate or update a Postman Collection v2.1.0 JSON for a single module. The collection lives at `src/modules/<module>/postman/<module>.postman_collection.json`. Triggers "generate postman collection for X", "/generate-postman-collection <module>".

Scaffold a feature module under src/modules/<plural>/ — entity, repository, service, audience-scoped controllers, DTOs, i18n stub, AppModule wiring. Triggers: "create a new module", "scaffold feature X", "/init-feature-module", new domain entity with API surface.