ai-flow-dev 2.1.7 → 2.1.8

package/README.md

@@ -10,7 +10,8 @@ AI Flow is an interactive CLI that creates comprehensive professional documentat
 
 **Key Features:**
 
-- 🚀 Complete professional documentation (Backend: 17 docs, Frontend: 15 docs, Mobile: 13 docs, Fullstack: 4 docs)
+- 🚀 Complete professional documentation (Backend: 15 docs, Frontend: 16 docs, Mobile: 14 docs, Fullstack: 4 docs)
+- 🧠 **Smart Description Refinement:** Detects ambiguity and iteratively guides you to a professional project definition.
 - ⚡ **Two modes:** Interactive (90-120 min, full control) or Smart Auto-Suggest (15-25 min, 6 questions)
 - 🌍 Universal support - 12 languages, 60+ frameworks, 35+ ORMs (98% coverage)
 - 🤖 Multi-AI support with slash commands
@@ -37,7 +38,8 @@ Transforma tu idea en un proyecto listo para producción y documentado para IA e
 
 **Características:**
 
-- 🚀 Documentación profesional completa (Backend: 17 docs, Frontend: 15 docs, Mobile: 13 docs, Fullstack: 4 docs)
+- 🚀 Documentación profesional completa (Backend: 15 docs, Frontend: 16 docs, Mobile: 14 docs, Fullstack: 4 docs)
+- 🧠 **Refinamiento Inteligente:** Detecta ambigüedad y te guía iterativamente hacia una descripción profesional.
 - ⚡ **Dos modos:** Interactivo (90-120 min, control total) o Auto-Sugerido (15-25 min, 6 preguntas)
 - 🌍 Soporte universal - 12 lenguajes, 60+ frameworks, 35+ ORMs
 - 🤖 Compatible with Claude, Copilot, Cursor, Gemini, Antigravity
@@ -63,7 +65,8 @@ ai-flow init .
 Transforme sua ideia em um projeto pronto para produção e documentado para IA em minutos.
 **Características:**
 
-- 🚀 Documentação profissional completa (Backend: 17, Frontend: 15, Mobile: 13, Fullstack: 4 docs)
+- 🚀 Documentação profissional completa (Backend: 15, Frontend: 16, Mobile: 14, Fullstack: 4 docs)
+- 🧠 **Refinamento Inteligente:** Detecta ambiguidade e guia você para uma descrição profissional.
 - ⚡ **Dois modos:** Interactivo (90-120 min, controle total) ou Auto-Sugestão (15-25 min, 6 perguntas)
 - 🌍 Suporte universal - 12 linguagens, 60+ frameworks, 35+ ORMs
 - 🤖 Compatível com Claude, Copilot, Cursor, Gemini, Antigravity
@@ -102,9 +105,10 @@ The result is interconnected documentation that guides AI assistants and human d
 
 - 🌍 **Universal Support** - 12 languages, 60+ frameworks, 35+ ORMs (98% coverage)
 - 🤖 **AI-Agnostic** - Claude, Copilot, Cursor, Gemini, Antigravity, any AI tool
-- 📚 **Professional Documentation** - Backend: 17, Frontend: 15, Mobile: 13, Fullstack: 4 docs
+- 📚 **Professional Documentation** - Backend: 15, Frontend: 16, Mobile: 14, Fullstack: 4 docs
+- 🧠 **Smart Description Refinement** - AI detects vague inputs and helps you rich the context (WHO, WHAT, WHY).
 - ⚡ **Two Questionnaire Modes:**
-  - **Interactive Mode:** Full control, 71 questions (90-120 min)
+  - **Interactive Mode:** Full control, all phases (90-120 min)
   - **Smart Auto-Suggest:** Only 6 critical questions, AI suggests best practices (15-25 min)
 - 🔍 **Smart 3-Layer Detection** - Analyzes existing projects in 15s-5min
 - 💾 **Intelligent Caching** - 0 seconds on re-runs with no changes
@@ -258,9 +262,9 @@ After initialization, use these slash commands in your AI tool:
 
 > **Note:** Command prefix may vary by AI tool. Examples use `/flow-` (GitHub Copilot), but Claude may use `/` alone, Cursor may use `@`, etc. Check your tool's documentation.
 
-**Backend Projects:** 8 commands  
-**Frontend Projects:** 2 commands  
-**Mobile Projects:** 2 commands  
+**Backend Projects:** 19 commands  
+**Frontend Projects:** 11 commands  
+**Mobile Projects:** 11 commands  
 **Fullstack Projects:** Combined backend + frontend commands
 
 **Documentation & Build:**
@@ -334,11 +338,11 @@ After initialization, use these slash commands in your AI tool:
 
 ## 🎯 Generated Documentation
 
-**Backend** (17 docs): AGENT.md, ai-instructions.md, copilot-instructions.md, project-brief.md, README.md, plus 8 technical docs and 2 specs
+**Backend** (15 docs): AGENT.md, ai-instructions.md, project-brief.md, plus 12 technical docs/specs.
 
-**Frontend** (15 docs): AGENT.md, ai-instructions.md, project-brief.md, plus 9 technical docs and 3 specs
+**Frontend** (16 docs): AGENT.md, ai-instructions.md, project-brief.md, plus 13 technical docs/specs.
 
-**Mobile** (13 docs): AGENT.md, ai-instructions.md, project-brief.md, plus 8 technical docs and 2 specs
+**Mobile** (14 docs): AGENT.md, ai-instructions.md, project-brief.md, plus 11 technical docs/specs.
 
 **Fullstack** (4 docs): AGENT.md, ai-instructions.md, project-brief.md, plus 1 spec
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-flow-dev",
-  "version": "2.1.7",
+  "version": "2.1.8",
   "description": "AI-powered development workflow from idea to production. Generate specs, plan features, and build with AI assistance throughout your project lifecycle.",
   "type": "module",
   "main": "dist/cli.js",

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

@@ -4,7 +4,9 @@
 
 > **📌 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**
+**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:]
@@ -17,26 +19,178 @@ If no, please provide correct values.
 [If NOT detected, ask:]
 What is the project name?
 
-Provide a short description (1 sentence) for README and package.json
+Provide an initial description of your project.
+(Don't worry about perfection - we'll refine it together if needed!)
+
+Example: "A backend for managing gym memberships"
+```
+
+**🔍 AI Internal: Ambiguity Analysis**
+
+After receiving the description, silently analyze for these criteria:
+
+| Criterion | Check For | Score +1 if present |
+|-----------|-----------|---------------------|
+| **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:**
+- Score 4-5: ✅ Accept immediately → Proceed to 1.2
+- Score 0-3: ⚠️ Enter refinement loop → Ask ONLY missing criteria
+
+---
+
+**🔄 Conditional Refinement Loop (only if score < 4)**
+
+> **CRITICAL**: Only ask about criteria that are MISSING. Do NOT repeat questions already answered. Respond in the SAME LANGUAGE the developer used.
+
+```
+[LANGUAGE: Match the developer's language]
+
+🔍 I'd like to understand your project better.
+
+Your description: "[original description]"
+
+[ONLY show questions for MISSING criteria:]
+
+[If WHO is missing:]
+1️⃣ WHO will use this system?
+   A) End consumers (B2C)
+   B) Business users (B2B)
+   C) Internal team
+   D) Other systems (APIs)
+   E) Other: __
+
+[If WHAT is missing:]
+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) Replace manual/legacy process
+   B) Launch new product/business
+   C) Improve existing system
+   D) Enable new capability
+   E) Other: __
+
+[If DOMAIN is missing:]
+4️⃣ What INDUSTRY/DOMAIN is this for?
+   A) E-commerce/Retail
+   B) Fitness/Health
+   C) Finance/Payments
+   D) Education
+   E) Social/Community
+   F) Business tools (CRM, ERP)
+   G) Other: __
+
+Your answers: __ (e.g., "A, B, A, E" or describe freely)
+```
+
+---
+
+**✨ Generate Professional Description Options**
+
+After gathering missing info, generate 3 polished versions:
+
 ```
+[LANGUAGE: Match the developer's language]
+
+✨ Based on your input, here are 3 professional descriptions:
+
+A) Concise (for package.json):
+   "[Generated 1-line description with WHO + WHAT]"
 
-**1.2 Project Overview**
+B) Descriptive (for README.md):
+   "[Generated 2-3 line description with WHO + WHAT + WHY]"
 
+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)
 ```
-What problem does this backend system solve?
 
-Describe in 2-3 sentences:
-- Who are the users?
-- What is the core value proposition?
-- What makes this project necessary?
+---
+
+**✅ Final Confirmation**
+
+```
+✅ Your final project description:
+
+📋 Name: [project name]
+📝 Description: "[final polished description]"
+
+Proceed to next question? (Y to continue)
+```
+
+---
+
+**1.2 Project Overview (Confirmation + Expansion)**
+
+> **📌 Smart Skip**: If 1.1 already captured WHO/WHAT/WHY completely, this becomes a quick confirmation.
+
+```
+[If 1.1 refinement was complete (score >= 4), show:]
+
+✅ Based on your description, I understand:
+   • Users: [WHO from 1.1]
+   • Core Action: [WHAT from 1.1]
+   • Purpose: [WHY from 1.1]
+
+Is this complete? (Y) Or would you like to add more context? (N)
+
+[If user says Y → Skip to 1.3]
+[If user says N → Ask:]
+What additional context would you like to add?
+
+---
+
+[If 1.1 was NOT refined OR any WHO/WHAT/WHY still missing, ask:]
+
+[ONLY ask for MISSING elements - check what was NOT captured in 1.1:]
+
+[If WHO still unclear:]
+Who are the primary users of this system?
+
+[If WHAT still unclear:]
+What is the core value proposition?
+
+[If WHY still unclear:]
+What makes this project necessary?
 
 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."
 ```
 
-**1.3 Target Users**
+**1.3 Target Users (Confirmation + Additional Types)**
+
+> **📌 Smart Skip**: If 1.1 already identified user types, this confirms and expands.
 
 ```
+[If WHO was captured in 1.1, show:]
+
+✅ Based on your description, your target users are: [WHO from 1.1]
+
+Would you like to add any additional user types? Select any that apply:
+
+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
+
+---
+
+[If WHO was NOT captured in 1.1, ask normally:]
+
 Who will use this system? Select all that apply:
 
 A) 🌐 External end-users (B2C) - Public-facing application
@@ -65,9 +219,24 @@ Your objectives:
 3.
 ```
 
-**1.5 System Type**
+**1.5 System Type (Confirmation + Validation)**
+
+> **📌 Smart Skip**: If 1.1 already identified the domain/industry, this confirms it.
 
 ```
+[If DOMAIN was captured in 1.1, show:]
+
+✅ Based on your description, this appears to be a: [DOMAIN from 1.1] system
+
+Is this correct?
+
+A) ✅ Yes, that's correct
+B) 🔄 No, it's actually: [show options below]
+
+---
+
+[If DOMAIN was NOT captured in 1.1, OR user selected B above:]
+
 What type of system are you building? (This helps suggest common features)
 
 A) 🛒 E-commerce/Marketplace
@@ -141,7 +310,7 @@ This helps us focus the documentation on what you're building now, while noting
 📋 What will you build in this first version? (Select from the features listed above)
 
 [Show features from question 1.6 and allow selection]
----
+---
 ⏭️ What will you leave for future versions? (What you're NOT building now)
 
 Common things to defer:
@@ -229,7 +398,7 @@ Example:
 - Invoicing: Invoice generation after purchase.
 
 The AI will automatically generate flow diagrams (mermaid) for each documented process.
----
+---
 #### 🎨 MERMAID BUSINESS FLOW DIAGRAM FORMAT - CRITICAL
 
 **Use this exact format** for business process flows:
@@ -356,7 +525,7 @@ flowchart TD
 - Customer Support Ticket Lifecycle
 
 **Validation:** Test at https://mermaid.live/ before saving
----
+---
 ```
 
 ### Phase 1 Output
@@ -381,7 +550,7 @@ Business Flows: [list of main flows]
 Is this correct? (Yes/No)
 If corrections needed, specify which section.
 ```
----
+---
 ### 📄 Generate Phase 1 Documents
 
 **Generate `project-brief.md` automatically:**
@@ -403,11 +572,11 @@ The document has been created with all the information from Phase 1.
 
 **If user edits the file:**
 Execute `read_file('project-brief.md')` to refresh context before continuing.
----
+---
 **Proceed to Phase 2 after document is generated and optionally reviewed.**
 
 > ⚠️ **CRITICAL:** DO NOT generate README.md in Phase 1. README.md is ONLY generated in Phase 8 (step 8.5) after framework initialization.
----
+---
 ## PHASE 2: Data Architecture (15-20 min)
 
 ````

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

@@ -1,22 +1,131 @@
 # Phase 1: Discovery & UX Requirements
 
 **Duration:** 15-20 minutes
-**Questions:** ~10 questions
+**Questions:** ~11 questions
 **Output:** project-brief.md, parts of AGENT.md
----
+---
 ## 🎯 Objective
 
-Understand the **user-facing aspects** of the application:
+Understand the **user-facing aspects** and core goal of the application:
 
-1. What type of application is being built?
-2. Who are the target users?
-3. What are the key user journeys?
-4. What devices and browsers must be supported?
-5. What are the UX priorities?
----
+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: Application Type
+### Question 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.
+
+```
+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"
+```
+
+**🔍 AI Internal: Ambiguity Analysis**
+
+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" |
+| **DETAIL** | Description has 10+ meaningful words | Not counting articles |
+
+**Scoring Rules:**
+- Score 4-5: ✅ Accept immediately → Proceed to 1.2
+- Score 0-3: ⚠️ Enter refinement loop → Ask ONLY missing criteria
+
+---
+
+**🔄 Conditional Refinement Loop (only if score < 4)**
+
+> **CRITICAL**: Only ask about criteria that are MISSING. Do NOT repeat questions already answered. Respond in the SAME LANGUAGE the developer used.
+
+```
+[LANGUAGE: Match the developer's language]
+
+🔍 I'd like to understand your project better.
+
+Your description: "[original description]"
+
+[ONLY show questions for MISSING criteria:]
+
+[If WHO is missing:]
+1️⃣ WHO will use this application?
+   A) End consumers (B2C)
+   B) Business users (B2B)
+   C) Internal team / Admin
+   D) 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
+   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
+   E) Other: __
+
+[If DOMAIN is missing:]
+4️⃣ What INDUSTRY/DOMAIN is this for?
+   A) E-commerce/Retail
+   B) Fitness/Health
+   C) Finance/Payments
+   D) Education
+   E) Social/Community
+   F) Business tools (CRM, ERP)
+   G) Other: __
+
+Your answers: __
+```
+
+---
+
+**✨ Generate Professional Description Options**
+
+After gathering missing info, generate 3 polished versions:
+
+```
+[LANGUAGE: Match the developer's language]
+
+✨ Based on your input, here are 3 professional descriptions:
+
+A) Concise (for package.json):
+   "[Generated 1-line description]"
+
+B) Descriptive (for README.md):
+   "[Generated 2-3 line description with UX focus]"
+
+C) Creative (for Marketing/Landing):
+   "[Generated catchy description]"
+
+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?**
 
@@ -51,10 +160,26 @@ E) **Static Site (SSG)**
 - Best for: Blogs, documentation, landing pages
 
 **Your answer:**
----
-### Question 1.2: Target Users
+---
+### Question 1.3: Target Users (Confirmation + Expansion)
+
+```
+[If WHO was captured in 1.1, show:]
+
+✅ Based on your description, your target users are: [WHO from 1.1]
+
+Describe your user personas more deeply (3-5 bullet points):
+
+- Demographics (age, tech-savviness, etc.)
+- Use cases / goals
+- Device preferences
+- Accessibility needs
 
-**Who are your primary target users?**
+---
+
+[If WHO was NOT captured in 1.1, ask normally:]
+
+Who are your primary target users?
 
 Describe your user personas (3-5 bullet points):
 
@@ -62,6 +187,7 @@ Describe your user personas (3-5 bullet points):
 - Use cases / goals
 - Device preferences
 - Accessibility needs
+```
 
 **Example:**
 
@@ -73,12 +199,22 @@ Describe your user personas (3-5 bullet points):
 ```
 
 **Your answer:**
----
-### Question 1.3: Key User Journeys
+---
+### Question 1.4: Key User Journeys (Confirmation + Expansion)
+
+```
+[If WHAT was captured in 1.1, show:]
+
+✅ Based on your description, a core journey is: [WHAT from 1.1]
+
+What are the 3-5 most critical user flows?
 
-**What are the 3-5 most critical user flows?**
+---
 
-List the core journeys users will take through your app.
+[If WHAT was NOT captured in 1.1, ask normally:]
+
+What are the 3-5 most critical user flows?
+```
 
 **Example:**
 
@@ -90,8 +226,8 @@ List the core journeys users will take through your app.
 ```
 
 **Your answer:**
----
-### Question 1.4: Device & Browser Support
+---
+### Question 1.5: Device & Browser Support
 
 **What devices and browsers must you support?**
 
@@ -122,8 +258,8 @@ D) **Desktop-First**
 - Best for: Admin panels, dashboards, B2B tools
 
 **Your answer:**
----
-### Question 1.5: Responsive Strategy
+---
+### Question 1.6: Responsive Strategy
 
 **How will you handle different screen sizes?**
 
@@ -150,8 +286,8 @@ D) **Fixed Width (Desktop Only)**
 - Best for: Internal tools, admin panels (desktop-only users)
 
 **Your answer:**
----
-### Question 1.6: Internationalization (i18n)
+---
+### Question 1.7: Internationalization (i18n)
 
 **Do you need multi-language support?**
 
@@ -180,8 +316,8 @@ D) **Right-to-Left (RTL) Support**
 **Your answer:**
 
 **If multi-language selected, list target languages:**
----
-### Question 1.7: Authentication Requirements
+---
+### Question 1.8: Authentication Requirements
 
 **What authentication method will you use?**
 
@@ -219,8 +355,8 @@ F) **No Authentication**
 - Best for: Marketing sites, public tools
 
 **Your answer:**
----
-### Question 1.8: Data Privacy & Compliance
+---
+### Question 1.9: Data Privacy & Compliance
 
 **What data privacy requirements do you have?**
 
@@ -257,8 +393,8 @@ F) **Multiple Regulations**
 - Most restrictive controls apply
 
 **Your answer:**
----
-### Question 1.9: Offline Support
+---
+### Question 1.10: Offline Support
 
 **Do users need offline access?**
 
@@ -287,8 +423,8 @@ D) **Offline-First**
 - Best for: Mobile apps, unreliable networks
 
 **Your answer:**
----
-### Question 1.10: Performance Priorities
+---
+### Question 1.11: Performance Priorities
 
 **What are your performance priorities?** (Select top 3)
 
@@ -327,25 +463,27 @@ F) **Perceived Performance**
 - Best for: User experience
 
 **Your answer (top 3):**
----
+---
 ## 📊 Phase 1 Summary
 
 Before proceeding to Phase 2, confirm the following:
 
 ```
----
+---
 📋 PHASE 1 SUMMARY: DISCOVERY & UX
----
-Application Type: [Answer from 1.1]
-Target Users: [Answer from 1.2]
-Key User Journeys: [Answer from 1.3]
-Device/Browser Support: [Answer from 1.4]
-Responsive Strategy: [Answer from 1.5]
-Internationalization: [Answer from 1.6]
-Authentication: [Answer from 1.7]
-Data Privacy: [Answer from 1.8]
-Offline Support: [Answer from 1.9]
-Performance Priorities: [Answer from 1.10]
+---
+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)
 ```
@@ -353,7 +491,7 @@ Is this correct? (Y/n)
 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:
@@ -439,7 +577,7 @@ At the end of Phase 1, generate or update:
 - Authentication: {{AUTH_METHOD}}
 - Compliance: {{DATA_PRIVACY_COMPLIANCE}}
 ```
----
+---
 ## 🚀 Next Steps
 
 ```
@@ -453,11 +591,7 @@ Next: Phase 2 - Components & Framework
 
 Read: .ai-flow/prompts/frontend/flow-build-phase-2-components.md
 ```
----
-**Last Updated:** 2025-01-XX
-
-**Version:** 1.2.0
-
-
-
+---
+**Last Updated:** 2025-12-XX
 
+**Version:** 1.3.0

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

@@ -1,21 +1,157 @@
 # Phase 1: Platform & Framework Selection
 
 **Duration:** 20-25 minutes
-**Questions:** ~15 questions
+**Questions:** ~17 questions
 **Output:** project-brief.md, parts of AGENT.md, parts of ai-instructions.md
----
+---
 ## 🎯 Objective
 
-Determine the **technical foundation** for your mobile application:
+Determine the **business goal and technical foundation** for your mobile application:
 
-1. What platforms will you target?
-2. What framework will you use?
-3. What minimum OS versions will you support?
-4. What development tools and languages?
----
+1. What is the core goal and purpose of the project?
+2. What platforms will you target?
+3. What framework will you use?
+4. What minimum OS versions will you support?
+5. What development tools and languages?
+---
 ## 📋 Questions
 
-### Question 1.1: Target Platforms
+### Question 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.
+
+```
+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 native iOS app for tracking wildlife sightings in the Amazon"
+```
+
+**🔍 AI Internal: Ambiguity Analysis**
+
+After receiving the description, silently analyze for these criteria:
+
+| Criterion | Check For | Score +1 if present |
+|-----------|-----------|---------------------|
+| **WHO** | Specific user type mentioned (not just "users") | "tourists", "researchers", "drivers" |
+| **WHAT** | Specific action/function (not just "app", "system") | "scan barcodes", "record audio", "track GPS" |
+| **WHY** | Purpose or value mentioned | "to protect species", "to optimize routes" |
+| **DOMAIN** | Industry/vertical indicated | "environmental", "logistics", "social" |
+| **DETAIL** | Description has 10+ meaningful words | Not counting articles |
+
+**Scoring Rules:**
+- Score 4-5: ✅ Accept immediately → Proceed to 1.2
+- Score 0-3: ⚠️ Enter refinement loop → Ask ONLY missing criteria
+
+---
+
+**🔄 Conditional Refinement Loop (only if score < 4)**
+
+> **CRITICAL**: Only ask about criteria that are MISSING. Do NOT repeat questions already answered. Respond in the SAME LANGUAGE the developer used.
+
+```
+[LANGUAGE: Match the developer's language]
+
+🔍 I'd like to understand your project better.
+
+Your description: "[original description]"
+
+[ONLY show questions for MISSING criteria:]
+
+[If WHO is missing:]
+1️⃣ WHO will use this mobile app?
+   A) End consumers (App Store/Play Store)
+   B) Internal employees (Enterprise)
+   C) Partners/Contractors
+   D) Other: __
+
+[If WHAT is missing:]
+2️⃣ WHAT is the core mobile action users will perform?
+   A) Transactional (Buy/Sell)
+   B) Utility (Tools/Monitoring)
+   C) Social (Chat/Share)
+   D) Media (Photo/Video)
+   E) Informational (News/Content)
+   F) Other: __
+
+[If WHY is missing:]
+3️⃣ WHY is this mobile project needed?
+   A) New product launch
+   B) Companion to web app
+   C) Offline-first requirement
+   D) Better mobile performance
+   E) Other: __
+
+[If DOMAIN is missing:]
+4️⃣ What INDUSTRY/DOMAIN is this for?
+   A) E-commerce/Retail
+   B) Fitness/Health
+   C) Finance/Payments
+   D) Education/Learning
+   E) Social/Community
+   F) Business tools (CRM, ERP)
+   G) Other: __
+
+Your answers: __
+```
+
+---
+
+**✨ Generate Professional Description Options**
+
+After gathering missing info, generate 3 polished versions:
+
+```
+[LANGUAGE: Match the developer's language]
+
+✨ Based on your input, here are 3 professional descriptions:
+
+A) Concise (for App Store subtitle):
+   "[Generated 1-line description]"
+
+B) Descriptive (for README.md):
+   "[Generated 2-3 line description with Mobile focus]"
+
+C) User-centric (for Marketing):
+   "[Generated benefit-driven description]"
+
+Which do you prefer? (1-3, or 4 to edit, 5 to start over)
+```
+
+**Your choice:**
+
+---
+
+### Question 1.2: Project Overview (Confirmation + Expansion)
+
+> **📌 Smart Skip**: If 1.1 already captured WHO/WHAT/WHY completely, this becomes a quick confirmation.
+
+```
+[If 1.1 refinement was complete (score >= 4), show:]
+
+✅ Based on your description, I understand:
+   • Users: [WHO from 1.1]
+   • Goal: [WHAT from 1.1]
+   • Need: [WHY from 1.1]
+
+Is this correct? (Y) Or would you like to add more context? (N)
+
+---
+
+[If 1.1 was NOT refined OR missing elements, ask:]
+
+Briefly describe the core problem this app solves:
+- Who are the primary users?
+- What is the main benefit?
+- Why build a mobile app instead of a web app?
+```
+
+**Your answer:**
+
+---
+### Question 1.3: Target Platforms
 
 **What platforms will your app support?**
 
@@ -44,8 +180,8 @@ D) **iOS + Android + Web (Universal)**
 - Best for: Multi-platform presence
 
 **Your answer:**
----
-### Question 1.2: Mobile Framework
+---
+### Question 1.4: Mobile Framework
 
 **What framework will you use to build your mobile app?**
 
@@ -100,8 +236,8 @@ D) **iOS + Android + Web (Universal)**
 
 - What Flutter version? (Latest stable recommended)
 - Will you use Flutter for Web/Desktop too? (Y/n)
----
-### Question 1.3: Minimum OS Versions
+---
+### Question 1.5: Minimum OS Versions
 
 **What minimum OS versions will you support?**
 
@@ -150,8 +286,8 @@ D) **iOS + Android + Web (Universal)**
   - Best for: Premium apps, latest tech
 
 **Your answer:**
----
-### Question 1.4: Programming Language
+---
+### Question 1.6: Programming Language
 
 **What programming language will you use?**
 
@@ -192,8 +328,8 @@ D) **iOS + Android + Web (Universal)**
   - Best for: Maintaining existing apps
 
 **Your answer:**
----
-### Question 1.5: Development Environment
+---
+### Question 1.7: Development Environment
 
 **What development tools will you use?**
 
@@ -222,8 +358,8 @@ D) **iOS + Android + Web (Universal)**
 - **Dart DevTools** - Debugging (Flutter)
 
 **Your answer:**
----
-### Question 1.6: Package Manager
+---
+### Question 1.8: Package Manager
 
 **What package manager will you use?**
 
@@ -246,8 +382,8 @@ D) **iOS + Android + Web (Universal)**
 - **Gradle** (built-in)
 
 **Your answer:**
----
-### Question 1.7: Build Tools & CI/CD
+---
+### Question 1.9: Build Tools & CI/CD
 
 **What build and deployment tools will you use?**
 
@@ -278,8 +414,8 @@ E) **Manual Builds**
 - Best for: Learning, small projects
 
 **Your answer:**
----
-### Question 1.8: Code Signing Strategy
+---
+### Question 1.10: Code Signing Strategy
 
 **How will you handle code signing?**
 
@@ -304,8 +440,8 @@ E) **Manual Builds**
   - Required for some enterprise scenarios
 
 **Your answer:**
----
-### Question 1.9: App Store Accounts
+---
+### Question 1.11: App Store Accounts
 
 **Do you have App Store accounts set up?**
 
@@ -321,8 +457,8 @@ E) **Manual Builds**
 - B) ❌ **No, will set up later**
 
 **Your answer:**
----
-### Question 1.10: Beta Testing Strategy
+---
+### Question 1.12: Beta Testing Strategy
 
 **How will you handle beta testing?**
 
@@ -347,8 +483,8 @@ D) **No Beta Testing**
 - Best for: MVPs, internal apps
 
 **Your answer:**
----
-### Question 1.11: Analytics & Crash Reporting
+---
+### Question 1.13: Analytics & Crash Reporting
 
 **What analytics and crash reporting will you use?**
 
@@ -374,8 +510,8 @@ D) **No Analytics**
 - Best for: Privacy-critical apps
 
 **Your answer:**
----
-### Question 1.12: UI/UX Framework
+---
+### Question 1.14: UI/UX Framework
 
 **What UI/UX framework or design system will you use?**
 
@@ -422,8 +558,8 @@ D) **No Analytics**
 
 - Will you use platform-specific UI? (iOS uses Cupertino, Android uses Material)
 - Or unified design across platforms?
----
-### Question 1.13: Theme & Dark Mode
+---
+### Question 1.15: Theme & Dark Mode
 
 **Will your app support dark mode?**
 
@@ -443,8 +579,8 @@ C) **No Dark Mode**
 - Best for: Simple apps
 
 **Your answer:**
----
-### Question 1.14: Internationalization (i18n)
+---
+### Question 1.16: Internationalization (i18n)
 
 **Will your app support multiple languages?**
 
@@ -471,8 +607,8 @@ C) **No Internationalization**
   - React Native: react-i18next, react-native-localize
   - Flutter: intl, easy_localization
   - Native: NSLocalizedString (iOS), Resources (Android)
----
-### Question 1.15: Image & Asset Management
+---
+### Question 1.17: Image & Asset Management
 
 **How will you handle images and assets?**
 
@@ -500,48 +636,46 @@ C) **All Remote Images**
   - React Native: react-native-fast-image, react-native-image-caching
   - Flutter: cached_network_image
   - Native: SDWebImage (iOS), Glide (Android)
----
+---
 ## ✅ Phase 1 Completion
 
 After answering all questions, summarize:
 
 ```
----
+---
 ✅ Phase 1 Complete: Platform & Framework Selection
----
+---
+Project Name: [Answer from 1.1]
+Project Description: [Answer from 1.1]
 Selected Stack:
-- Platforms: iOS + Android
-- Framework: React Native 0.72.0
-- Language: TypeScript
-- Minimum iOS: 15.0+
-- Minimum Android: API 26 (Android 8.0)+
-- Package Manager: npm
-- Build Tools: Fastlane
-- Analytics: Firebase Analytics + Crashlytics
-- UI Framework: React Native Paper
-- Dark Mode: System Theme
-- Internationalization: Multiple Languages (react-i18next)
-- Image Management: Local Assets + Remote Images
+- Platforms: [Answer from 1.3]
+- Framework: [Answer from 1.4]
+- Language: [Answer from 1.6]
+- Minimum iOS: [Answer from 1.5]
+- Minimum Android: [Answer from 1.5]
+- Package Manager: [Answer from 1.8]
+- Build Tools: [Answer from 1.9]
+- Analytics: [Answer from 1.13]
+- UI Framework: [Answer from 1.14]
+- Dark Mode: [Answer from 1.15]
+- Internationalization: [Answer from 1.16]
+- Image Management: [Answer from 1.17]
 
 Proceed to Phase 2 (Navigation & Architecture)? (Y/n)
 ```
----
+---
 ## 📝 Generated Documents
 
 After Phase 1, generate/update:
 
-- `project-brief.md` - Add platform and framework information
+- `project-brief.md` - Add project goal, platforms, and framework information
 - `AGENT.md` - Update technical context section
 - `ai-instructions.md` - Add framework-specific rules and setup
----
+---
 **Next Phase:** Phase 2 - Navigation & Architecture
 
 Read: `.ai-flow/prompts/mobile/flow-build-phase-2-navigation.md`
----
-**Last Updated:** 2025-01-XX
-
-**Version:** 1.4.0
-
-
-
+---
+**Last Updated:** 2025-12-XX
 
+**Version:** 1.5.0

package/templates/AGENT.template.md

@@ -412,4 +412,4 @@ See `README.md` for installation and setup instructions.
 
 **Last Updated:** {{GENERATION_DATE}}
 
-**Generated by:** AI Flow v2.1.6
+**Generated by:** AI Flow v2.1.8