ai-flow-dev 2.1.2 → 2.1.4

package/prompts/mobile/flow-docs-sync.md

@@ -3,28 +3,24 @@
 **YOU ARE AN EXPERT MOBILE ARCHITECT AND DOCUMENTATION SPECIALIST.**
 
 Your mission is to detect changes in the mobile codebase and update the project documentation automatically when the user executes `/flow-docs-sync`.
-
----
-
+---
 ## Command: `/flow-docs-sync`
 
 ### Objective
 
-Detect changes in the mobile codebase compared to the last documented state (stored in `.ai-flow/analysis.json`) and update all affected documentation files automatically.
-
----
-
+Detect changes in the mobile codebase compared to the last documented state (stored in `.ai-flow/cache/docs-analysis.json`) and update all affected documentation files automatically.
+---
 ## Execution Flow
 
 ### Step 1: Check for Analysis File
 
 ```
-First, check if `.ai-flow/analysis.json` exists:
+First, check if `.ai-flow/cache/docs-analysis.json` exists:
 
 - ✅ If exists → Proceed to Step 2 (Compare Changes)
 - ❌ If NOT exists → Execute full Phase 0 analysis first:
   - Run complete mobile code analysis (as described in Phase 0)
-  - Create `.ai-flow/analysis.json` with current state
+  - Create `.ai-flow/cache/docs-analysis.json` with current state
   - Then proceed to Step 2
 ```
 
@@ -47,7 +43,7 @@ First, check if `.ai-flow/analysis.json` exists:
 
 2. **Compare with Previous State:**
 
-   - Load `.ai-flow/analysis.json`
+   - Load `.ai-flow/cache/docs-analysis.json`
    - Compare current state vs previous state
    - Detect changes in:
      - **Screens:** New, modified, or deleted screens
@@ -173,9 +169,9 @@ No updates required.
    - Update app store configuration if app.json or build config changed
    - Maintain existing configuration
 
-2. **Update `analysis.json`:**
+2. **Update `docs-analysis.json`:**
 
-   - Save current state to `.ai-flow/analysis.json`
+   - Save current state to `.ai-flow/cache/docs-analysis.json`
    - Update timestamp
    - Include all detected changes in metadata
 
@@ -208,7 +204,7 @@ No updates required.
 📝 specs/build-configuration.md
 - Updated build.gradle configuration
 
-✅ analysis.json updated with new state
+✅ docs-analysis.json updated with new state
 ```
 
 ### Step 5: Handle Cancellation
@@ -218,9 +214,7 @@ No updates required.
 ```
 Update cancelled. Run `/flow-docs-sync` when you're ready to update the documentation.
 ```
-
----
-
+---
 ## Change Detection Rules
 
 ### Screens Detection
@@ -341,9 +335,7 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
 
 - Add new variables to configuration spec
 - Maintain existing variables
-
----
-
+---
 ## Important Rules
 
 1. **Incremental Updates Only:**
@@ -360,7 +352,7 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
 
 3. **Update Analysis File:**
 
-   - Always update `.ai-flow/analysis.json` after document updates
+   - Always update `.ai-flow/cache/docs-analysis.json` after document updates
    - Include timestamp and change summary
    - Save complete current state for next comparison
 
@@ -369,9 +361,7 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
    - Regenerate navigation diagrams when screens change
    - Regenerate architecture diagrams when structure changes
    - Use mermaid format for all diagrams
-
----
-
+---
 ## 📊 MOBILE DIAGRAM REGENERATION GUIDELINES
 
 When regenerating mobile diagrams, follow these **critical** formatting rules:
@@ -437,9 +427,7 @@ graph TD
     style P1 fill:#fff4e6
 ```
 ````
-
----
-
+---
 ### State Management Diagrams (state-management.md)
 
 **Diagram Types:** `graph LR`, `sequenceDiagram`, `graph TD`
@@ -495,9 +483,7 @@ sequenceDiagram
     Note over Cache: Cache valid for 5min
 ```
 ````
-
----
-
+---
 ### Testing Diagrams (testing.md)
 
 **Diagram Type:** `graph TB`
@@ -535,9 +521,7 @@ graph TB
     style UNIT fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
 ```
 ````
-
----
-
+---
 ### Common Formatting Rules (ALL Mobile Diagrams)
 
 **CRITICAL - Code Fence Syntax:**
@@ -583,16 +567,12 @@ graph TB
 - Show device vs emulator distinction in testing diagrams
 - Include deep linking routes in navigation diagrams
 - Highlight authentication flows and protected routes
-
----
-
+---
 5. **Error Handling:**
    - If document doesn't exist, create it following template
-   - If analysis.json is corrupted, regenerate it
+   - If docs-analysis.json is corrupted, regenerate it
    - If comparison fails, show error and suggest full Phase 0 re-run
-
----
-
+---
 ## Example Execution
 
 ```
@@ -622,14 +602,15 @@ AI:
 - Added new permission (Location)
 - Updated permission handling section
 
-✅ analysis.json updated with new state
+✅ docs-analysis.json updated with new state
 
 Documentation synchronized successfully.
 ```
+---
+**BEGIN EXECUTION when user runs `/flow-docs-sync`**
+
 
----
 
-**BEGIN EXECUTION when user runs `/flow-docs-sync`**
 
 
 

package/prompts/shared/mermaid-guidelines.md

@@ -0,0 +1,106 @@
+# 🎨 Mermaid Diagram Guidelines
+
+Follow these critical rules for all Mermaid diagrams to ensure they render correctly in GitHub, VS Code, and other markdown viewers.
+
+## 🛠️ General Rules
+
+- **Code Fence:** ALWAYS use exactly ` ```mermaid ` (lowercase, no spaces).
+- **NO Indentation:** Do not indent the diagram code with spaces or tabs.
+- **Closing Fence:** Always close with ` ``` `.
+- **Validation:** Preview at [mermaid.live](https://mermaid.live/) if unsure.
+---
+## 📊 Entity Relationship (ER) Diagrams
+
+**Type:** `erDiagram`
+
+### Relationship Notation
+
+- `||--o{` : One-to-Many (one to zero or more)
+- `||--||` : One-to-One (one to exactly one)
+- `}o--o{` : Many-to-Many (requires junction table)
+- `||--|{` : One-to-Many (one to one or more)
+
+### Field Notation
+
+- `PK` : Primary Key
+- `FK` : Foreign Key
+- `UK` : Unique Key
+- Add descriptions in quotes: `string email "User email address"`
+
+### Example
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    USER {
+        string id PK
+        string email UK
+        string name
+    }
+    ORDER {
+        string id PK
+        string userId FK
+        decimal total
+    }
+```
+---
+## 📐 Architecture & Flow Diagrams
+
+**Type:** `graph TD` (Top-Down) or `graph LR` (Left-Right)
+
+### Node Shapes
+
+- `[Square]` : Services, components, apps
+- `[(Cylinder)]` : Databases, storage
+- `([Rounded])` : Start/End points
+- `{Diamond}` : Decision points
+
+### Styling
+
+- Use `<br/>` for line breaks in labels.
+- Apply colors: `style NodeName fill:#e1f5ff`
+- Label connections: `A -->|HTTPS| B`
+
+### Example
+
+```mermaid
+graph TD
+    Client[Web App] -->|API Call| API[Node.js API]
+    API -->|Query| DB[(PostgreSQL)]
+    style Client fill:#e1f5ff
+    style API fill:#fff4e1
+    style DB fill:#e1ffe1
+```
+---
+## 🔄 Business Flow Diagrams
+
+**Type:** `flowchart TD` (or `flowchart LR`)
+
+### Requirements
+
+- Start/End with `([Terminal Node])`.
+- Use `{Diamond}` for decision points.
+- Label branches: `-->|Yes|` or `-->|No|`.
+- Show error/failure paths.
+
+### Example
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Action[Action]
+    Action --> Decision{Success?}
+    Decision -->|Yes| End([Success])
+    Decision -->|No| Fail([Failed])
+    style Start fill:#e1f5ff
+    style End fill:#e1ffe1
+    style Fail fill:#ffe1e1
+```
+---
+## ⚠️ Common Mistakes to Avoid
+
+- ❌ ` ```Mermaid ` (Capital M)
+- ❌ ` ``` mermaid ` (Extra space)
+- ❌ Using invalid characters in node IDs (use `NodeID[Label]` instead)
+- ❌ Circular dependencies without clear flow
+
+

package/prompts/shared/scope-levels.md

@@ -0,0 +1,126 @@
+# Project Scope Levels
+
+> **Canonical definition of MVP, Production-Ready, and Enterprise scope levels.**
+>
+> This file defines how scope affects phase execution, question depth, and technology choices across all AI Flow workflows.
+---
+## Scope Level Summary
+---
+| Scope                | Symbol | Duration (Backend) | Phases    | Best For                           |
+| -------------------- | ------ | ------------------ | --------- | ---------------------------------- |
+| **MVP**              | 🚀     | 60-80 min          | Core only | Prototypes, proof of concept       |
+| **Production-Ready** | ⭐     | 90-120 min         | All       | Production apps, client projects   |
+| **Enterprise**       | 🏆     | 120-160 min        | Extended  | Large-scale, mission-critical apps |
+---
+## MVP Scope 🚀
+---
+### Characteristics
+
+- **Phases included:** Core phases only (Phase 1-4 in backend)
+- **Question depth:** Simplified, essential questions only
+- **Technology choices:** Simple, proven defaults
+
+### Technology Defaults
+
+| Category       | MVP Choice                     |
+| -------------- | ------------------------------ |
+| Database       | PostgreSQL (single instance)   |
+| ORM            | Framework-idiomatic            |
+| Caching        | None or in-memory              |
+| Search         | Database LIKE queries          |
+| Architecture   | Monolith                       |
+| API Style      | REST only                      |
+| Authentication | JWT (basic)                    |
+| Authorization  | RBAC (simple roles)            |
+| Password       | bcrypt, 8+ chars               |
+| Git Workflow   | GitHub Flow                    |
+| Test Coverage  | 15-25%                         |
+| Test Types     | Unit tests only                |
+| Deployment     | PaaS (Heroku, Railway, Render) |
+| Monitoring     | Basic (health checks, logs)    |
+---
+## Production-Ready Scope ⭐
+---
+### Characteristics
+
+- **Phases included:** All phases (1-7/8)
+- **Question depth:** Complete professional coverage
+- **Technology choices:** Robust, scalable defaults
+
+### Technology Defaults
+
+| Category       | Production Choice                   |
+| -------------- | ----------------------------------- |
+| Database       | PostgreSQL (managed)                |
+| ORM            | Framework-idiomatic                 |
+| Caching        | Redis                               |
+| Search         | PostgreSQL Full-Text or Meilisearch |
+| Architecture   | Clean Architecture                  |
+| API Style      | REST + GraphQL (optional)           |
+| Authentication | JWT + Refresh Tokens                |
+| Authorization  | RBAC (granular permissions)         |
+| Password       | bcrypt 12 rounds, 12+ chars         |
+| Git Workflow   | Git Flow                            |
+| Test Coverage  | 70%                                 |
+| Test Types     | Unit, Integration, E2E              |
+| Deployment     | Cloud (AWS/GCP/Azure)               |
+| Monitoring     | APM (Datadog/New Relic) + Sentry    |
+---
+## Enterprise Scope 🏆
+---
+### Characteristics
+
+- **Phases included:** All phases with extended questions
+- **Question depth:** Advanced, comprehensive
+- **Technology choices:** Enterprise-grade, highly scalable
+
+### Technology Defaults
+
+| Category       | Enterprise Choice                      |
+| -------------- | -------------------------------------- |
+| Database       | PostgreSQL (multi-region/sharded)      |
+| ORM            | Framework-idiomatic                    |
+| Caching        | Redis Cluster                          |
+| Search         | Elasticsearch                          |
+| Architecture   | Microservices / Domain-Driven Design   |
+| API Style      | REST + GraphQL + gRPC                  |
+| Authentication | OAuth2 + SSO + MFA                     |
+| Authorization  | ABAC (Attribute-Based)                 |
+| Password       | bcrypt 14 rounds, 16+ chars, policies  |
+| Git Workflow   | Git Flow + Release branches            |
+| Test Coverage  | 85%+                                   |
+| Test Types     | Unit, Integration, E2E, Load, Security |
+| Deployment     | Multi-region, Kubernetes               |
+| Monitoring     | Full observability stack               |
+---
+## Scope Selection Prompt
+---
+```
+---
+🎯 Project Scope Selection
+---
+What scope level do you want for this documentation?
+
+A) 🚀 **MVP** (60-80 min) - Core features only, minimal setup
+   - Core phases only
+   - Simple architecture
+   - Basic testing
+   - Best for: Prototypes, proof of concept
+
+B) ⭐ **Production-Ready** (90-120 min) - Complete professional setup
+   - All phases
+   - Robust architecture
+   - Comprehensive testing + CI/CD
+   - Best for: Production apps, client projects
+
+C) 🏆 **Enterprise** (120-160 min) - Advanced features and scalability
+   - All phases with extended questions
+   - Enterprise architecture
+   - Full observability + compliance
+   - Best for: Large-scale, mission-critical apps
+
+Your choice (A/B/C):
+```
+
+
+

package/prompts/shared/story-points.md

@@ -0,0 +1,65 @@
+# Story Points Reference
+
+> **Canonical reference for Fibonacci-based Story Point estimation across all AI Flow phases.**
+>
+> This file is the single source of truth for Story Points. All phases that require SP estimation MUST reference this file.
+---
+## Story Points Scale (Fibonacci)
+---
+| Story Points | Complexity | Typical Time | Examples                               |
+| ------------ | ---------- | ------------ | -------------------------------------- |
+| **1 SP**     | Trivial    | 1-2 hours    | Add simple field, update enum          |
+| **2 SP**     | Very Small | 2-4 hours    | Basic validation, simple test          |
+| **3 SP**     | Small      | 4-8 hours    | Simple CRUD endpoint, basic entity     |
+| **5 SP**     | Medium     | 1-2 days     | Complex endpoint with business logic   |
+| **8 SP**     | Complex    | 2-3 days     | Auth flow, complex validation          |
+| **13 SP**    | Large      | 1 week       | Complete module with full tests        |
+| **21 SP**    | Very Large | 2 weeks      | Major feature with integration         |
+| **34 SP**    | Epic       | 3 weeks      | Multiple related features (Epic-level) |
+---
+## Story Points to Time Conversion (Hybrid Estimation)
+---
+Use this table to add time estimates to each task:
+
+| Story Points | Time Estimate (solo dev) | Time Range | Example Task                            |
+| ------------ | ------------------------ | ---------- | --------------------------------------- |
+| **1 SP**     | 1-2 hours                | (~1-2h)    | Add enum value, simple config change    |
+| **2 SP**     | 3-4 hours                | (~3-4h)    | Write 5-8 unit tests, basic validation  |
+| **3 SP**     | 4-8 hours                | (~4-8h)    | Simple CRUD endpoint, basic entity      |
+| **5 SP**     | 1-2 days                 | (~1-2d)    | Complex endpoint with business logic    |
+| **8 SP**     | 2-3 days                 | (~2-3d)    | Auth flow, complex validation           |
+| **13 SP**    | 1 week                   | (~1w)      | Complete module with full test coverage |
+| **21 SP**    | 2 weeks                  | (~2w)      | Major feature with integration          |
+| **34 SP**    | 3 weeks                  | (~3w)      | Multiple related features (Epic-level)  |
+
+> **Note:** Time assumes AI-assisted development (GitHub Copilot, Claude, etc.). Without AI assistance, multiply time estimates by 2-3x.
+>
+> **Velocity Tracking:** After completing 2-3 features, compare actual time vs estimates to calibrate your team's velocity. Adjust remaining estimates accordingly.
+---
+## Epic Estimation Guidelines
+---
+- **Foundation Epic:** 13-21 SP (depends on framework complexity)
+- **Data Layer Epic:** 3-5 SP per simple entity, 8-13 SP per complex entity
+- **Auth Epic:** 8 SP (basic JWT) to 21 SP (multi-provider + RBAC + 2FA)
+- **Business Epics:** Varies by domain complexity
+- **Integration Epic:** 5-8 SP per external service
+- **Operations Epic:** 13 SP (standard CI/CD + monitoring)
+---
+## Feature Size Classification
+---
+| Size        | Task Count | Phases  | Characteristics                                    |
+| ----------- | ---------- | ------- | -------------------------------------------------- |
+| **SMALL**   | 1-10 tasks | 1 phase | Single file changes, isolated                      |
+| **MEDIUM**  | 11-40      | 2-4     | Multiple files, some cross-layer dependencies      |
+| **COMPLEX** | 41-80      | 4-8     | Multiple modules, integration, extensive testing   |
+| **LARGE**   | 81+        | 8-N     | Feature affecting entire system, major refactoring |
+---
+## How to Use Hybrid Estimation
+---
+- Each task shows **both** Story Points and time: `• 2 SP (~3-4h)`
+- Story Points measure **complexity** (stable across teams)
+- Time estimates measure **effort** (varies by team velocity)
+- Track both to improve estimation accuracy over time
+
+
+

package/prompts/shared/task-format.md

@@ -0,0 +1,86 @@
+# Task Format Reference (Spec-Kit Inspired)
+
+> **Canonical task format for all AI Flow development workflows.**
+>
+> This file defines the standard task format used in Phase 9 (Roadmap), /feature, /fix, and all development commands.
+---
+## Standard Task Format
+---
+**Every task must follow this format:**
+
+```markdown
+- [ ] [TaskID] [Optional:P] [Optional:StoryTag] Description • SP (~time)
+      File: exact/path/to/file.ts
+      Dependencies: T001, T002 (or "None")
+```
+---
+## Format Components
+---
+| Component       | Required | Description                                                              |
+| --------------- | -------- | ------------------------------------------------------------------------ |
+| `[TaskID]`      | ✅       | Sequential ID in execution order (T001, T002, ..., T099, T100)           |
+| `[P]`           | ❌       | Parallelization marker - ONLY for tasks that can run simultaneously      |
+| `[StoryTag]`    | ❌       | Links task to user story ([US1], [US2]) - only in story-based phases     |
+| `Description`   | ✅       | What to implement (specific, LLM-completable without additional context) |
+| `• SP (~time)`  | ✅       | Hybrid estimation - Story Points + time (e.g., "2 SP (~3-4h)")           |
+| `File:`         | ✅       | Exact file path where work happens                                       |
+| `Dependencies:` | ✅       | Which tasks must complete first (even if "None")                         |
+---
+## Task Sequencing Rules
+---
+1. **Tests BEFORE implementation** (TDD approach)
+2. **Models → Services → Controllers → Endpoints** (layer dependency order)
+3. **Core utilities BEFORE features** that use them
+4. **Database migrations BEFORE data access code**
+5. **Interfaces BEFORE implementations**
+---
+## Parallelization Rules ([P] Marker)
+---
+### ✅ Use [P] When:
+
+- Tasks target **different files**
+- No shared dependencies between tasks
+- Can run simultaneously (e.g., independent entities, different modules)
+
+### ❌ Don't Use [P] When:
+
+- Task depends on another incomplete task
+- Same file is modified by multiple tasks
+- Shared resource (DB migration, config file, shared service)
+---
+## Complete Task Example
+---
+```markdown
+- [ ] [T042] [P] Write unit tests for Product entity validation (12 tests) • 2 SP (~3-4h)
+      File: tests/unit/entities/Product.entity.spec.ts
+      Tests: price validation, stock constraints, name required, category FK
+      Dependencies: None (can run parallel with other test tasks)
+```
+---
+## Feature Template
+---
+```markdown
+### Feature {{NUMBER}}: {{FEATURE_NAME}} • {{SP}} SP (~{{TIME}})
+
+**Scope:** {{ENTITY}} entity + {{ENDPOINT_COUNT}} endpoints + {{TEST_COUNT}} tests
+
+**Tasks:**
+
+- [ ] T0XX [P] Write {{ENTITY}} entity tests • 2 SP (~3-4h) → tests/unit/{{ENTITY}}.spec.ts
+- [ ] T0YY Create {{ENTITY}} entity • 2 SP (~3-4h) → src/entities/{{ENTITY}}.ts
+- [ ] T0ZZ Create I{{REPOSITORY}} interface • 1 SP (~1-2h) → src/repositories/I{{REPOSITORY}}.ts
+- [ ] T0AA Implement {{REPOSITORY}} • 2 SP (~3-4h) → src/repositories/{{REPOSITORY}}.ts (after T0YY, T0ZZ)
+- [ ] T0BB Implement {{SERVICE}} business logic • 3 SP (~4-8h) → src/services/{{SERVICE}}.ts (after T0AA)
+- [ ] T0CC Create {{CONTROLLER}} endpoints • 2 SP (~3-4h) → src/controllers/{{CONTROLLER}}.ts (after T0BB)
+- [ ] T0DD [P] Write integration tests • 2 SP (~3-4h) → tests/integration/{{CONTROLLER}}.spec.ts
+- [ ] T0EE [P] Update API docs • 1 SP (~1h) → docs/api.md
+
+**Parallel:** T0XX, T0DD, T0EE can run together
+
+**Done when:** All endpoints work + tests pass + coverage ≥ {{COVERAGE}}%
+
+**Start:** `/feature new "{{FEATURE_NAME}}"`
+```
+
+
+