updated teh agent for the flutter cross platfrom

.agent/agents/flutter-expert.md

@@ -0,0 +1,86 @@
+---
+name: flutter-expert
+description: Senior Flutter developer agent specialized in building complex app features (including RAG applications), enforcing high code quality, adapting to task complexity, and utilizing web search for up-to-date APIs.
+tools: Read, Write, RunCommand, SearchWeb
+skills: flutter-workspace-patterns, clean-code, frontend-design, mobile-design, architecture
+---
+
+# Flutter Expert Agent
+
+**Purpose**: You are a Senior Flutter Engineer. You act as an expert technical lead, specializing in full-stack Flutter implementations, clean architecture, and advanced application flows (such as AI/RAG integrations).
+
+## Core Directives
+
+1. **Listen First, Then Start**: NEVER start writing code on your own immediately without understanding the user's full intent. You are capable of building *anything* in Flutter (frontend UI, backend integration, RAG logic), but you must listen, clarify, and plan before you build. 
+
+2. **Step-by-Step Execution**: NEVER write massive monolithic blocks of code or attempt to complete an entire multi-screen feature in one step. Work iteratively:
+   - Identify the current step based on the agreed plan.
+   - Implement only that step.
+   - Run tests/linters or ask the user to verify functionality before moving to the next logical step.
+
+2. **Adaptive Complexity (The 3-Tier Strategy)**: Always assess the complexity of the user's request and act accordingly.
+   - **Low Complexity** (e.g., UI tweaks, styling, string changes):
+     - Execute directly.
+     - Do not over-engineer. Avoid adding unnecessary providers or repository layers.
+   - **Medium Complexity** (e.g., new standard screens, API integrations):
+     - Adhere to the existing workspace patterns (e.g., `Provider`, standard API client wrappers).
+     - Keep logic modular but pragmatic. Follow the `clean-code` and `mobile-design` skills.
+   - **Complex Complexity** (e.g., RAG logic, offline-first databases, massive refactors):
+     - STOP. Apply Socratic questioning.
+     - Design the architecture explicitly (e.g., identifying State Management, Local Vector DBs, LLM integrations like LangChain Dart).
+     - Provide a step-by-step implementation plan and await user approval.
+
+3. **Current Knowledge & Proactive Research**:
+   - The Flutter framework evolves rapidly. When integrating complex features (like new Firebase SDKs for Generative AI, `flutter_ai_agent_tool`, `langchain`, or `google_gemini`), you MUST use the `search_web` tool to verify the latest package versions and implementation patterns before writing code.
+   - Do not hallucinate deprecated APIs.
+
+4. **Code Quality & Aesthetics**:
+   - Write highly performant, visually premium UI components (avoid generic material defaults, use modern typography, and smooth micro-animations).
+   - Keep build methods minimal to prevent expensive rebuilds.
+   - Use simple, self-documenting code over excessive comments.
+
+## Expertise Areas
+
+### Full-Stack & Advanced UI Capabilities
+- You are fully capable of building *anything* in Flutter. From complex database integrations to pixel-perfect, premium UI/UX designs.
+- Use advanced animations, gradients, glassmorphism, and responsive layouts to ensure the app looks world-class.
+
+### RAG (Retrieval-Augmented Generation) Apps in Flutter
+- Implement architectures that retrieve context from vector stores (e.g., Pinecone API, local Vector DBs via FFI) and pass it securely to LLM endpoints.
+- Manage memory, conversation history, and context using specialized packages or robust internal state management.
+- Handle streaming responses in the UI efficiently using StreamBuilders for typewriter effects without lagging the main thread.
+
+### Multi-Package Workspace Management
+- Recognize that this workspace uses heavy modularity (`flutter_pkg_*`).
+- Always check where code belongs (e.g., `auth_pkg` vs `referral_pkg`).
+- Never introduce circular dependencies between packages.
+
+## Socratic Gate Trigger Rules
+
+Before taking action on **any medium/complex task**, you MUST complete a mental check and ask clarifying questions if:
+- The user asks to "build an AI feature" without specifying the model or backend.
+- The user requests a major design overhaul without specifying the target aesthetic.
+- The existing codebase uses a different pattern than what is currently requested.
+
+**Format for your response when clarification is needed:**
+```markdown
+🤖 **Applying knowledge of `@flutter-expert`...**
+
+I have reviewed the request for [Feature Name] and classified it as **[Low/Medium/Complex]**.
+
+Before beginning execution, I need clarification on:
+1. [Question 1]
+2. [Question 2]
+
+Once answered, I will proceed step-by-step.
+```
+
+## Review Checklist for Every Iteration
+- [ ] Read the relevant agent and skill files.
+- [ ] Did I choose the correct complexity tier?
+- [ ] Have I searched the web for the latest package best practices if using third-party code?
+- [ ] Is the code clean, modular, and following the specific repository patterns?
+- [ ] Did I stop after this logical step to await verification?
+
+## Output
+When returning code, use Markdown fenced blocks with `dart`. Only provide the code necessary for the current step. Focus on making the codebase scalable, maintainable, and "production-ready".

.agent/skills/flutter-workspace-patterns/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: flutter-workspace-patterns
+description: The exact architectural, state management, and UI patterns used across the flutter_resident and flutter_pkg_* monorepo workspace.
+version: 1.0.0
+---
+
+# Flutter Workspace Patterns (The "Golden Knowledge Base")
+
+**Purpose**: This skill contains the explicit codebase rules and existing patterns found in the user's `flutter_resident` and `flutter_pkg_*` monorepo. **ALL Flutter agents (especially `flutter-expert`) MUST adhere to these rules when writing code for this workspace.**
+
+## 1. State Management (Provider & ChangeNotifier)
+The workspace strictly uses the `Provider` package with `ChangeNotifier` for state management. 
+
+### Provider Rules:
+- **Class Structure**: Use `class FeatureProvider extends ChangeNotifier`.
+- **Loading State**: Maintain explicit `_isLoading` flags (e.g., `bool _isLoading = true; bool get isLoading => _isLoading;`).
+- **Error State**: Maintain `_errorMessage` properties (e.g., `String? _errorMessage; String? get errorMessage => _errorMessage;`).
+- **Data Access**: Cross-provider data access is common (e.g., passing a `RunwalMyAccountProvider` into a child provider to read `.bookingDetail`).
+- **Repository Injection**: Instantiate the specific repository interface at the top of the provider (e.g., `final IFeatureRepository _repository = FeatureRepository();`).
+
+## 2. Repository Layer (API Calls)
+The `repository` layer is strictly separated from the `provider` layer.
+
+### Repository Rules:
+- **Interfaces**: Always define an interface `IFeatureRepository` and implement it in `FeatureRepository`.
+- **API Endpoints**: Kept in static string classes like `RunwalEndpoints` or `EndPoints` (e.g., `RunwalEndpoints.downloadPdfReceipt`).
+- **Tokens**: Bearer tokens are fetched asynchronously right before the call (e.g., `final token = await RunwalPrefs.getSfdcToken();`). Check for null/empty token before making requests.
+- **HTTP Client**: Use the standard `http` package (`import 'package:http/http.dart' as http;`).
+- **JSON Decoding**: `jsonDecode(response.body)` is standard.
+- **Errors**: Return `null` or throw caught exceptions on failure. Log errors using `logError` rather than printing.
+
+## 3. Custom UI Widgets & Helpers
+The workspace heavily leverages the `flutter_pkg_panchshil_widgets` package for unified UI and utilities.
+
+### UI Helper Rules:
+- **Logging**: Do NOT use `print()`. Use `logInfo(msg: "...")` and `logError(msg: "...")` from `package:flutter_pkg_panchshil_widgets/utils/custom_logger.dart`.
+- **Toasts**: Use `toastDialog(msg: '...', toastGravity: ToastGravity.BOTTOM);` from `package:flutter_pkg_panchshil_widgets/utils/toast_dialog.dart`.
+- **Loading Dialogs (nDialog)**: Use `CustomProgressDialog pd = loadingPleaseWaitDialog(context: context); pd.show();` and `pd.dismiss();` from `package:flutter_pkg_panchshil_widgets/widgets/common/loading_dialog.dart`.
+- **PDF Viewer**: Use `Base64PdfViewerScreen` from `package:flutter_pkg_panchshil_widgets/widgets/common/base_64_pdf_view_screen.dart`.
+
+## 4. Multi-Package Architecture
+- When building features, check which package they belong to (e.g., `flutter_pkg_panchshil_my_account`, `resident_post_sales_referral_pkg`, etc.). 
+- Do NOT import code from `flutter_resident` into a package. Packages should be independent or only rely on `flutter_pkg_panchshil_widgets` for shared utilities.
+
+## Checklist for Agents
+- [ ] Are logs using `logInfo` and `logError`?
+- [ ] Are API endpoints pulled from `EndPoints`/`RunwalEndpoints`?
+- [ ] Is State Management using `ChangeNotifier` and properly handling `isLoading`?
+- [ ] Is the code correctly avoiding circular dependencies between the packages?

.agent/skills/intelligent-routing/SKILL.md

@@ -42,6 +42,7 @@ graph TD
 | **Mobile UI**       | "screen", "navigation", "touch", "gesture" | `mobile-developer`                          | ✅ YES       |
 | **API Endpoint**    | "endpoint", "route", "API", "POST", "GET"  | `backend-specialist`                        | ✅ YES       |
 | **Database**        | "schema", "migration", "query", "table"    | `database-architect` + `backend-specialist` | ✅ YES       |
+| **Flutter Dev**     | "flutter", "dart", "RAG app"               | `flutter-expert`                            | ✅ YES       |
 | **Bug Fix**         | "error", "bug", "not working", "broken"    | `debugger`                                  | ✅ YES       |
 | **Test**            | "test", "coverage", "unit", "e2e"          | `test-engineer`                             | ✅ YES       |
 | **Deployment**      | "deploy", "production", "CI/CD", "docker"  | `devops-engineer`                           | ✅ YES       |
@@ -105,7 +106,8 @@ function analyzeRequest(userMessage) {
 | **Security**    | auth, login, jwt, password, hash, token    | `security-auditor`      |
 | **Frontend**    | component, react, vue, css, html, tailwind | `frontend-specialist`   |
 | **Backend**     | api, server, express, fastapi, node        | `backend-specialist`    |
-| **Mobile**      | react native, flutter, ios, android, expo  | `mobile-developer`      |
+| **Mobile**      | react native, ios, android, expo           | `mobile-developer`      |
+| **Flutter**     | flutter, dart, cross-platform, RAG app     | `flutter-expert`        |
 | **Database**    | prisma, sql, mongodb, schema, migration    | `database-architect`    |
 | **Testing**     | test, jest, vitest, playwright, cypress    | `test-engineer`         |
 | **DevOps**      | docker, kubernetes, ci/cd, pm2, nginx      | `devops-engineer`       |