ai-flow-dev 2.1.3 → 2.1.5

package/prompts/backend/flow-build-phase-2.md

@@ -142,13 +142,9 @@ C) Activity → (User | Organization | Deal) - activities linked to various obje
 D) Other: __
 
 → Your selection (e.g., A, C): __
-
 ---
-
 Your specific relationships (list main ones):
-
 ---
-
 Your specific relationships (list main ones):
 -
 -
@@ -226,6 +222,155 @@ H) 🗂️ Partitioning - Split large tables by date/region/etc.
 For each selected, provide brief detail:
 ```
 
+**2.7.1 Soft Delete Configuration** (if A selected above)
+
+```
+How will you handle data deletion?
+
+Field for soft delete:
+A) ⭐ deleted_at (timestamp, null = active) - Recommended
+B) is_deleted (boolean)
+C) status field (e.g., status = 'deleted')
+D) Custom: __
+
+Entities with SOFT delete (keep record, mark as deleted):
+- Users ✅
+- Orders ✅
+- Products ✅
+- [List yours...]
+
+Entities with HARD delete (permanent removal):
+- Session tokens
+- Temporary files
+- Cart items after checkout
+- [List yours...]
+
+Permanent cleanup policy:
+A) ⭐ Purge soft-deleted after __ days (recommended: 90)
+B) Archive to cold storage after __ days
+C) Never delete (compliance requirement)
+
+Default query behavior:
+A) ⭐ Exclude deleted by default (add scope/filter)
+B) Include all, filter explicitly
+```
+
+**2.7.2 State Machines** (for entities with lifecycle states)
+
+```
+Do any entities have defined state lifecycles?
+
+A) ⭐ Yes - Define state machines
+B) No - Simple status fields without transitions
+
+If yes, define for each entity:
+
+---
+Entity: Order (example)
+States: [draft, pending, confirmed, shipped, delivered, cancelled, refunded]
+
+Valid Transitions:
+- draft → pending (action: submit)
+- pending → confirmed (action: pay) [requires: payment_id]
+- pending → cancelled (action: cancel, or timeout: 24h)
+- confirmed → shipped (action: ship) [requires: tracking_number]
+- shipped → delivered (action: deliver)
+- confirmed → refunded (action: refund)
+- delivered → refunded (action: refund) [within: 30 days]
+
+Invalid Transitions (explicitly forbidden):
+- shipped → cancelled (cannot cancel after shipping)
+- delivered → cancelled
+
+Side Effects:
+- pending → confirmed: send confirmation email, reserve inventory
+- confirmed → cancelled: release inventory, refund payment
+- shipped → delivered: send delivery notification
+---
+
+Your state machines:
+
+Entity: __
+States: __
+Transitions: __
+```
+
+**2.7.1 Domain-Driven Design Concepts** (Production-Ready and Enterprise only)
+
+```
+Will you use Domain-Driven Design (DDD) patterns?
+
+A) ⭐ Yes - Using DDD tactical patterns
+   - Aggregate Roots for transactional boundaries
+   - Value Objects for immutable data
+   - Domain Events for decoupling
+
+B) 🔥 Partial - Only Aggregate Roots
+   - Define aggregate roots for complex domains
+   - Keep entities grouped by aggregate
+
+C) No - Simple CRUD patterns
+   - Standard entity relationships
+   - No aggregate boundaries
+
+If using DDD (A or B):
+
+What are your Aggregate Roots?
+(Aggregate roots are the entry points to groups of related entities)
+
+Examples:
+- Order (with OrderItems, Shipping, Payment)
+- User (with Profile, Preferences, Settings)
+- Project (with Tasks, Members, Files)
+
+Your Aggregate Roots:
+1. __ (contains: __)
+2. __ (contains: __)
+3. __ (contains: __)
+
+Domain Events (things that happen in your domain):
+- UserRegistered
+- OrderPlaced
+- PaymentCompleted
+- etc.
+
+Your key domain events:
+1.
+2.
+3.
+```
+
+**2.7.4 Transaction Boundaries**
+
+```
+Which operations require database transactions?
+
+List operations that must be atomic (all-or-nothing):
+
+1. User Registration:
+   - Create User record
+   - Create Profile record
+   - Send welcome email (queue, not in transaction)
+   → Rollback if: User or Profile creation fails
+
+2. Order Creation:
+   - Create Order record
+   - Create OrderItems
+   - Reserve inventory
+   - Charge payment
+   → Rollback if: Any step fails
+
+3. [Your operations]:
+   - Step 1
+   - Step 2
+   → Rollback if: __
+
+Your transactional operations:
+1.
+2.
+3.
+```
+
 **2.8 Database Indexes**
 
 ```
@@ -362,86 +507,9 @@ Is this correct? (Yes/No)
 
 #### 🎨 MERMAID ER DIAGRAM FORMAT - CRITICAL
 
-**Use this exact format** (lowercase `mermaid`, no spaces, three backticks):
-
-````markdown
-```mermaid
-erDiagram
-    USER ||--o{ ORDER : places
-    USER ||--o{ REVIEW : writes
-    PRODUCT ||--o{ ORDER_ITEM : contains
-    ORDER ||--o{ ORDER_ITEM : includes
-
-    USER {
-        string id PK "Primary Key"
-        string email UK "Unique Key"
-        string name
-        string hashedPassword
-        datetime createdAt
-        datetime updatedAt
-    }
-
-    ORDER {
-        string id PK
-        string userId FK "Foreign Key to USER"
-        decimal total
-        string status "pending, completed, cancelled"
-        datetime createdAt
-    }
-
-    PRODUCT {
-        string id PK
-        string name
-        text description
-        decimal price
-        int stock
-        datetime createdAt
-    }
-
-    ORDER_ITEM {
-        string id PK
-        string orderId FK
-        string productId FK
-        int quantity
-        decimal price
-    }
-
-    REVIEW {
-        string id PK
-        string userId FK
-        string productId FK
-        int rating "1-5 stars"
-        text comment
-        datetime createdAt
-    }
-```
-````
-
-**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 after field type for clarity
-
-**Common Mistakes to Avoid:**
-
-- ❌ `​```Mermaid` (capital M - will not render)
-- ❌ `​``` mermaid` (extra space - will not render)
-- ❌ Indenting the entire diagram with spaces/tabs
-- ❌ Missing closing ` ``` ` fence
-- ❌ Invalid entity/relationship syntax
-
-**Validation:** Preview your diagram at https://mermaid.live/ or in VS Code markdown preview
+> 📎 **Reference:** See [prompts/shared/mermaid-guidelines.md](../shared/mermaid-guidelines.md) for ER diagram syntax, relationship notation, and common mistakes.
 
----
+## **Example ER Diagram:**
 
 ```
 ✅ Generated: docs/data-model.md
@@ -463,8 +531,6 @@ Execute `read_file('docs/data-model.md')` to refresh context before continuing.
 
 ---
 
-**Proceed to Phase 3 after document is generated and optionally reviewed.**
-
----
+## **Proceed to Phase 3 after document is generated and optionally reviewed.**
 
 ## PHASE 3: System Architecture (15-20 min)

package/prompts/backend/flow-build-phase-3.md

@@ -20,66 +20,9 @@ Define the technical stack, architecture patterns, and system design.
 
 #### 🎨 MERMAID ARCHITECTURE DIAGRAM FORMAT - CRITICAL
 
-**Use this exact format** for system architecture diagrams:
+> 📎 **Reference:** See [prompts/shared/mermaid-guidelines.md](../shared/mermaid-guidelines.md) for architecture diagram syntax, node shapes, and styling.
 
-````markdown
-```mermaid
-graph TD
-    Client[Client Application<br/>React/Mobile/Web]
-    LB[Load Balancer<br/>Nginx/ALB]
-    API[API Gateway<br/>Node.js/Express]
-    Auth[Auth Service<br/>JWT/OAuth]
-    Business[Business Logic Layer]
-    DB[(Primary Database<br/>PostgreSQL)]
-    Cache[(Redis Cache<br/>Session & Data)]
-    Queue[Message Queue<br/>RabbitMQ/SQS]
-    Storage[File Storage<br/>S3/MinIO]
-    Email[Email Service<br/>SendGrid/SES]
-    Monitor[Monitoring<br/>Prometheus/DataDog]
-
-    Client -->|HTTPS| LB
-    LB -->|Forward| API
-    API -->|Verify Token| Auth
-    API -->|Business Rules| Business
-    Business -->|Query/Write| DB
-    Business -->|Cache Check| Cache
-    Business -->|Async Tasks| Queue
-    Business -->|Upload/Download| Storage
-    Queue -->|Send Email| Email
-    API -->|Metrics| Monitor
-    Business -->|Logs| Monitor
-
-    style Client fill:#e1f5ff
-    style API fill:#fff4e1
-    style Auth fill:#ffe1e1
-    style DB fill:#e1ffe1
-    style Cache fill:#f0e1ff
-    style Queue fill:#ffe1f5
-```
-````
-
-**Diagram Types:**
-
-- `graph TD` = Top-Down flow (recommended for most architectures)
-- `graph LR` = Left-Right flow (good for linear pipelines)
-- `graph BT` = Bottom-Top (less common)
-- `graph RL` = Right-Left (less common)
-
-**Node Shapes:**
-
-- `[Square Brackets]` = Services, applications, components
-- `[(Cylinder)]` = Databases, persistent storage
-- `([Rounded])` = Start/End points
-- `{Diamond}` = Decision points
-- `[[Double Square]]` = Subroutines
-- `[/Parallelogram/]` = Input/Output
-
-**Styling:**
-
-- Use `<br/>` for line breaks in node labels
-- Apply styles with: `style NodeName fill:#colorcode`
-- Label connections: `A -->|Label Text| B`
-- Use consistent colors for component types
+**Example Architecture Diagram:**
 
 **Common Architecture Patterns:**
 
@@ -127,9 +70,7 @@ graph TD
 - Label protocols on connections (HTTPS, gRPC, WebSocket)
 - Use consistent naming conventions
 
-**Validation:** Preview at https://mermaid.live/ before committing
-
----
+## **Validation:** Preview at https://mermaid.live/ before committing
 
 **3.1 Backend Framework**
 
@@ -329,12 +270,115 @@ Please answer the following questions to define the global API conventions (thes
 10. If you want to customize an endpoint (e.g., add special logic, validations, or unique parameters), describe the case here:
 
 - [Brief description, example endpoint, parameters, special logic]
-
 ---
-
 The AI will use these conventions to automatically document all CRUD endpoints for each entity in api.md. If you need additional or custom endpoints, you can add them manually later.
 ````
 
+**3.5.1 Error Codes Catalog**
+
+```
+Will you use standardized error codes?
+
+A) ⭐ Yes - Domain-specific error codes (recommended for APIs)
+B) No - HTTP status codes only
+
+If yes, define your error code format:
+
+Format:
+A) ⭐ Prefixed by domain: USER_001, ORDER_003, PAYMENT_005
+B) Numeric ranges: 1000-1999 (Users), 2000-2999 (Orders)
+C) Other: __
+
+Define your error codes:
+
+| Code          | HTTP | Message                        | Resolution                    |
+|---------------|------|--------------------------------|-------------------------------|
+| USER_001      | 404  | User not found                 | Verify user ID exists         |
+| USER_002      | 409  | Email already registered       | Use different email or login  |
+| USER_003      | 400  | Invalid email format           | Provide valid email           |
+| AUTH_001      | 401  | Invalid credentials            | Check username/password       |
+| AUTH_002      | 401  | Token expired                  | Refresh or re-authenticate    |
+| AUTH_003      | 403  | Insufficient permissions       | Contact administrator         |
+| ORDER_001     | 400  | Empty cart                     | Add items before checkout     |
+| ORDER_002     | 400  | Insufficient stock             | Reduce quantity or wait       |
+| PAYMENT_001   | 402  | Payment declined               | Try different payment method  |
+| VALIDATION_001| 400  | Required field missing         | Provide all required fields   |
+
+Your error codes:
+| Code | HTTP | Message | Resolution |
+|------|------|---------|------------|
+|      |      |         |            |
+```
+
+**3.5.2 Input Validation Rules Catalog**
+
+```
+Define validation rules for common fields across your API:
+
+| Field Type     | Rules                                    | Error Message                    |
+|----------------|------------------------------------------|----------------------------------|
+| email          | valid format, max 255, lowercase         | Invalid email format             |
+| password       | min 8, uppercase, lowercase, number      | Password too weak                |
+| username       | min 3, max 30, alphanumeric, no spaces   | Invalid username format          |
+| phone          | E.164 format or local format             | Invalid phone number             |
+| url            | valid URL, https only (optional)         | Invalid URL format               |
+| date           | ISO 8601 format, not in past (optional)  | Invalid date format              |
+| price/amount   | positive, max 2 decimals                 | Invalid amount                   |
+| quantity       | positive integer, max 9999               | Invalid quantity                 |
+| id (UUID)      | valid UUID v4 format                     | Invalid ID format                |
+| slug           | lowercase, hyphens only, max 100         | Invalid slug format              |
+
+Entity-specific validation (example):
+
+User:
+- firstName: required, min 2, max 50, letters only
+- lastName: required, min 2, max 50, letters only
+- birthDate: valid date, must be 18+ years ago
+
+Product:
+- name: required, min 3, max 100
+- price: required, positive, max 999999.99
+- sku: required, unique, uppercase, alphanumeric
+
+Your entity validations:
+
+Entity: __
+- field: [rules]
+
+Entity: __
+- field: [rules]
+```
+
+**3.5.3 Idempotency Strategy**
+
+```
+How will you handle duplicate requests (critical for payments, orders)?
+
+A) ⭐ Idempotency keys - Client sends unique key per request
+B) Natural idempotency - Use unique constraints (email, etc.)
+C) Not needed - Operations are naturally idempotent
+D) Combination of A + B
+
+If using idempotency keys (A):
+
+Header name:
+A) ⭐ Idempotency-Key (standard)
+B) X-Request-ID
+C) Custom: __
+
+Key storage:
+A) ⭐ Redis with TTL (recommended)
+B) Database table
+
+TTL: __ hours (recommended: 24)
+
+Which endpoints require idempotency?
+- POST /orders ✅
+- POST /payments ✅
+- POST /users ✅
+- [Your endpoints]: __
+```
+
 **3.6 Key Dependencies**
 
 ```
@@ -598,9 +642,7 @@ D) Accounting (QuickBooks, Xero)
 E) Other: __
 
 → Your selection (e.g., A, B, C): __
-
 ---
-
 For each selected, briefly describe the use case:
 D) Other: __
 
@@ -610,9 +652,7 @@ B) Calendar (Google/Outlook)
 C) CRM (Salesforce, HubSpot)
 D) Accounting (QuickBooks, Xero)
 E) Other: __
-
 ---
-
 For each selected, briefly describe the use case:
 
 Example:

package/prompts/backend/flow-build-phase-4.md

@@ -461,9 +461,7 @@ Input Validation: [strategy + sanitization rules + size limits + file upload val
 
 Is this correct? (Yes/No)
 ```
-
----
-
+---
 ### 📄 Generate Phase 4 Documents
 
 **Before starting generation:**
@@ -503,13 +501,12 @@ Documents have been created with all Phase 4 information.
 
 **If user edits files:**
 Re-read files to refresh context before continuing.
-
----
-
+---
 **Proceed to Phase 5 only after documents are validated.**
 
 > ⚠️ **CRITICAL:** DO NOT generate README.md in this phase. README.md is ONLY generated in Phase 8 (step 8.5) after framework initialization.
+---
+## PHASE 5: Development Standards (15-20 min)
+
 
----
 
-## PHASE 5: Development Standards (15-20 min)

package/prompts/backend/flow-build-phase-5.md

@@ -1,12 +1,12 @@
 ## PHASE 5: Code Standards (15-20 min)
 
-> **Order for this phase:** 5.1 → 5.2 → 5.3 → 5.4 → 5.5 → 5.6 → 5.7 → 5.8 → 5.9 → 5.10 → 5.11
+> **Order for this phase:** 5.1 → 5.2 → 5.3 → 5.4 → 5.5 → 5.6 → 5.7 → 5.8 → 5.9 → 5.10 → 5.11 → 5.12 → 5.13
 
 > **📌 Scope-based behavior:**
 >
-> - **MVP:** Ask 5.1-5.5 only (formatting, naming, structure, coverage target, Git workflow), skip 5.6-5.11 (advanced practices)
-> - **Production-Ready:** Ask all questions 5.1-5.11
-> - **Enterprise:** Ask all questions 5.1-5.11 with emphasis on governance and documentation
+> - **MVP:** Ask 5.1-5.5 only (formatting, naming, structure, coverage target, Git workflow), skip 5.6-5.13 (advanced practices)
+> - **Production-Ready:** Ask all questions 5.1-5.13
+> - **Enterprise:** Ask all questions 5.1-5.13 with emphasis on governance and documentation
 
 ### Objective
 
@@ -198,9 +198,7 @@ src/
     Extensions/
 
 Benefits: Scalable, easy to find related code, clear module boundaries
-
 ---
-
 B) 🏆 Feature-based (Flat) - Simple projects
 
 Flat structure within each feature (AI will adapt naming):
@@ -218,9 +216,7 @@ src/
     ...
 
 Benefits: Simpler, fewer folders, good for small projects
-
 ---
-
 C) Layer-based (Traditional) - Legacy style
 
 Group by technical layer/type (AI will adapt naming):
@@ -244,9 +240,7 @@ src/
 
 Benefits: Clear separation by type, familiar for MVC developers
 Drawbacks: Hard to see feature boundaries, files scattered
-
 ---
-
 D) Hybrid - Domain + Shared layers
 
 Modules for features + shared technical folders (AI will adapt):
@@ -266,9 +260,7 @@ src/
 
 Your choice: __
 Why?
-
 ---
-
 After you select, the AI will generate the exact folder structure with proper:
 - File extensions (.ts, .py, .java, .go)
 - Naming conventions (camelCase, snake_case, PascalCase)
@@ -564,6 +556,40 @@ E) Other: __
 Log retention: __ days
 ```
 
+**5.13 Custom Project Rules**
+
+```
+Do you have any project-specific rules for AI assistants?
+
+❌ NEVER Rules (things that should NEVER be done):
+
+Examples of NEVER rules:
+- Never use ORM X, always use ORM Y
+- Never modify files in the /legacy folder
+- Never use inline styles in components
+- Never bypass the API gateway
+
+Your custom NEVER rules:
+1. __
+2. __
+3. __
+(Leave blank if none)
+
+✅ ALWAYS Rules (things that should ALWAYS be done):
+
+Examples of ALWAYS rules:
+- Always use the company's error handling wrapper
+- Always include tenant_id in database queries
+- Always use the shared logging utility
+- Always run security scan before commit
+
+Your custom ALWAYS rules:
+1. __
+2. __
+3. __
+(Leave blank if none)
+```
+
 ### Phase 5 Output
 
 ```
@@ -581,6 +607,7 @@ Complexity: [function length, cyclomatic complexity, parameters, nesting depth l
 Git: [commit format (conventional/simple), branch naming convention]
 Versioning: [scheme (SemVer/Date), migration strategy, changelog method, responsibility]
 Logging Standards: [format (JSON/text), levels, context, aggregation tool, retention]
+Custom Rules: [NEVER rules count, ALWAYS rules count]
 
 Is this correct? (Yes/No)
 ```

package/prompts/backend/flow-build-phase-6.md

@@ -3,8 +3,8 @@
 > **Order for this phase:**
 >
 > - **MVP:** 6.1 → 6.2 (smoke tests) → 6.7 (CI basics)
-> - **Production-Ready:** 6.1 → 6.2 → 6.3 → 6.4 → 6.5 → 6.6 → 6.7
-> - **Enterprise:** 6.1 → 6.2 → 6.3 → 6.4 → 6.5 → 6.6 → 6.7 → 6.8 → 6.9
+> - **Production-Ready:** 6.1 → 6.1b → 6.2 → 6.3 → 6.4 → 6.5 → 6.6 → 6.7
+> - **Enterprise:** 6.1 → 6.1b → 6.2 → 6.3 → 6.4 → 6.5 → 6.6 → 6.7 → 6.8 → 6.9
 
 > **📌 Scope-based behavior:**
 >
@@ -46,6 +46,33 @@ Mocking library: **
 
 ```
 
+**6.1b Testing Philosophy** (Production-Ready and Enterprise only)
+
+```
+What is your testing philosophy?
+
+A) ⭐ Test-First (TDD) - Write tests before code
+   - Red-Green-Refactor cycle
+   - Higher initial effort, better design
+   - Best for: Complex business logic, critical systems
+
+B) 🔥 Test-After - Write tests after implementation
+   - Faster initial development
+   - Risk of untested edge cases
+   - Best for: Rapid prototyping, time-sensitive features
+
+C) ⚡ Behavior-Driven (BDD) - Write tests as specifications
+   - Given/When/Then format
+   - Business-readable tests
+   - Best for: Domain-heavy applications
+
+D) 🏆 Hybrid - TDD for core logic, test-after for simple features
+   - Balance of speed and quality
+   - Pragmatic approach
+
+Your choice: __
+```
+
 **6.2 Test Types**
 
 ```
@@ -417,9 +444,7 @@ Status: Exhaustive testing strategy with advanced scenarios
 
 Is this correct? (Yes/No)
 ```
-
 ---
-
 ### 📄 Generate Phase 6 Documents
 
 **Before starting generation:**
@@ -451,14 +476,10 @@ Document has been created with all Phase 6 information.
 
 **If user edits file:**
 Re-read file to refresh context before continuing.
-
 ---
-
 **Proceed to Phase 7 only after documents are validated.**
 
 > ⚠️ **CRITICAL:** DO NOT generate README.md in this phase. README.md is ONLY generated in Phase 8 (step 8.5) after framework initialization.
-
 ---
-
 ## PHASE 7: Operations & Deployment (10 min)
 ````