agent-flutter 0.1.1

package/templates/shared/skills/flutter-navigation-manager/references/REFERENCE.md

@@ -0,0 +1,71 @@
+# GetX Routing Reference
+
+Examples for implementing scalable routing with **GetX** and nested **Navigator** stacks.
+
+## References
+
+- [Router Configuration](router-config.md) — Standard setup with `AppPages`, `GetPage`, and `CommonRouter`.
+- [Skill: Flutter Navigation Manager](../SKILL.md) — Strategy, prototype mapping, and arguments.
+
+## Quick Navigation
+
+```dart
+// Full-screen route (hides BottomBar)
+Get.toNamed(AppPages.detail, arguments: {'id': 123});
+// Back
+Navigator.pop(context);
+```
+
+```dart
+// Nested route under BottomBar (keeps visible)
+Navigator.of(context).pushNamed(
+  AppPages.detail,
+  arguments: {'id': 123},
+);
+// Back
+Navigator.pop(context);
+```
+
+## Arguments
+
+```dart
+// GetX: send & receive
+Get.toNamed(AppPages.detail, arguments: {'id': 123, 'mode': 'edit'});
+final args = Get.arguments as Map<String, dynamic>;
+final id = args['id'] as int;
+final mode = args['mode'] as String?;
+```
+
+```dart
+// Navigator: prefer pushNamed with arguments
+Navigator.of(context).pushNamed(
+  AppPages.detail,
+  arguments: {'id': 123, 'mode': 'edit'},
+);
+// Receive in the destination page
+final args = ModalRoute.of(context)?.settings.arguments as Map<String, dynamic>?;
+final id = args?['id'] as int?;
+final mode = args?['mode'] as String?;
+```
+
+## Bindings
+
+Use bindings with routes to initialize dependencies:
+
+```dart
+// AppPages (GetPage)
+GetPage(
+  name: AppPages.notification,
+  page: () => const NotificationPage(),
+  binding: NotificationBinding(),
+);
+```
+
+```dart
+// CommonRouter (nested/shared) using GetPageRoute
+return GetPageRoute(
+  page: () => const NotificationPage(),
+  settings: settings,
+  binding: NotificationBinding(),
+);
+```

package/templates/shared/skills/flutter-navigation-manager/references/router-config.md

@@ -0,0 +1,57 @@
+# Router Configuration (GetX)
+
+## AppPages Configuration
+Located in `lib/src/utils/app_pages.dart`.
+
+```dart
+import 'package:get/get.dart';
+import 'package:link_home/src/ui/home/home_page.dart';
+import 'package:link_home/src/ui/auth/login/login_page.dart';
+import 'package:link_home/src/ui/auth/login/binding/login_binding.dart';
+
+class AppPages {
+  static const String login = _Paths.login;
+  static const String home = _Paths.home;
+
+  static final pages = [
+    GetPage(
+      name: _Paths.login,
+      page: () => const LoginPage(),
+      binding: LoginBinding(), // Attach Binding
+    ),
+    GetPage(
+      name: _Paths.home,
+      page: () => const HomePage(),
+    ),
+  ];
+}
+
+abstract class _Paths {
+  static const String login = "/login";
+  static const String home = "/home";
+}
+```
+
+## Common Router (Nested/Shared)
+Located in `lib/src/ui/routing/common_router.dart`.
+Used for handling routes that might be accessible from multiple entry points or require custom transitions.
+
+```dart
+class CommonRouter {
+  static Route<dynamic>? onGenerateRoute(RouteSettings settings) {
+    switch (settings.name) {
+      case AppPages.notification:
+        return GetPageRoute(
+          page: () => const NotificationPage(),
+          settings: settings,
+          binding: NotificationBinding(),
+        );
+      default:
+        return GetPageRoute(
+          page: () => const NotFoundPage(),
+          settings: settings,
+        );
+    }
+  }
+}
+```

package/templates/shared/skills/flutter-standard-lib-src-architecture/SKILL.md

@@ -0,0 +1,89 @@
+# Standard lib/src Architecture
+
+## **Priority: P0 (CRITICAL)**
+
+Standard folder architecture for Flutter apps organized under `lib/src/`.
+
+## Structure
+
+```text
+lib/
+└── src/
+    ├── api/
+    ├── core/
+    │   ├── model/
+    │   │   ├── request/   # API Request Bodies (DTOs)
+    │   │   └── response/  # API Response Objects (DTOs)
+    ├── di/
+    ├── enums/
+    ├── extensions/
+    ├── helper/
+    ├── locale/
+    ├── ui/
+    │   ├── <page_name>/
+    │   │   ├── binding/
+    │   │   ├── components/
+    │   │   └── interactor/
+    │   └── widgets/
+    └── utils/
+```
+
+## Implementation Guidelines
+
+- **Page Modules**: Each screen/flow is a module under `lib/src/ui/<page_name>/`.
+- **Page Naming**: Page file MUST be named `<page_name>_page.dart` (e.g., `page_a_page.dart`).
+- **Folder Roles**:
+  - `ui/<page>/binding/`: routing + dependency wiring for that page module.
+  - `ui/<page>/interactor/`: state + business logic for that page module.
+  - `ui/<page>/components/`: page-specific UI blocks.
+  - `ui/widgets/`: shared UI widgets reused across pages.
+  - `di/`: global dependency registration (app-level modules).
+  - `api/`: networking clients, repositories/services (no UI).
+  - `core/model/`: **Data Transfer Objects (DTOs)**.
+    - `request/`: Models sent TO the server (e.g., `LoginRequest`).
+    - `response/`: Models received FROM the server (e.g., `LoginResponse`).
+    - *Note*: Shared domain entities can sit directly in `core/model/`.
+  - `core/`: cross-cutting infrastructure (router, theme, localization plumbing, error mapping, etc.).
+  - `utils/`: app-wide constants/styles/helpers that are safe to import anywhere.
+
+- **Dependency Rule**:
+  - `components`/`widgets`/page UI → may depend on `interactor`.
+  - `interactor` → may depend on `api`, `core`, and `utils`.
+  - `api`/`core` → must not depend on `ui`.
+  - `binding` is the only place inside a page module allowed to import `di`.
+
+## UI: Component Extraction (P0)
+
+Any **visually meaningful UI block** must be extracted into a component file.
+
+### What counts as “visually meaningful”
+
+- A block users can visually identify as a unit (Header, SearchBar, Card, Section, BottomSheet content).
+- A repeated layout (e.g., list item / card appears 2+ times).
+- A block with its own spacing/background/border/gradient.
+- A block that would make the page widget harder to scan if kept inline.
+
+### Folder convention
+
+```text
+lib/src/ui/<page_name>/
+├── binding/
+├── interactor/
+├── components/
+└── <page_name>_page.dart
+```
+
+Shared components live in:
+
+```text
+lib/src/ui/widgets/
+```
+
+## Reference & Examples
+
+For page module blueprints and DI guidance:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+dependency-injection | go-router-navigation | getx-localization | error-handling

package/templates/shared/skills/flutter-standard-lib-src-architecture/references/REFERENCE.md

@@ -0,0 +1,19 @@
+# Standard lib/src Architecture Reference
+
+Detailed examples for organizing Flutter apps using the standard `lib/src` structure.
+
+## References
+
+- [**Standard Folder Structure**](folder-structure.md) - Deep dive into `lib/src` directory nesting.
+- [**Core vs Shared UI**](shared-core.md) - When to put code in `core`, `ui/widgets`, or keep it page-local.
+- [**Modular Injection**](modular-injection.md) - How to wire dependencies per page module + global DI.
+
+## **Quick Implementation Rule**
+
+- Page-local code stays page-local:
+  - Do not import `lib/src/ui/<page>/components/` from other pages.
+  - Do not import `lib/src/ui/<page>/binding/` from other pages.
+- If something is reused by multiple pages, move it to:
+  - `lib/src/ui/widgets/` (UI)
+  - `lib/src/core/` (infrastructure)
+  - `lib/src/utils/` (constants/styles)

package/templates/shared/skills/flutter-standard-lib-src-architecture/references/folder-structure.md

@@ -0,0 +1,35 @@
+# Standard lib/src Folder Structure
+
+A complete blueprint for the standard `lib/src` structure and a single page module.
+
+```text
+lib/src/
+├── api/
+├── core/
+├── di/
+├── enums/
+├── extensions/
+├── helper/
+├── locale/
+├── ui/
+│   ├── authentication/
+│   │   ├── binding/
+│   │   │   └── authentication_binding.dart
+│   │   ├── components/
+│   │   │   └── login_form.dart
+│   │   ├── interactor/
+│   │   │   └── authentication_interactor.dart
+│   │   └── authentication_page.dart
+│   └── widgets/
+│       └── app_button.dart
+└── utils/
+    ├── app_styles.dart
+    ├── app_colors.dart
+    └── app_pages.dart
+```
+
+## **Key Constraints**
+
+1. **Page Encapsulation**: `ui/<page>/components` and `ui/<page>/binding` are page-private.
+2. **Shared UI**: If reused by multiple pages, move it to `ui/widgets/`.
+3. **No UI in API/Core**: `api/` and `core/` must not import from `ui/`.

package/templates/shared/skills/flutter-standard-lib-src-architecture/references/modular-injection.md

@@ -0,0 +1,27 @@
+# Modular Injection (Per Page Module)
+
+This describes how to keep dependency wiring modular in the standard `lib/src` architecture.
+
+## Goal
+
+- Each page module owns its own bindings (wiring for that module).
+- App composition wires global dependencies in `lib/src/di/`.
+
+## Suggested Structure
+
+```text
+lib/src/
+├── di/
+│   ├── di.dart
+│   └── modules/
+└── ui/
+    └── <page>/
+        └── binding/
+            └── <page>_binding.dart
+```
+
+## Rules
+
+- Global DI registers shared services (clients, storage, repositories) in `di/modules/`.
+- Page binding registers only page-scoped objects (interactors/controllers) for that page.
+- UI code must not register dependencies outside `binding/` and `di/`.

package/templates/shared/skills/flutter-standard-lib-src-architecture/references/shared-core.md

@@ -0,0 +1,29 @@
+# Core vs Shared UI
+
+Use this rule to decide where code should live in a standard `lib/src` codebase.
+
+## Core (`lib/src/core/`)
+
+Put code here when it is:
+- Cross-cutting infrastructure (router, theme, localization, networking base, logging)
+- App-wide and not tied to any specific page
+- Safe to be imported by any page module
+
+## Shared UI (`lib/src/ui/widgets/`)
+
+Put code here when it is:
+- UI building blocks reused by multiple pages (buttons, form fields, empty states)
+- Design system widgets (app button, app text, skeletons)
+- Not “infrastructure”, but still reusable UI
+
+## Page-local (`lib/src/ui/<page>/...`)
+
+Default choice. Keep code inside the feature when it is:
+- Only used by one page (UI components, interactor logic, page validators/helpers)
+- Tightly coupled to that page flow
+
+## Rule of Thumb
+
+- If only one page uses it → keep it in that page.
+- If many pages use it and it’s infrastructure-like → `core/`.
+- If many pages use it and it’s UI → `ui/widgets/`.

package/templates/shared/skills/flutter-standard-lib-src-architecture-dependency-rules/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: Flutter Standard lib/src Architecture (Dependency Rules)
+description: Dependency flow and separation of concerns for the project (UI -> BLoC -> Repository).
+---
+
+# Project Architecture & Dependency Rules
+
+## **Priority: P0 (CRITICAL)**
+
+This project follows a feature-based Clean Architecture adapted for Flutter.
+
+## Structure
+
+```text
+lib/src/
+├── api/                  # API definitions & DTOs
+├── core/
+│   └── repository/       # Data Layer (Repositories)
+├── di/                   # Dependency Injection Setup
+├── ui/                   # Presentation Layer
+│   ├── <feature>/
+│   │   ├── binding/      # DI Bindings
+│   │   ├── bloc/         # OR interactor/ (Business Logic)
+│   │   └── <page>.dart   # UI Widget
+│   └── routing/          # Routing Logic
+└── utils/                # Helpers & Constants
+```
+
+## Dependency Flow
+
+**UI** (`ui/<feature>`) 
+  ↓ calls
+**BLoC** (`ui/<feature>/bloc` or `interactor`)
+  ↓ calls
+**Repository** (`core/repository`)
+  ↓ calls
+**API / Local Storage**
+
+## Rules
+
+### 1. Presentation Layer (UI)
+- **Responsibility**: Render UI, handle user input, listen to State.
+- **Dependencies**: Can depend on `BLoC` (via `BlocBuilder`/`BlocListener`).
+- **Forbidden**: NO direct API calls. NO direct Repository access.
+
+### 2. Business Logic Layer (BLoC/Interactor)
+- **Responsibility**: State management, business logic, calling repositories.
+- **Dependencies**: Can depend on `Repository`.
+- **Forbidden**: NO UI widgets (`BuildContext`, `Scaffold`).
+
+### 3. Data Layer (Repository)
+- **Responsibility**: Coordinate data sources (Remote API, Local DB).
+- **Dependencies**: `Api`, `SharedPreference`, etc.
+- **Forbidden**: NO knowledge of UI or BLoC.
+
+## Reference & Examples
+
+See [references/repository-mapping.md](references/repository-mapping.md).

package/templates/shared/skills/flutter-standard-lib-src-architecture-dependency-rules/references/REFERENCE.md

@@ -0,0 +1,113 @@
+# Reference: Standard lib/src Architecture Examples
+
+This reference shows how the standard `lib/src` structure maps to responsibilities:
+
+- `ui/<page>/interactor`: state + business logic
+- `api/`: DTOs + repositories + remote data sources
+- `di/` and `ui/<page>/binding`: dependency wiring
+
+## Example: Interactor + Repository + DTO mapping
+
+### 1) App model (used by Interactors / UI)
+
+```dart
+class BankModel {
+  final String id;
+  final String name;
+  final String branchCode;
+
+  const BankModel({
+    required this.id,
+    required this.name,
+    required this.branchCode,
+  });
+}
+```
+
+### 2) DTO + mapper (in `lib/src/api/`)
+
+```dart
+class BankDto {
+  final String id;
+  final String name;
+  final String branchCode;
+
+  const BankDto({
+    required this.id,
+    required this.name,
+    required this.branchCode,
+  });
+
+  factory BankDto.fromJson(Map<String, dynamic> json) => BankDto(
+        id: json['bank_id'] as String,
+        name: json['bank_name'] as String,
+        branchCode: json['code'] as String,
+      );
+
+  BankModel toModel() => BankModel(id: id, name: name, branchCode: branchCode);
+}
+```
+
+### 3) Repository (in `lib/src/api/`)
+
+```dart
+abstract class IBankRepository {
+  Future<Result<List<BankModel>>> fetchBanks();
+}
+
+class BankRepository implements IBankRepository {
+  final BankRemoteDataSource remoteDataSource;
+
+  BankRepository(this.remoteDataSource);
+
+  @override
+  Future<Result<List<BankModel>>> fetchBanks() async {
+    try {
+      final dtoList = await remoteDataSource.getBanks();
+      final banks = dtoList.map((dto) => dto.toModel()).toList();
+      return Success(banks);
+    } catch (e) {
+      return FailureResult(ApiFailure.fromException(e));
+    }
+  }
+}
+```
+
+### 4) Interactor (in `lib/src/ui/<page>/interactor/`)
+
+```dart
+enum BankStatus { initial, loading, loaded, failure }
+
+class BankInteractor extends Equatable {
+  final IBankRepository repository;
+  final BankStatus status;
+  final List<BankModel> banks;
+  final String? message;
+
+  const BankInteractor({
+    required this.repository,
+    this.status = BankStatus.initial,
+    this.banks = const [],
+    this.message,
+  });
+
+  Future<BankInteractor> fetch() async {
+    final result = await repository.fetchBanks();
+    return switch (result) {
+      Success(value: final banks) => BankInteractor(
+          repository: repository,
+          status: BankStatus.loaded,
+          banks: banks,
+        ),
+      FailureResult(failure: final failure) => BankInteractor(
+          repository: repository,
+          status: BankStatus.failure,
+          message: failure.message,
+        ),
+    };
+  }
+
+  @override
+  List<Object?> get props => [status, banks, message];
+}
+```

package/templates/shared/skills/flutter-standard-lib-src-architecture-dependency-rules/references/repository-mapping.md

@@ -0,0 +1,48 @@
+# Repository & BLoC Mapping
+
+## Repository Pattern
+Repositories act as the bridge between Data Sources (API) and the Domain/Business Logic.
+
+```dart
+// lib/src/core/repository/auth_repository.dart
+class AuthRepository extends Api {
+  final AppShared _appShared;
+  final IAuthApiUrl _authUrl;
+
+  AuthRepository(this._appShared, this._authUrl);
+
+  Future<void> login(Map<String, dynamic> payload) async {
+    final res = await request(
+      _authUrl.login,
+      Method.post,
+      body: payload,
+    );
+    // Save token, handle data
+  }
+}
+```
+
+## BLoC Implementation
+BLoCs use repositories to fetch data and emit states.
+
+```dart
+// lib/src/ui/notification/interactor/notification_bloc.dart
+class NotificationBloc extends Bloc<NotificationEvent, NotificationState> {
+  // Inject Repository if needed
+  // final NotificationRepository _repo;
+
+  NotificationBloc() : super(const NotificationState()) {
+    on<NotificationInitialized>(_onInitialized);
+  }
+
+  Future<void> _onInitialized(event, emit) async {
+    emit(state.copyWith(pageState: PageState.loading));
+    try {
+      // await _repo.fetchNotifications();
+      emit(state.copyWith(pageState: PageState.success));
+    } catch (e) {
+      emit(state.copyWith(pageState: PageState.failure));
+    }
+  }
+}
+```