agent-flutter 0.1.1

package/templates/shared/skills/flutter-assets-management/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: Flutter Assets Management
+description: Standards for asset naming, organization, and synchronization with design tools.
+---
+
+# Assets Management
+
+## **Priority: P1 (HIGH)**
+
+Strict conventions for asset filenames to ensure traceability between Design (Figma) and Code.
+
+## Naming Convention
+
+### **CRITICAL RULE: Figma Matching**
+- **Filenames MUST match the layer/export name in Figma.**
+- **Format**: `snake_case` (lowercase with underscores).
+- **Prohibited**: Random strings, UUIDs, or generic names (e.g., `image_1.png`, `552ecefb...png`).
+
+### **Temporary Naming for Per-Screen Icons**
+- **Rule**: If a name already exists, append an incrementing numeric suffix: `_2`, `_3`, ...
+- **Examples**:
+  - `visit_record_calendar.svg` → `visit_record_calendar_2.svg` (if already present)
+  - `customer_detail_back.svg` → `customer_detail_back_2.svg` (if already present)
+- **AppAssets**: Constant should match the filename; e.g. `iconsVisitRecordCalendar2Svg` → `'assets/images/icons/visit_record_calendar_2.svg'`.
+- **Note**: Do not overwrite existing files; always create the next numeric suffix.
+
+### **Examples**
+| Bad (Reject) | Good (Accept) |
+| :--- | :--- |
+| `552ecefb-d09c.png` | `user_avatar_placeholder.png` |
+| `Group 123.svg` | `ic_notification_badge.svg` |
+| `IMG_2024.jpg` | `onboarding_background.jpg` |
+
+## Organization
+
+```text
+assets/
+├── images/ # Illustrations, photos, backgrounds
+├── icons/ # Vector icons (SVG)
+└── fonts/ # Custom font files
+```
+
+## Workflow
+1.  **Rename in Figma**: Before exporting, rename the layer in Figma to a valid `snake_case` name.
+2.  **Export**: Export the asset with the correct name.
+3.  **Import**: Place in the corresponding `assets/` subdirectory.
+4.  **Verification**: Do not commit random filenames.
+
+## Icon Consistency & Deduplication
+- **Goal**: Avoid cross-screen reuse during the current phase; keep icons per-screen only.
+- **Rule**:
+  - **Single Source**: Each icon has one SVG file and one constant in `AppAssets`.
+  - **No Duplicates**: Do not add different filenames with identical graphics/content.
+- **Dedup Workflow**:
+  1. Normalize SVG: remove metadata, pretty-print, sort attributes, flatten stroke→fill, remove masks/filters if unnecessary.
+  2. Compute a content hash (SHA-256) after normalization; compare within `assets/images/icons/`.
+  3. If hashes match, consolidate to a single file and update all code references to the shared `AppAssets` constant.
+  4. Variants (color/size/outline vs solid) must be clearly named and treated as different when geometry or semantics differ (e.g., `icons_chevron_solid.svg` vs `icons_chevron_outline.svg`).
+- **CI/Pre-commit (Recommended)**:
+  - Add a duplicate check step: normalize + hash for `assets/images/icons/`.
+  - Fail build on duplicates; print a list of files to consolidate.
+- **Usage Policy**:
+  - Always use `SvgPicture.asset(AppAssets.some_icon)`; do not reference raw paths.
+  - For recolor, use a fill/tint-friendly version (stroke flattened to fill).
+
+## Temporary Policy: Per-Screen Icons Only
+- **Scope**: Current phase.
+- **Rule**: Each screen adds its own icons only; do not reuse icons across other screens.
+- **Naming Suggestion**: Name by screen context (e.g., `customer_detail_back.svg`, `visit_record_calendar.svg`) to avoid confusion.
+- **Note**: When moving to project-wide reuse, we will consolidate using the dedup policy above.
+
+## SVG Color Handling
+- **Default**: Do not apply `color`/`colorFilter` if the SVG already has the correct Figma colors.
+- **Allowed**: Only use `color`/`colorFilter` when explicit recolor is required (e.g., active/inactive states) and the icon is prepared with fill (no stroke).
+- **Prohibited**: Avoid applying `colorFilter` broadly on multi-color SVGs; this causes color deviations unless explicitly specified by design.
+## Related Topics
+
+idiomatic-flutter | feature-based-clean-architecture

package/templates/shared/skills/flutter-bloc-state-management/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: Flutter BLoC State Management
+description: Standards for predictable state management using flutter_bloc and equatable. Invoke when implementing BLoCs/Cubits, Events, States, or refactoring page widgets into components.
+---
+
+# BLoC State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Predictable state management separating business logic from UI using `flutter_bloc` and `equatable`.
+
+## Structure
+
+```text
+presentation/blocs/
+├── auth/
+│   ├── auth_bloc.dart
+│   ├── auth_event.dart # (Equatable)
+│   └── auth_state.dart # (Equatable)
+```
+
+## Implementation Guidelines
+
+- **States & Events**: Use `equatable` for value equality (stable rebuilds, reliable tests).
+- **State Strategy**:
+  - **Phase-based State**: Use a `Status` enum (idle/loading/success/failure) for exclusive UI phases.
+  - **Property-based State**: Use explicit properties (e.g. `isSubmitting`, `errorMessage`, `data`) for forms and complex screens.
+- **Copy/Update**: Provide `copyWith` manually when needed (keep it small and explicit).
+- **Error Handling**: Use `Failure` objects; avoid throwing exceptions.
+- **Async Data**: Use `emit.forEach` or `emit.onEach` for streams.
+- **Concurrency**: Use `transformer` (restartable, droppable) for event debouncing.
+- **Testing**: Use `blocTest` for state transition verification.
+- **Injection**: Register BLoCs as `@injectable` (Factory).
+
+## Anti-Patterns
+
+- **No Manual Emit**: Do not call `emit()` inside `Future.then`; always use `await` or `emit.forEach`.
+- **No UI Logic**: Do not perform calculations or data formatting inside `BlocBuilder`.
+- **No Cross-Bloc Reference**: Do not pass a BLoC instance into another BLoC; use streams or the UI layer to coordinate.
+
+## Reference & Examples
+
+For full BLoC/Cubit implementations and concurrency patterns:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+feature-based-clean-architecture | dependency-injection

package/templates/shared/skills/flutter-bloc-state-management/references/REFERENCE.md

@@ -0,0 +1,19 @@
+# BLoC State Management Reference
+
+Detailed patterns for implementing BLoC/Cubit in production.
+
+## References
+
+- [**Full Auth BLoC (Union State)**](auth-bloc-example.md) - Best for distinct app phases.
+- [**Property-Based State (Forms)**](property-based-state.md) - Best for persistent data and forms.
+- [**Cubit Minimal**](cubit-minimal.md) - Simple state management without events.
+
+## **Concurrency Transformer**
+
+```dart
+// Restartable prevents multiple simultaneous requests
+on<SearchEvent>(
+  _onSearch,
+  transformer: restartable(),
+);
+```

package/templates/shared/skills/flutter-bloc-state-management/references/auth-bloc-example.md

@@ -0,0 +1,96 @@
+# Auth BLoC Full Implementation
+
+## **Events (Equatable)**
+
+```dart
+abstract class AuthEvent extends Equatable {
+  const AuthEvent();
+  @override
+  List<Object?> get props => [];
+}
+
+class AuthStarted extends AuthEvent {
+  const AuthStarted();
+}
+
+class AuthLoginSubmitted extends AuthEvent {
+  final String email;
+  final String password;
+  const AuthLoginSubmitted(this.email, this.password);
+
+  @override
+  List<Object?> get props => [email, password];
+}
+
+class AuthLogoutPressed extends AuthEvent {
+  const AuthLogoutPressed();
+}
+```
+
+## **States (Equatable)**
+
+```dart
+enum AuthStatus { initial, loading, authenticated, unauthenticated, failure }
+
+class AuthState extends Equatable {
+  final AuthStatus status;
+  final User? user;
+  final String? message;
+
+  const AuthState({
+    required this.status,
+    this.user,
+    this.message,
+  });
+
+  const AuthState.initial() : this(status: AuthStatus.initial);
+
+  AuthState copyWith({
+    AuthStatus? status,
+    User? user,
+    String? message,
+  }) {
+    return AuthState(
+      status: status ?? this.status,
+      user: user ?? this.user,
+      message: message ?? this.message,
+    );
+  }
+
+  @override
+  List<Object?> get props => [status, user, message];
+}
+```
+
+## **BLoC Implementation**
+
+```dart
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  final IAuthRepository _repository;
+
+  AuthBloc(this._repository) : super(const AuthState.initial()) {
+    on<AuthLoginSubmitted>(_onLogin);
+    on<AuthLogoutPressed>(_onLogout);
+  }
+
+  Future<void> _onLogin(
+    AuthLoginSubmitted event,
+    Emitter<AuthState> emit,
+  ) async {
+    emit(state.copyWith(status: AuthStatus.loading));
+    final result = await _repository.login(event.email, event.password);
+
+    switch (result) {
+      case Success(value: final user):
+        emit(state.copyWith(status: AuthStatus.authenticated, user: user));
+      case FailureResult(failure: final failure):
+        emit(state.copyWith(status: AuthStatus.failure, message: failure.message));
+    }
+  }
+
+  Future<void> _onLogout(AuthLogoutPressed event, Emitter<AuthState> emit) async {
+    await _repository.logout();
+    emit(state.copyWith(status: AuthStatus.unauthenticated, user: null));
+  }
+}
+```

package/templates/shared/skills/flutter-bloc-state-management/references/property-based-state.md

@@ -0,0 +1,103 @@
+# Property-Based State Pattern (Forms & Complex Data)
+
+This pattern uses a single data class to maintain the entire state of a feature. It is the preferred approach for forms, multi-step wizards, and screens with persistent filtering.
+
+## **Pattern Implementation**
+
+```dart
+class NewRequestState extends Equatable {
+  final List<ReturnMaterial> selectedItems;
+  final String returnReference;
+  final SalesOrg salesOrg;
+
+  final bool showErrorMessages;
+  final bool isSubmitting;
+
+  final String? submitSuccessMessage;
+  final ApiFailure? submitFailure;
+
+  const NewRequestState({
+    required this.selectedItems,
+    required this.returnReference,
+    required this.salesOrg,
+    required this.showErrorMessages,
+    required this.isSubmitting,
+    this.submitSuccessMessage,
+    this.submitFailure,
+  });
+
+  factory NewRequestState.initial() => NewRequestState(
+        selectedItems: const [],
+        returnReference: '',
+        salesOrg: SalesOrg.empty(),
+        showErrorMessages: false,
+        isSubmitting: false,
+      );
+
+  NewRequestState copyWith({
+    List<ReturnMaterial>? selectedItems,
+    String? returnReference,
+    SalesOrg? salesOrg,
+    bool? showErrorMessages,
+    bool? isSubmitting,
+    String? submitSuccessMessage,
+    ApiFailure? submitFailure,
+  }) {
+    return NewRequestState(
+      selectedItems: selectedItems ?? this.selectedItems,
+      returnReference: returnReference ?? this.returnReference,
+      salesOrg: salesOrg ?? this.salesOrg,
+      showErrorMessages: showErrorMessages ?? this.showErrorMessages,
+      isSubmitting: isSubmitting ?? this.isSubmitting,
+      submitSuccessMessage: submitSuccessMessage,
+      submitFailure: submitFailure,
+    );
+  }
+
+  @override
+  List<Object?> get props => [
+        selectedItems,
+        returnReference,
+        salesOrg,
+        showErrorMessages,
+        isSubmitting,
+        submitSuccessMessage,
+        submitFailure,
+      ];
+}
+```
+
+## **When to use this vs. Union States?**
+
+### **1. Use Property-Based (Flat) State when:**
+
+- **Preservation is key**: You are building a **Form** or a **wizard** where users enter data. If you used a Union `Loading` state, the user's current input would be lost unless passed forward manually.
+- **Overlapping UI**: You need to show a loading indicator *on top* of existing data (e.g., a "loading" overlay on a list).
+- **Complex Filtering**: Multiple filters (search, date, category) that all need to persist.
+
+### **2. Use Union States (Sealed Classes) when:**
+
+- **Exclusive Phases**: The screen looks completely different in each state (e.g., Login Screen -> Loading Spinner -> Dashboard).
+- **Simple Lifecycle**: Fetch data once -> Display it. No complex user input involved.
+- **Type Safety**: The UI *must* have data in the `Success` state and *must not* have it in `Initial`.
+
+## **UI Consumption (Success/Failure fields)**
+
+```dart
+BlocListener<NewRequestBloc, NewRequestState>(
+  listenWhen: (p, c) =>
+      p.submitSuccessMessage != c.submitSuccessMessage ||
+      p.submitFailure != c.submitFailure,
+  listener: (context, state) {
+    if (state.submitFailure != null) {
+      showErrorSnackbar(state.submitFailure!.message);
+      return;
+    }
+    if (state.submitSuccessMessage != null) {
+      navigateToSummary();
+      return;
+    }
+  },
+  child: ...,
+)
+```

package/templates/shared/skills/flutter-dependency-injection-injectable/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: Flutter Dependency Injection (GetX)
+description: Standards for dependency injection using GetX Bindings and Service Locator.
+---
+
+# Dependency Injection (GetX)
+
+## **Priority: P1 (HIGH)**
+
+This project uses **GetX** for dependency injection.
+Dependencies are managed via `Bindings` and the global `Get` service locator.
+
+## Structure
+
+```text
+lib/src/
+├── di/
+│   ├── di_graph_setup.dart      # Global/Core dependencies (Singletons)
+│   ├── register_core_module.dart
+│   └── register_manager_module.dart
+└── ui/
+    └── <feature>/
+        └── binding/
+            └── <feature>_binding.dart # Feature-specific dependencies
+```
+
+## Implementation Guidelines
+
+### 1. Global Dependencies (Singletons)
+Register core services (API clients, storage, managers) in `lib/src/di/di_graph_setup.dart`.
+
+```dart
+// register_core_module.dart
+Future<void> _registerCoreModule() async {
+  Get.put(SharedPreferenceHelper(), permanent: true);
+  Get.lazyPut(() => AuthRepository(Get.find(), Get.find()), fenix: true);
+}
+```
+
+### 2. Feature Dependencies (Bindings)
+Use `Bindings` to lazy-load controllers/BLoCs when a page is entered.
+
+```dart
+// lib/src/ui/auth/login/binding/login_binding.dart
+class LoginBinding extends Bindings {
+  @override
+  void dependencies() {
+    // Register BLoC/Controller
+    Get.lazyPut<LoginBloc>(() => LoginBloc());
+  }
+}
+```
+
+### 3. Injection Types
+- **`Get.put()`**: Immediate initialization. Use for critical core services.
+- **`Get.lazyPut()`**: Lazy initialization. Created only when used. Best for Repositories/BLoCs.
+- **`Get.find<T>()`**: Inject a dependency.
+
+### 4. Scoping
+- Bindings attached to `GetPage` in `AppPages` are automatically disposed when the route is removed from the stack (unless `fenix: true` is used).
+
+## Reference & Examples
+
+See [references/modules.md](references/modules.md).

package/templates/shared/skills/flutter-dependency-injection-injectable/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# Dependency Injection Reference
+
+Implementation patterns for `injectable` and `get_it` in massive Flutter projects.
+
+## References
+
+- [**Injection Modules**](modules.md) - Registering third-party libraries (Dio, Hive).
+- [**Production Initialization**](initialization.md) - Wiring everything in `main.dart`.
+- [**Testing Mocks**](testing-mocks.md) - How to swap services during unit tests.
+
+## **Quick Registration Guide**
+
+- **@injectable**: Use for BLoCs (New instance every time).
+- **@LazySingleton**: Use for Repositories and DataSources (Global, lazy-init).
+- **@singleton**: Use only for truly shared resources (init on startup).

package/templates/shared/skills/flutter-dependency-injection-injectable/references/modules.md

@@ -0,0 +1,42 @@
+# DI Modules (GetX)
+
+## Global Setup
+`lib/src/di/di_graph_setup.dart`
+
+```dart
+Future<void> setupDependenciesGraph() async {
+  await _initializeEnvironment();
+  await _registerCoreModule(); // Repositories, APIs
+  _registerManagersModule();   // Managers
+}
+```
+
+## Feature Binding Example
+`lib/src/ui/auth/login/binding/login_binding.dart`
+
+```dart
+import 'package:get/get.dart';
+import 'package:link_home/src/ui/auth/login/bloc/login_bloc.dart';
+
+class LoginBinding extends Bindings {
+  @override
+  void dependencies() {
+    // Lazy load the Bloc/Controller for this feature
+    Get.lazyPut<LoginBloc>(() => LoginBloc());
+  }
+}
+```
+
+## Repository Registration
+Repositories are typically registered globally or in a core module.
+
+```dart
+// register_core_module.dart
+Get.lazyPut<AuthRepository>(
+  () => AuthRepository(
+    Get.find<AppShared>(),
+    Get.find<IAuthApiUrl>(),
+  ),
+  fenix: true, // Recreate if disposed but needed again
+);
+```

package/templates/shared/skills/flutter-error-handling/SKILL.md

@@ -0,0 +1,25 @@
+# Error Handling
+
+## **Priority: P1 (HIGH)**
+
+Standardized typed error handling using `Result<T>` and `Failure` models. The project uses **Dio** for networking, not `http`.
+
+## Implementation Guidelines
+
+- **Networking**: Use `Dio` (configured in `lib/src/api/api.dart`).
+- **Result Pattern**: Return `Result<T>` from repositories. No exceptions in UI/BLoC.
+- **Failures**: Define domain-specific failures as plain immutable classes.
+- **Error Mapping**:
+  - `Api` class (in `lib/src/api/api.dart`) handles low-level `DioException`.
+  - It extracts error messages from server response (e.g., `response.data['errors']` or `response.data['message']`).
+  - It handles UI feedback (e.g., `showErrorToast`) automatically for API errors.
+  - Repositories should catch exceptions rethrown by `Api` and map them to `Failure`.
+
+## Reference & Examples
+
+For Failure definitions and API error mapping:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+layer-based-clean-architecture | bloc-state-management

package/templates/shared/skills/flutter-error-handling/references/REFERENCE.md

@@ -0,0 +1,38 @@
+# Error Handling Reference
+
+## **Dio Error Mapping**
+
+Since the project uses `Dio` and a centralized `Api` wrapper (`lib/src/api/api.dart`), errors are processed as follows:
+
+1.  **Low-Level Catching (`Api.request`)**:
+    -   Catches `DioException`.
+    -   Parses `response.data['errors']` (Map) or `response.data['message']` (String).
+    -   Shows Toast automatically via `showErrorToast`.
+    -   Rethrows the exception for the Repository to handle logic flow.
+
+2.  **Repository Layer Mapping**:
+    Repositories should wrap API calls in try-catch blocks to return `Result<T>` (Success/Failure).
+
+    ```dart
+    // Example Repository
+    Future<Result<LoginResponse>> login(LoginRequest request) async {
+      try {
+        final response = await Api.request(
+          url: ApiUrl.login,
+          method: 'POST',
+          body: request.toJson(),
+        );
+        return Result.success(LoginResponse.fromJson(response));
+      } catch (e) {
+        // Dio errors are already toasted by Api class, 
+        // but we return Failure so BLoC knows to stop loading.
+        return Result.failure(ServerFailure(e.toString()));
+      }
+    }
+    ```
+
+## **Failure Types**
+
+-   **ServerFailure**: API returned 4xx/5xx or connection failed.
+-   **CacheFailure**: Local storage error.
+-   **ValidationFailure**: Invalid input (caught before API call).

package/templates/shared/skills/flutter-error-handling/references/error-mapping.md

@@ -0,0 +1,44 @@
+# Functional Failure Patterns
+
+## **Global Failures (No Code-gen)**
+
+```dart
+abstract class ApiFailure implements Exception {
+  const ApiFailure();
+}
+
+class ServerFailure extends ApiFailure {
+  const ServerFailure();
+}
+
+class NetworkFailure extends ApiFailure {
+  const NetworkFailure();
+}
+
+class UnauthenticatedFailure extends ApiFailure {
+  const UnauthenticatedFailure();
+}
+
+class BadRequestFailure extends ApiFailure {
+  final String message;
+  const BadRequestFailure(this.message);
+}
+```
+
+## **Infrastructure Mapper**
+
+```dart
+extension DioErrorX on DioException {
+  ApiFailure toFailure() {
+    switch (type) {
+      case DioExceptionType.connectionTimeout:
+        return const NetworkFailure();
+      case DioExceptionType.badResponse:
+        if (response?.statusCode == 401) return const UnauthenticatedFailure();
+        return const ServerFailure();
+      default:
+        return const ServerFailure();
+    }
+  }
+}
+```

package/templates/shared/skills/flutter-navigation-manager/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: Flutter Navigation Manager
+description: Routing strategy management (GetX is the Project Standard).
+---
+
+# Flutter Navigation Strategy
+
+## **Active Strategy: GetX**
+
+This project currently uses **GetX** for all navigation requirements.
+
+**Do NOT use:**
+- AutoRoute
+- GoRouter
+- Navigator 2.0 (Raw)
+
+## Guidelines
+
+### GetX Routing
+- **Configuration**: `lib/src/utils/app_pages.dart`
+- **Navigation**: `Get.toNamed()`, `Get.offNamed()`
+- **Bindings**: Attach dependencies via `binding` property in `GetPage`.
+
+### Prototype → Route Mapping Rules
+- **Full Screen (Hides BottomBar)**: Register the route in `AppPages` and use `Get.toNamed(AppPages.some)`. Back: `Navigator.pop(context)`.
+- **Nested Under BottomBar (Keeps Visible)**:
+  - Register routes in `lib/src/ui/routing/<tab>_router.dart` (or `common_router.dart` if shared).
+  - Use `Navigator.of(context).push(...)` to push onto the tab’s internal stack, avoiding root replacement.
+  - Back: `Navigator.pop(context)` (do not use `Get.back()` to avoid popping the wrong stack).
+- **Shared Page (Keeps BottomBar)**: Register in `common_router.dart` and use `Navigator.of(context)` within the current tab context.
+
+### Decision Heuristics (Prototype Mapping)
+- Destination keeps BottomBar visible → Nested route.
+- Destination covers entire screen (modal/full-screen) → Full screen GetX route.
+- Detail flow originating from the current tab (e.g., Customer → Customer Detail) → Nested.
+- Flow leaving tab context (e.g., Login, standalone Privacy Policy) → Full screen.
+
+### Arguments (GetX vs Navigator)
+- **GetX (Full Screen)**:
+  - Send: `Get.toNamed(AppPages.detail, arguments: {'id': 123, 'mode': 'edit'})`
+  - Receive: 
+    ```dart
+    final args = Get.arguments as Map<String, dynamic>;
+    final id = args['id'] as int;
+    final mode = args['mode'] as String?;
+    ```
+- **Navigator (Nested)**:
+  - Prefer constructor parameters for strong typing:
+    ```dart
+    Navigator.of(context).push(MaterialPageRoute(
+      builder: (_) => DetailPage(id: 123, mode: 'edit'),
+    ));
+    ```
+  - If using `settings.arguments`:
+    ```dart
+    Navigator.of(context).push(MaterialPageRoute(
+      settings: const RouteSettings(arguments: {'id': 123}),
+      builder: (_) => const DetailPage(),
+    ));
+    // In DetailPage (build):
+    final args = ModalRoute.of(context)?.settings.arguments as Map?;
+    ```
+  - Rule: Constructor > settings.arguments > Get.arguments in nested flows to avoid stack/context confusion.
+
+### Examples
+```dart
+// Full screen: hides BottomBar
+Get.toNamed(AppPages.visitRecord);
+// Back
+Navigator.pop(context);
+
+// Nested: keeps BottomBar
+Navigator.of(context).push(
+  MaterialPageRoute(builder: (_) => const CustomerDetailPage()),
+);
+// Back
+Navigator.pop(context);
+```
+
+## Related Topics
+getx-state-management | dependency-injection