ai-flow-dev 2.2.0 → 2.2.4

package/prompts/frontend/flow-build-phase-1.md

@@ -1,33 +1,54 @@
-# Phase 1: Discovery & UX Requirements
+## PHASE 1: Discovery & Business (15-20 min)
+
+> **Order for this phase:** 1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6 → 1.7 → 1.8 → 1.9 → 1.10
+
+> **📌 Scope-based behavior:**
+> - **MVP/Basic Scope:** Focus only on core requirements. Skip advanced business logic questions.
+> - **Production-Ready Scope:** In-depth exploration of compliance, scalability, and long-term business goals.
+
+### Objective
+Define the project's core purpose, business rules, and high-level requirements to ensure the foundation is solid before technical design begins.
 
-**Duration:** 15-20 minutes
-**Questions:** ~11 questions
-**Output:** project-brief.md, parts of AGENT.md
 ---
-## 🎯 Objective
 
-Understand the **user-facing aspects** and core goal of the application:
+## 🔍 Pre-Flight Check (Smart Skip Logic)
+
+> 📎 **Reference:** See [prompts/shared/smart-skip-preflight.md](../shared/smart-skip-preflight.md) for the complete smart skip logic.
+
+**Execute Pre-Flight Check for Phase 1:**
+
+- **Target File**: `project-brief.md`
+- **Phase Name**: "BUSINESS CONTEXT"
+- **Key Items**: Project name, description, users, objectives, system type, features, scope, constraints, metrics, business flows
+- **Typical Gaps**: Business objectives, success metrics, constraints
+
+**Proceed with appropriate scenario based on audit data from `.ai-flow/cache/audit-data.json`**
 
-1. What is the core goal and purpose of the project?
-2. What type of application is being built?
-3. Who are the target users?
-4. What are the key user journeys?
-5. What devices and browsers must be supported?
-6. What are the UX priorities?
 ---
-## 📋 Questions
 
-### Question 1.1: Project Name & Description (with Smart Refinement)
+## Phase 1 Questions (Full Mode)
+
+> **📌 Note:** If Phase 0 was executed, some questions may already be answered. Skip those and only ask what's missing.
+
+**1.1 Project Name & Description (with Smart Refinement)**
 
 > **🧠 Intelligent Refinement System**: This question detects vague descriptions and guides the developer to enrich them. It only asks what's missing and responds in the developer's language.
 
 ```
+[If detected from Phase 0, show:]
+✅ Project Name: [detected name]
+✅ Description: [detected description]
+
+Is this correct? (Y/N)
+If no, please provide correct values.
+
+[If NOT detected, ask:]
 What is the project name?
 
 Provide an initial description of your project.
 (Don't worry about perfection - we'll refine it together if needed!)
 
-Example: "A frontend dashboard for managing inventory in real-time"
+Example: "A backend for managing gym memberships"
 ```
 
 **🔍 AI Internal: Ambiguity Analysis**
@@ -36,10 +57,10 @@ After receiving the description, silently analyze for these criteria:
 
 | Criterion | Check For | Score +1 if present |
 |-----------|-----------|---------------------|
-| **WHO** | Specific user type mentioned (not just "users") | "store managers", "traders", "students" |
-| **WHAT** | Specific action/function (not just "view", "show") | "compare prices", "edit profiles", "visualize data" |
-| **WHY** | Purpose or value mentioned | "to increase conversion", "to save time", "to improve UX" |
-| **DOMAIN** | Industry/vertical indicated | "fintech", "e-commerce", "social media" |
+| **WHO** | Specific user type mentioned (not just "users") | "gym members", "restaurant owners" |
+| **WHAT** | Specific action/function (not just "manage") | "track workouts", "process payments" |
+| **WHY** | Purpose or value mentioned | "to replace spreadsheets", "to launch app" |
+| **DOMAIN** | Industry/vertical indicated | "fitness", "fintech", "healthcare" |
 | **DETAIL** | Description has 10+ meaningful words | Not counting articles |
 
 **Scoring Rules:**
@@ -62,27 +83,28 @@ Your description: "[original description]"
 [ONLY show questions for MISSING criteria:]
 
 [If WHO is missing:]
-1️⃣ WHO will use this application?
+1️⃣ WHO will use this system?
    A) End consumers (B2C)
    B) Business users (B2B)
-   C) Internal team / Admin
-   D) Other: __
+   C) Internal team
+   D) Other systems (APIs)
+   E) Other: __
 
 [If WHAT is missing:]
-2️⃣ WHAT is the core UX action users will perform?
-   A) Browse & Shop
-   B) Manage & Configure
-   C) Read & Consume
-   D) Create & Publish
-   E) Analyze & Visualize
+2️⃣ WHAT is the core action users will perform?
+   A) Buy/sell products or services
+   B) Manage/organize information
+   C) Communicate/collaborate
+   D) Monitor/analyze data
+   E) Create/publish content
    F) Other: __
 
 [If WHY is missing:]
 3️⃣ WHY is this project needed?
-   A) Launch new product
-   B) Replace legacy UI
-   C) Better mobile experience
-   D) Specific new feature
+   A) Replace manual/legacy process
+   B) Launch new product/business
+   C) Improve existing system
+   D) Enable new capability
    E) Other: __
 
 [If DOMAIN is missing:]
@@ -95,7 +117,7 @@ Your description: "[original description]"
    F) Business tools (CRM, ERP)
    G) Other: __
 
-Your answers: __
+Your answers: __ (e.g., "A, B, A, E" or describe freely)
 ```
 
 ---
@@ -110,488 +132,495 @@ After gathering missing info, generate 3 polished versions:
 ✨ Based on your input, here are 3 professional descriptions:
 
 A) Concise (for package.json):
-   "[Generated 1-line description]"
+   "[Generated 1-line description with WHO + WHAT]"
 
 B) Descriptive (for README.md):
-   "[Generated 2-3 line description with UX focus]"
+   "[Generated 2-3 line description with WHO + WHAT + WHY]"
 
-C) Creative (for Marketing/Landing):
-   "[Generated catchy description]"
+C) Technical (for AGENT.md):
+   "[Generated technical description with DOMAIN + WHAT]"
 
 Which do you prefer? (1-3, or 4 to edit, 5 to start over)
 ```
 
-**Your choice:**
-
 ---
 
-### Question 1.2: Application Type
-
-**What type of frontend application are you building?**
+**✅ Final Confirmation**
 
-A) ⭐ **Single Page Application (SPA)**
+```
+✅ Your final project description:
 
-- Example: Gmail, Notion, Figma
-- Characteristics: Client-side routing, dynamic updates, minimal page reloads
-- Best for: Web apps, dashboards, admin panels
+📋 Name: [project name]
+📝 Description: "[final polished description]"
 
-B) 🔥 **Multi-Page Application (MPA)**
+Proceed to next question? (Y to continue)
+```
 
-- Example: E-commerce sites, blogs, marketing sites
-- Characteristics: Server-rendered pages, traditional navigation
-- Best for: Content-heavy sites, SEO-critical apps
+---
 
-C) ⚡ **Progressive Web App (PWA)**
+**1.2 Project Overview (Confirmation + Expansion)**
 
-- Example: Twitter Lite, Starbucks PWA
-- Characteristics: Offline support, installable, push notifications
-- Best for: Mobile-first apps, offline-first experiences
+> **📌 Smart Skip**: If 1.1 already captured WHO/WHAT/WHY completely, this becomes a quick confirmation.
 
-D) 🏆 **Server-Side Rendered (SSR) App**
+```
+[If 1.1 refinement was complete (score >= 4), show:]
 
-- Example: Next.js apps, Nuxt apps
-- Characteristics: Initial server render, hydration, SEO-friendly
-- Best for: Hybrid apps, dynamic content with SEO needs
+✅ Based on your description, I understand:
+   • Users: [WHO from 1.1]
+   • Core Action: [WHAT from 1.1]
+   • Purpose: [WHY from 1.1]
 
-E) **Static Site (SSG)**
+Is this complete? (Y) Or would you like to add more context? (N)
 
-- Example: Documentation sites, portfolios
-- Characteristics: Pre-rendered at build time, fast, CDN-friendly
-- Best for: Blogs, documentation, landing pages
+[If user says Y → Skip to 1.3]
+[If user says N → Ask:]
+What additional context would you like to add?
 
-**Your answer:**
 ---
-### Question 1.3: Target Users (Confirmation + Expansion)
 
-```
-[If WHO was captured in 1.1, show:]
+[If 1.1 was NOT refined OR any WHO/WHAT/WHY still missing, ask:]
 
-✅ Based on your description, your target users are: [WHO from 1.1]
+[ONLY ask for MISSING elements - check what was NOT captured in 1.1:]
 
-Describe your user personas more deeply (3-5 bullet points):
+[If WHO still unclear:]
+Who are the primary users of this system?
 
-- Demographics (age, tech-savviness, etc.)
-- Use cases / goals
-- Device preferences
-- Accessibility needs
+[If WHAT still unclear:]
+What is the core value proposition?
 
----
+[If WHY still unclear:]
+What makes this project necessary?
 
-[If WHO was NOT captured in 1.1, ask normally:]
+Example:
+"A backend for a fitness tracking mobile app used by gym-goers (users). It allows users to log workouts, track progress over time, and share achievements with friends (value). This project is necessary to replace our legacy spreadsheet-based system and support our new iOS app launch."
+```
 
-Who are your primary target users?
+**1.3 Target Users (Confirmation + Additional Types)**
 
-Describe your user personas (3-5 bullet points):
+> **📌 Smart Skip**: If 1.1 already identified user types, this confirms and expands.
 
-- Demographics (age, tech-savviness, etc.)
-- Use cases / goals
-- Device preferences
-- Accessibility needs
 ```
+[If WHO was captured in 1.1, show:]
 
-**Example:**
-
-```
-- Small business owners (30-50 years old, moderate tech skills)
-- Goal: Manage inventory and track sales
-- Devices: Desktop (70%), Mobile (30%)
-- Accessibility: WCAG 2.1 AA compliance required
-```
+✅ Based on your description, your target users are: [WHO from 1.1]
 
-**Your answer:**
----
-### Question 1.4: Key User Journeys (Confirmation + Expansion)
+Would you like to add any additional user types? Select any that apply:
 
-```
-[If WHAT was captured in 1.1, show:]
+A) 🌐 External end-users (B2C) - Public-facing application
+B) 🏢 Internal employees (B2B/Enterprise) - Company internal tool
+C) 🔌 Other systems/services (API consumers) - Integration platform
+D) 👥 Partners/Third-parties - Partner ecosystem
+E) 📱 Mobile/Web apps - Backend for frontend
+F) ✅ No additional users - [WHO from 1.1] is complete
 
-✅ Based on your description, a core journey is: [WHAT from 1.1]
+---
 
-What are the 3-5 most critical user flows?
+[If WHO was NOT captured in 1.1, ask normally:]
 
----
+Who will use this system? Select all that apply:
 
-[If WHAT was NOT captured in 1.1, ask normally:]
+A) 🌐 External end-users (B2C) - Public-facing application
+B) 🏢 Internal employees (B2B/Enterprise) - Company internal tool
+C) 🔌 Other systems/services (API consumers) - Integration platform
+D) 👥 Partners/Third-parties - Partner ecosystem
+E) 📱 Mobile/Web apps - Backend for frontend
 
-What are the 3-5 most critical user flows?
+(Can select multiple)
 ```
 
-**Example:**
+**1.4 Business Objectives**
 
 ```
-1. Sign up → Email verification → Onboarding wizard → Dashboard
-2. Create new project → Add team members → Set up integrations
-3. Browse products → Add to cart → Checkout → Payment confirmation
-4. Search for content → Filter results → View details → Save favorite
+What are the top 3 measurable objectives for this project?
+
+Examples:
+- Process 10,000 transactions/day
+- Reduce customer onboarding time by 50%
+- Support 1M active users
+- Achieve 99.9% uptime SLA
+
+Your objectives:
+1.
+2.
+3.
 ```
 
-**Your answer:**
----
-### Question 1.5: Device & Browser Support
-
-**What devices and browsers must you support?**
-
-A) ⭐ **Modern Browsers Only** (Last 2 versions)
-
-- Chrome, Firefox, Safari, Edge
-- Mobile: iOS Safari 14+, Chrome Android
-- Pros: Use latest web features, smaller bundle size
-- Cons: May exclude <5% of users
-
-B) 🔥 **Broad Compatibility** (Last 3-4 years)
-
-- Include IE11, older Safari versions
-- Requires polyfills and transpilation
-- Pros: Wider audience reach
-- Cons: Larger bundle, limited features
-
-C) **Mobile-First**
-
-- Prioritize iOS Safari and Chrome Android
-- Responsive design for desktop
-- Best for: Consumer apps, e-commerce
-
-D) **Desktop-First**
-
-- Optimize for desktop browsers
-- Mobile as secondary experience
-- Best for: Admin panels, dashboards, B2B tools
-
-**Your answer:**
----
-### Question 1.6: Responsive Strategy
-
-**How will you handle different screen sizes?**
-
-A) ⭐ **Mobile-First Responsive** (Recommended)
+**1.5 System Type (Confirmation + Validation)**
 
-- Design for mobile first, scale up for desktop
-- Breakpoints: 640px (mobile), 768px (tablet), 1024px (desktop)
-- Best for: Most modern apps
+> **📌 Smart Skip**: If 1.1 already identified the domain/industry, this confirms it.
 
-B) **Desktop-First Responsive**
-
-- Design for desktop, scale down for mobile
-- Best for: Complex dashboards with dense data
-
-C) **Adaptive (Multiple Designs)**
+```
+[If DOMAIN was captured in 1.1, show:]
 
-- Separate designs for mobile vs desktop
-- Example: Different layouts/features per breakpoint
-- Best for: Apps with very different mobile/desktop experiences
+✅ Based on your description, this appears to be a: [DOMAIN from 1.1] system
 
-D) **Fixed Width (Desktop Only)**
+Is this correct?
 
-- No mobile optimization
-- Best for: Internal tools, admin panels (desktop-only users)
+A) ✅ Yes, that's correct
+B) 🔄 No, it's actually: [show options below]
 
-**Your answer:**
 ---
-### Question 1.7: Internationalization (i18n)
 
-**Do you need multi-language support?**
+[If DOMAIN was NOT captured in 1.1, OR user selected B above:]
 
-A) ⭐ **Single Language Only**
+What type of system are you building? (This helps suggest common features)
 
-- No i18n needed
-- Fastest development
+A) 🛒 E-commerce/Marketplace
+B) 📱 SaaS/B2B Platform
+C) 📊 CRM/ERP/Business Tool
+D) 🎮 Social/Community Platform
+E) 📋 Content Management
+F) 🏦 FinTech/Payment
+G) 🏥 Healthcare/Booking
+H) 📚 Education/Learning
+I) 🔧 DevTools/API Platform
+J) Other: __
 
-B) **Multi-Language (Static)**
+Your choice: __
+```
 
-- Support 2-5 languages
-- Translations managed in code (JSON files)
-- Example: English, Spanish, French
+**1.6 Core Features**
 
-C) 🌍 **Multi-Language (Dynamic)**
+```
+What are the main functionalities your system needs?
+
+Think about what your users will be able to do with your system. You can list them freely, or select from common features suggested below based on your system type.
+
+🛒 E-commerce common features:
+1) User authentication (register/login)
+2) Product catalog with search/filters
+3) Shopping cart
+4) Checkout and payment processing
+5) Order management
+6) Inventory tracking
+7) Admin dashboard
+📱 SaaS common features:
+1) User authentication with SSO
+2) Multi-tenant organization/workspace management
+3) Role-based access control (RBAC)
+4) Subscription and billing
+5) Dashboard and analytics
+6) API access
+7) Admin panel
+📊 CRM/Business Tool common features:
+1) User/team management
+2) Contact/customer database
+3) Activity tracking and logging
+4) Reporting and analytics
+5) Integrations (email, calendar, etc.)
+6) Search and filters
+7) Export functionality
+🎮 Social/Community common features:
+1) User profiles
+2) Posts/content creation
+3) Feed/timeline
+4) Comments and reactions
+5) Follow/friend system
+6) Notifications
+7) Moderation tools
+⭐ Your specific features (add any custom functionalities):
+-
+-
+-
+
+List all functionalities your system needs (select from above or add your own):
+```
 
-- Support 10+ languages
-- CMS-driven translations or API-based
-- Example: Crowdin, Phrase integration
+**1.7 Scope Definition**
 
-D) **Right-to-Left (RTL) Support**
+```
+Now let's prioritize: What will you build in this first version, and what will you leave for future versions?
 
-- Include Arabic, Hebrew, etc.
-- Requires bidirectional layout support
+This helps us focus the documentation on what you're building now, while noting what comes later.
 
-**Your answer:**
+📋 What will you build in this first version? (Select from the features listed above)
 
-**If multi-language selected, list target languages:**
+[Show features from question 1.6 and allow selection]
 ---
-### Question 1.8: Authentication Requirements
-
-**What authentication method will you use?**
-
-A) ⭐ **Email/Password (Traditional)**
-
-- Users sign up with email and password
-- Requires password reset flow
-- Best for: Most apps
-
-B) 🔥 **Social Login (OAuth)**
-
-- Google, GitHub, Facebook, etc.
-- Faster signup, lower friction
-- Best for: Consumer apps
-
-C) **Magic Link / Passwordless**
-
-- Email-based login link
-- No password management
-- Best for: B2B SaaS, low-security apps
-
-D) **SSO / SAML (Enterprise)**
-
-- Okta, Auth0, Azure AD integration
-- Best for: Enterprise B2B apps
+⏭️ What will you leave for future versions? (What you're NOT building now)
+
+Common things to defer:
+1) Mobile native apps (building web/API first)
+2) Advanced analytics/ML features
+3) Third-party integrations (v2)
+4) White-label/multi-branding
+5) Internationalization (i18n)
+6) Advanced automation/workflows
+7) Video/live streaming features
+⭐ Other features to defer (add your own):
+-
+-
+-
+
+💡 Tip: It's okay to start simple! You can always expand later. This helps us create focused documentation for your current needs.
+```
 
-E) **Multi-Factor Authentication (MFA)**
+**1.8 Constraints**
 
-- SMS, authenticator app, WebAuthn
-- Best for: High-security apps (finance, healthcare)
+```
+What constraints does this project have? Select all that apply:
 
-F) **No Authentication**
+A) ⏰ Time - Must launch by specific date
+B) 💰 Budget - Limited development resources
+C) 📜 Compliance - Regulatory requirements (GDPR, HIPAA, SOC2, etc.)
+D) 🔧 Technology - Must use specific tech stack
+E) 📊 Scale - Must handle specific traffic/data volume
+F) 🔐 Security - High security requirements
+G) ⚡ Performance - Strict latency/throughput requirements
 
-- Public app, no user accounts
-- Best for: Marketing sites, public tools
+For each selected, provide details:
 
-**Your answer:**
----
-### Question 1.9: Data Privacy & Compliance
+Example:
+- Time: Must launch MVP by Q3 2024
+- Compliance: Must be GDPR compliant as we serve EU users
+```
 
-**What data privacy requirements do you have?**
+**1.9 Success Metrics**
 
-A) ⭐ **Standard (No Special Requirements)**
+```
+How will you measure success?
 
-- Basic privacy policy
-- No regulated data
+1. Expected Users:
+   - Initial launch: __ users
+   - Year 1 goal: __ users
 
-B) **GDPR Compliance (EU)**
+2. Performance Targets:
+   - Response time: < __ ms
+   - Uptime: __ %
 
-- Cookie consent banner
-- Right to be forgotten
-- Data export capabilities
+3. Business Goals:
+   - [Goal 1]
+   - [Goal 2]
 
-C) **CCPA Compliance (California)**
+⭐ Standard for MVP:
+- Users: 1,000 initial / 10,000 Year 1
+- Response time: < 500ms (API), < 100ms (DB)
+- Uptime: 99.9% (Standard cloud SLA)
 
-- "Do Not Sell" option
-- Data deletion requests
+🏆 Standard for Production/Scale:
+- Users: 100,000+ active
+- Response time: < 200ms (API), < 50ms (DB)
+- Uptime: 99.99% (High Availability)
+```
 
-D) 🏆 **HIPAA Compliance (Healthcare)**
+**1.10 Main Business Flows**
 
-- Encrypted data transmission
-- Audit logs
-- Strict access controls
+> Note: If you omit any common flow or functionality, the AI will suggest and document typical processes relevant to your system type, based on best practices and common use cases.
 
-E) **SOC 2 / ISO 27001 (Enterprise)**
+`````
+List the main business flows of the system (e.g., sales, inventory update, invoicing, user registration).
 
-- Security audit requirements
-- Detailed logging and monitoring
+For each flow, you can add a brief description (optional).
 
-F) **Multiple Regulations**
+If you wish, you can specify the main steps of any flow (numbered format). If you do not specify them, the AI will deduce typical steps based on the name and description.
 
-- Combine GDPR + CCPA + others
-- Most restrictive controls apply
+Example:
+- Sales: Process of purchasing products by the customer.
+  1. Customer selects products
+  2. Order is created
+  3. Inventory is updated
+  4. Invoice is generated
+- Inventory: Automatic stock update after each sale.
+- Invoicing: Invoice generation after purchase.
 
-**Your answer:**
+The AI will automatically generate flow diagrams (mermaid) for each documented process.
 ---
-### Question 1.10: Offline Support
-
-**Do users need offline access?**
-
-A) ⭐ **Online Only**
-
-- Requires internet connection
-- Simplest implementation
-
-B) **Basic Offline (Read-Only)**
-
-- Cache data for offline viewing
-- No offline editing
-- Example: News apps, documentation
-
-C) 🔥 **Full Offline (Sync)**
-
-- Offline editing with sync when online
-- Requires conflict resolution
-- Example: Note apps, task managers
-- Technologies: Service Workers, IndexedDB
-
-D) **Offline-First**
-
-- Works offline by default
-- Syncs in background
-- Best for: Mobile apps, unreliable networks
+#### 🎨 MERMAID BUSINESS FLOW DIAGRAM FORMAT - CRITICAL
+
+**Use this exact format** for business process flows:
+
+````markdown
+```mermaid
+flowchart TD
+    Start([User Visits Site]) --> Browse[Browse Product Catalog]
+    Browse --> Search{Search or<br/>Browse Categories?}
+
+    Search -->|Use Search| Filter[Apply Search Filters]
+    Search -->|Browse| Category[Select Category]
+
+    Filter --> Results[View Search Results]
+    Category --> Results
+
+    Results --> Select[Select Product]
+    Select --> Details[View Product Details]
+    Details --> Decision{Add to Cart?}
+
+    Decision -->|Yes| AddCart[Add Item to Cart]
+    Decision -->|No| Browse
+
+    AddCart --> MoreShopping{Continue<br/>Shopping?}
+    MoreShopping -->|Yes| Browse
+    MoreShopping -->|No| Cart[View Shopping Cart]
+
+    Cart --> ReviewCart{Cart OK?}
+    ReviewCart -->|Modify| Browse
+    ReviewCart -->|Proceed| Checkout[Start Checkout]
+
+    Checkout --> Address[Enter/Confirm Address]
+    Address --> Payment[Enter Payment Info]
+    Payment --> Review[Review Order]
+    Review --> ProcessPayment[Process Payment]
+
+    ProcessPayment --> PaymentResult{Payment<br/>Success?}
+
+    PaymentResult -->|Success| Confirm[Order Confirmation]
+    PaymentResult -->|Declined| Retry{Retry<br/>Payment?}
+
+    Retry -->|Yes| Payment
+    Retry -->|No| SaveCart[Save Cart for Later]
+    SaveCart --> End1([Exit: Saved])
+
+    Confirm --> Email[Send Confirmation Email]
+    Email --> Inventory[Update Inventory]
+    Inventory --> Invoice[Generate Invoice]
+    Invoice --> End2([Order Complete])
+
+    style Start fill:#e1f5ff
+    style End1 fill:#ffe1e1
+    style End2 fill:#e1ffe1
+    style ProcessPayment fill:#fff4e1
+    style Confirm fill:#d4edda
+`````
+
+````
+
+**Flowchart Syntax:**
+- `flowchart TD` = Top-Down flow (recommended)
+- `flowchart LR` = Left-Right flow
+- `flowchart BT` = Bottom-Top
+- `flowchart RL` = Right-Left
+
+**Node Shapes:**
+- `[Rectangle]` = Process step/action
+- `{Diamond}` = Decision point (Yes/No, multiple options)
+- `([Rounded Rectangle])` = Start/End terminal
+- `[(Cylinder)]` = Database operation
+- `[[Subroutine]]` = Sub-process
+- `[/Parallelogram/]` = Input/Output
+- `((Circle))` = Connection point
+
+**Arrow Types:**
+- `-->` = Solid arrow (standard flow)
+- `-.->` = Dotted arrow (optional/conditional)
+- `==>` = Thick arrow (emphasis)
+- `-->|Label|` = Labeled arrow (decision branch)
+
+**Best Practices for Business Flows:**
+1. **Always start with a terminal**: `([Start])`
+2. **Always end with a terminal**: `([End])`
+3. **Label decision branches**: Use `-->|Yes|` or `-->|No|`
+4. **Use line breaks in labels**: `{Continue<br/>Shopping?}` for readability
+5. **Apply consistent styling**: Same colors for similar node types
+6. **Keep it readable**: Avoid spaghetti flows, group related steps
+7. **Show all paths**: Every decision should have all branches defined
+8. **Include error paths**: Payment failures, validation errors, etc.
+
+**Multiple Flow Example (Advanced):**
+
+```mermaid
+flowchart TD
+    subgraph "Customer Journey"
+        C1[Browse] --> C2[Select]
+        C2 --> C3[Purchase]
+    end
+
+    subgraph "Backend Processing"
+        B1[Validate Order] --> B2[Process Payment]
+        B2 --> B3[Update Inventory]
+        B3 --> B4[Send Notifications]
+    end
+
+    C3 --> B1
+    B4 --> C4[Confirmation]
+```
 
-**Your answer:**
+**Color Coding Guide:**
+- Blue (`#e1f5ff`): Start/Entry points
+- Green (`#e1ffe1`): Success/Completion
+- Red (`#ffe1e1`): Failure/Error states
+- Yellow (`#fff4e1`): Critical operations (Payment, Auth)
+- Purple (`#f0e1ff`): External integrations
+
+**Common Business Flows to Document:**
+- User Registration/Login
+- Purchase/Checkout Process
+- Content Creation/Publishing
+- Approval/Review Workflows
+- Data Import/Export
+- Notification/Alert Flows
+- Customer Support Ticket Lifecycle
+
+**Validation:** Test at https://mermaid.live/ before saving
 ---
-### Question 1.11: Performance Priorities
-
-**What are your performance priorities?** (Select top 3)
-
-A) ⭐ **Fast Initial Load (LCP < 2.5s)**
-
-- Optimize Core Web Vitals
-- Code splitting, lazy loading
-- Best for: SEO, user retention
-
-B) **Smooth Interactions (FID < 100ms)**
-
-- Debounce inputs, optimize re-renders
-- Best for: Interactive apps, dashboards
-
-C) **Visual Stability (CLS < 0.1)**
-
-- Prevent layout shifts
-- Reserve space for dynamic content
-- Best for: Content-heavy sites
-
-D) **Low Bundle Size**
-
-- Minimize JavaScript payload
-- Tree shaking, compression
-- Best for: Mobile users, slow networks
-
-E) **Fast Time to Interactive (TTI)**
-
-- Hydration optimization
-- Critical CSS inlining
-- Best for: SSR apps
-
-F) **Perceived Performance**
-
-- Skeleton screens, optimistic UI
-- Best for: User experience
+```
 
-**Your answer (top 3):**
----
-## 📊 Phase 1 Summary
+### Phase 1 Output
 
-Before proceeding to Phase 2, confirm the following:
+After gathering all information, confirm:
 
 ```
----
-📋 PHASE 1 SUMMARY: DISCOVERY & UX
----
-Project Name: [Answer from 1.1]
-Project Description: [Answer from 1.1]
-Application Type: [Answer from 1.2]
-Target Users: [Answer from 1.3]
-Key User Journeys: [Answer from 1.4]
-Device/Browser Support: [Answer from 1.5]
-Responsive Strategy: [Answer from 1.6]
-Internationalization: [Answer from 1.7]
-Authentication: [Answer from 1.8]
-Data Privacy: [Answer from 1.9]
-Offline Support: [Answer from 1.10]
-Performance Priorities: [Answer from 1.11]
-
-Is this correct? (Y/n)
+📋 PHASE 1 SUMMARY:
+
+Project: [name]
+Description: [1 sentence]
+Users: [list]
+Objectives: [3 objectives]
+System Type: [E-commerce/SaaS/etc.]
+Core Features: [list of main functionalities]
+First Version Features: [what will be built now]
+Future Features: [what will be deferred]
+Constraints: [list with details]
+Success Metrics: [KPIs]
+Business Flows: [list of main flows]
+
+Is this correct? (Yes/No)
+If corrections needed, specify which section.
 ```
-
-If **Yes:** Proceed to Phase 2
-
-If **No:** Allow user to correct specific answers
 ---
-## 📝 Document Generation (Partial)
-
-At the end of Phase 1, generate or update:
-
-### 1. project-brief.md (Partial)
-
-```markdown
-# {{PROJECT_NAME}} - Project Brief
-
-## Overview
-
-{{PROJECT_DESCRIPTION}}
-
-## Application Type
-
-{{APPLICATION_TYPE}}
-
-## Target Users
-
-{{TARGET_USERS}}
-
-## Key User Journeys
-
-1. {{USER_JOURNEY_1}}
-2. {{USER_JOURNEY_2}}
-3. {{USER_JOURNEY_3}}
-4. {{USER_JOURNEY_4}}
-5. {{USER_JOURNEY_5}}
-
-## Technical Requirements
-
-### Browser Support
+### 📄 Generate Phase 1 Documents
 
-{{BROWSER_SUPPORT}}
+**Generate `project-brief.md` automatically:**
 
-### Responsive Strategy
+- Use template: `.ai-flow/templates/project-brief.template.md`
+- Fill with all Phase 1 information
+- Write to project root: `project-brief.md`
 
-{{RESPONSIVE_STRATEGY}}
-
-### Internationalization
-
-{{I18N_SUPPORT}}
-
-### Authentication
-
-{{AUTH_METHOD}}
-
-### Data Privacy
-
-{{DATA_PRIVACY_COMPLIANCE}}
-
-### Offline Support
+```
+✅ Generated: project-brief.md
 
-{{OFFLINE_SUPPORT}}
+The document has been created with all the information from Phase 1.
 
-### Performance Priorities
+📝 Would you like to make any corrections before continuing?
 
-{{PERFORMANCE_PRIORITIES}}
+→ If yes: Edit project-brief.md and type "ready" when done. I'll re-read it.
+→ If no: Type "continue" to proceed to Phase 2.
 ```
 
-### 2. AGENT.md (Partial)
-
-```markdown
-# AGENT.md
+**If user edits the file:**
+Execute `read_file('project-brief.md')` to refresh context before continuing.
+---
 
-## About This Project
+## 📝 Generated Documents
 
-**Project Name:** {{PROJECT_NAME}}
+After Phase 1, generate/update:
+- `project-brief.md` - Core project discovery and requirements
 
-**Type:** {{APPLICATION_TYPE}}
+---
 
-**Target Users:** {{TARGET_USERS}}
+**Next Phase:** Phase 2 - Data Architecture (15-20 min)
 
-## Key Features
+Read: `.ai-flow/prompts/backend/flow-build-phase-2.md`
 
-{{KEY_USER_JOURNEYS}}
+---
 
-## Requirements
+**Last Updated:** 2025-12-20
+**Version:** 2.1.8
 
-- Browser Support: {{BROWSER_SUPPORT}}
-- Responsive: {{RESPONSIVE_STRATEGY}}
-- i18n: {{I18N_SUPPORT}}
-- Authentication: {{AUTH_METHOD}}
-- Compliance: {{DATA_PRIVACY_COMPLIANCE}}
-```
 ---
-## 🚀 Next Steps
 
-```
-✅ Phase 1 Complete!
+## PHASE 2: Data Architecture (15-20 min)
 
-Documents Generated:
-  - project-brief.md (partial)
-  - AGENT.md (partial)
+````
 
-Next: Phase 2 - Components & Framework
 
-Read: .ai-flow/prompts/frontend/flow-build-phase-2-components.md
-```
----
-**Last Updated:** 2025-12-XX
 
-**Version:** 1.3.0