ai-flow-dev 1.0.3 → 1.1.2

package/prompts/frontend/flow-bootstrap-phase-8.md

@@ -0,0 +1,670 @@
+# 🏆 Phase 8: Project Setup & Final Documentation
+
+**Context:** Phases 1-7 have collected all project information. Now we'll initialize the framework (if needed) and generate all final documentation.
+
+**Duration:** 10-15 minutes
+
+**Goal:** Set up the project structure and create comprehensive documentation that consolidates all information from previous phases.
+
+---
+
+## 📋 Phase 8 Overview
+
+This final phase will:
+
+1. **Detect project state** (new vs existing project)
+2. **Initialize framework** (optional, for new projects)
+3. **Generate final documentation** (components, performance, operations)
+4. **Generate master index** (AGENT.md)
+5. **Generate README.md** (with intelligent merge if needed)
+6. **Create tool-specific configs** (based on AI tool selection)
+
+---
+
+## 8.1: Project State Detection
+
+```
+🔍 Detecting current project state...
+```
+
+**Auto-detect:**
+
+- [ ] Check for existing source code (`src/`, `app/`, `components/`, `pages/`, etc.)
+- [ ] Check for framework files (`package.json`, `angular.json`, `vite.config.ts`, `next.config.js`, etc.)
+- [ ] Check for package managers (`package.json`, `yarn.lock`, `pnpm-lock.yaml`)
+- [ ] Check for existing README.md (framework-generated or custom)
+
+**Classification:**
+
+- **New Project**: No source code, no framework files
+- **Initialized Framework**: Has framework files, has source code
+- **Existing Project**: Has source code but AI Flow docs were just created
+
+**Present Detection Results:**
+
+```
+📊 Project State Detection:
+
+Type: [New Project | Initialized Framework | Existing Project]
+
+Found:
+- Source directories: [list or none]
+- Framework files: [list or none]
+- Package manager: [npm/yarn/pnpm or none]
+- README.md: [exists: yes/no]
+
+Recommendation: [Next action based on state]
+```
+
+---
+
+## 8.2: Framework Initialization (Optional)
+
+**Only if:** Project state = "New Project"
+
+### 8.2.1: Ask User Preference
+
+```
+🎯 Your project appears to be new.
+
+Would you like me to initialize the [FRAMEWORK_NAME] project structure now?
+
+Options:
+A) ✅ Yes, initialize [FRAMEWORK_NAME] (recommended)
+B) ⏭️  Skip for now (manual setup later)
+
+→ Your choice:
+```
+
+**If user chooses A (initialize):**
+
+### 8.2.2: Pre-initialization Backup
+
+```
+📦 Preparing for framework initialization...
+
+Creating backup of AI Flow documentation:
+→ Moving .ai-flow/ docs to .ai-flow/temp-backup/
+
+Files to backup:
+✅ project-brief.md
+✅ docs/ui-structure.md
+✅ docs/architecture.md
+✅ ai-instructions.md
+✅ docs/code-standards.md
+✅ docs/testing.md
+✅ docs/performance.md
+✅ docs/operations.md
+✅ specs/configuration.md
+✅ .env.example
+
+Backup complete! Safe to initialize framework.
+```
+
+### 8.2.3: Execute Framework CLI
+
+**Based on framework detected in Phase 3:**
+
+**React:**
+
+```bash
+# Create React App (traditional)
+npx create-react-app . --template typescript
+
+# Vite + React (recommended)
+npm create vite@latest . -- --template react-ts
+
+# Next.js (full-stack)
+npx create-next-app@latest . --typescript --eslint --tailwind --app --src-dir --import-alias "@/*"
+```
+
+**Vue:**
+
+```bash
+# Vue CLI
+vue create .
+
+# Vite + Vue (recommended)
+npm create vite@latest . -- --template vue-ts
+
+# Nuxt.js (full-stack)
+npx nuxi@latest init .
+```
+
+**Angular:**
+
+```bash
+# Angular CLI
+ng new . --routing --style=scss --skip-git
+
+# Angular with standalone components
+ng new . --standalone --routing --style=scss --skip-git
+```
+
+**Svelte:**
+
+```bash
+# SvelteKit
+npm create svelte@latest .
+
+# Vite + Svelte
+npm create vite@latest . -- --template svelte-ts
+```
+
+**Other frameworks:**
+
+```bash
+# Solid.js
+npx degit solidjs/templates/ts .
+
+# Preact
+npx preact-cli create default .
+
+# Remix
+npx create-remix@latest .
+
+# Astro
+npm create astro@latest .
+```
+
+**Show progress:**
+
+```
+🚀 Initializing [FRAMEWORK_NAME]...
+
+[Framework CLI output]
+
+✅ Framework initialized successfully!
+```
+
+### 8.2.4: Restore AI Flow Documentation
+
+```
+📥 Restoring AI Flow documentation...
+
+Moving files from .ai-flow/temp-backup/ back to .ai-flow/
+
+✅ All AI Flow docs restored!
+```
+
+### 8.2.5: Handle README.md Conflict
+
+**If framework created README.md:**
+
+```
+⚠️  Framework generated its own README.md
+
+I'll merge it with AI Flow's comprehensive README:
+
+Strategy:
+1. Keep framework's quick start section (if valuable)
+2. Replace with AI Flow's comprehensive content
+3. Preserve any framework-specific setup instructions
+
+Merging...
+```
+
+**Merge Logic:**
+
+- Extract framework's "Getting Started" or "Installation" section
+- Use AI Flow's README template as base
+- Insert framework's quick start in appropriate section
+- Ensure no duplication
+- Keep AI Flow's structure (overview, features, tech stack, etc.)
+
+**If user chooses B (skip):**
+
+```
+⏭️  Skipping framework initialization.
+
+You can initialize manually later with:
+[Show appropriate CLI command]
+
+Proceeding to documentation generation...
+```
+
+---
+
+## 8.3: Generate Final Documentation
+
+```
+📖 Re-reading all generated documents to ensure accuracy...
+
+✅ Re-reading project-brief.md
+✅ Re-reading docs/ui-structure.md
+✅ Re-reading docs/architecture.md
+✅ Re-reading ai-instructions.md
+✅ Re-reading docs/code-standards.md
+✅ Re-reading docs/testing.md
+✅ Re-reading docs/performance.md
+✅ Re-reading docs/operations.md
+✅ Re-reading specs/configuration.md
+✅ Re-reading .env.example
+
+✅ Context fully loaded and updated!
+
+🎉 Now generating final 4 documents:
+
+1. docs/components-guide.md - Component architecture and patterns
+2. docs/state-management.md - State management strategy
+3. docs/contributing.md - Contribution guidelines
+4. AGENT.md - Universal AI configuration (master index)
+5. README.md - Project overview (consolidates all phases)
+
+Generating...
+```
+
+### 8.3.1: Generate docs/components-guide.md
+
+- **Template:** `.ai-flow/templates/docs/components-guide.template.md`
+- **Content from:** Phase 2 (UI structure) + Phase 5 (code standards)
+- **Requirements:**
+  - List component hierarchy from Phase 2
+  - Document component patterns (container/presentational, atomic design, etc.)
+  - Include props conventions
+  - Add styling approach
+  - Link to component library (if using one)
+
+### 8.3.2: Generate docs/state-management.md
+
+- **Template:** `.ai-flow/templates/docs/state-management.template.md`
+- **Content from:** Phase 3 (state management strategy)
+- **Requirements:**
+  - Document chosen state solution (Redux, Zustand, Context, etc.)
+  - Define state structure
+  - Include action/reducer patterns
+  - Document async state handling
+  - Add caching strategy
+
+### 8.3.3: Generate docs/contributing.md
+
+- **Template:** `.ai-flow/templates/docs/contributing.template.md`
+- **Content from:** Phase 5 (code standards) + Phase 7 (operations)
+- **Requirements:**
+  - Git workflow from Phase 5
+  - Commit message format
+  - Code review process
+  - Setup instructions from Phase 7
+  - Testing requirements from Phase 6
+
+---
+
+## 8.4: Generate AGENT.md (Master Index)
+
+- **Template:** `.ai-flow/templates/AGENT.template.md`
+- **Content from:** ALL phases (this is the aggregator)
+- **Requirements:**
+  - **CRITICAL:** Re-read ALL previously generated documents before filling
+  - List all documents with descriptions
+  - Provide quick reference to tech stack
+  - Include critical architecture rules
+  - Link to all specs and docs
+  - Summarize key decisions from each phase
+  - Include common commands
+
+**Structure:**
+
+```markdown
+# 🤖 AGENT.md - Universal AI Assistant Configuration
+
+## 📚 Documentation Index
+
+### Core Documents
+
+1. **project-brief.md** - [1-sentence description]
+2. **ai-instructions.md** - [1-sentence description]
+
+### Documentation
+
+3. **docs/ui-structure.md** - [1-sentence description]
+4. **docs/architecture.md** - [1-sentence description]
+5. **docs/components-guide.md** - [1-sentence description]
+6. **docs/state-management.md** - [1-sentence description]
+7. **docs/code-standards.md** - [1-sentence description]
+8. **docs/testing.md** - [1-sentence description]
+9. **docs/performance.md** - [1-sentence description]
+10. **docs/operations.md** - [1-sentence description]
+11. **docs/contributing.md** - [1-sentence description]
+
+### Specifications
+
+12. **specs/configuration.md** - [1-sentence description]
+13. **.env.example** - Environment variables template
+14. **README.md** - Project overview and setup
+
+## 🎯 Quick Reference
+
+### Tech Stack
+
+[List from Phase 3]
+
+### Critical Rules
+
+[Key rules from code-standards.md and ai-instructions.md]
+
+### Common Commands
+
+[From operations.md and contributing.md]
+```
+
+---
+
+## 8.5: Generate README.md (Intelligent Merge)
+
+- **Template:** `.ai-flow/templates/README.template.md`
+- **Content from:** ALL phases (most comprehensive document)
+- **Requirements:**
+  - **CRITICAL:** Re-read ALL documents before generating
+  - Include project overview from Phase 1
+  - List features from Phase 1
+  - Show tech stack from Phase 3
+  - Include quick start from Phase 7
+  - Link to all documentation
+  - Include deployment info from Phase 7
+
+**Merge Strategy (if framework README exists):**
+
+1. **Read framework's README.md** (if exists from step 8.2)
+2. **Extract valuable sections:**
+   - Installation commands specific to framework
+   - Framework-specific setup instructions
+   - Dev server commands
+3. **Use AI Flow template as base structure:**
+   - Project name and description (from Phase 1)
+   - Features (from Phase 1)
+   - Tech stack (from Phase 3)
+   - Architecture overview (link to docs/architecture.md)
+   - Getting started (merge with framework's instructions)
+   - Testing (link to docs/testing.md)
+   - Deployment (from Phase 7)
+   - Contributing (link to docs/contributing.md)
+4. **Insert framework-specific content** in "Getting Started" section
+5. **Ensure no duplication**
+6. **Validate all links** work correctly
+
+---
+
+## 8.6: Create Tool-Specific Configs
+
+**Based on AI tool selection from Phase 3:**
+
+### If Claude selected:
+
+**Create `.clauderules`:**
+
+```markdown
+# Claude AI Configuration
+
+This project uses AI Flow documentation structure.
+
+## Primary Reference
+
+Read `.ai-flow/AGENT.md` first for complete documentation index.
+
+## Key Documents
+
+- Project overview: `.ai-flow/project-brief.md`
+- AI instructions: `.ai-flow/ai-instructions.md`
+- Architecture: `.ai-flow/docs/architecture.md`
+- UI Structure: `.ai-flow/docs/ui-structure.md`
+- Components: `.ai-flow/docs/components-guide.md`
+- State: `.ai-flow/docs/state-management.md`
+- Code standards: `.ai-flow/docs/code-standards.md`
+
+## Working Instructions
+
+When writing code:
+
+1. Follow patterns in `.ai-flow/docs/code-standards.md`
+2. Reference component structure in `.ai-flow/docs/ui-structure.md`
+3. Follow state management patterns from `.ai-flow/docs/state-management.md`
+4. Write tests per `.ai-flow/docs/testing.md`
+
+## Critical Rules
+
+[Extract top 5-10 rules from ai-instructions.md]
+```
+
+### If Cursor selected:
+
+**Create `.cursorrules`:**
+
+```markdown
+# Cursor AI Configuration
+
+Project uses AI Flow documentation in `.ai-flow/` directory.
+
+## Documentation Index
+
+See `.ai-flow/AGENT.md` for complete document list.
+
+## Quick Reference
+
+- Tech Stack: [from Phase 3]
+- Architecture: `.ai-flow/docs/architecture.md`
+- Components: `.ai-flow/docs/components-guide.md`
+- Code Standards: `.ai-flow/docs/code-standards.md`
+
+## Code Generation Rules
+
+[Extract key rules from ai-instructions.md]
+```
+
+### If GitHub Copilot selected:
+
+**Create `.github/copilot-instructions.md`:**
+
+```markdown
+# GitHub Copilot Instructions
+
+## Project Context
+
+[Project description from Phase 1]
+
+## Documentation Structure
+
+This project uses AI Flow. All documentation is in `.ai-flow/` directory.
+
+Master index: `.ai-flow/AGENT.md`
+
+## Key References
+
+- Architecture: `.ai-flow/docs/architecture.md`
+- UI Structure: `.ai-flow/docs/ui-structure.md`
+- Components: `.ai-flow/docs/components-guide.md`
+- State: `.ai-flow/docs/state-management.md`
+- Code Standards: `.ai-flow/docs/code-standards.md`
+- Testing: `.ai-flow/docs/testing.md`
+
+## Code Generation Guidelines
+
+[Extract guidelines from ai-instructions.md and code-standards.md]
+
+## Tech Stack
+
+[From Phase 3]
+```
+
+---
+
+## 8.7: Final Validation & Success Message
+
+```
+🔍 Validating all generated files...
+
+✅ Checking for placeholder text...
+✅ Validating file references...
+✅ Ensuring all links work...
+✅ Verifying template completeness...
+
+All validations passed!
+```
+
+**Show complete summary:**
+
+```
+🎉 AI Flow Complete!
+
+Generated 14 documents successfully:
+
+Phase 1:
+✅ project-brief.md
+
+Phase 2:
+✅ docs/ui-structure.md
+
+Phase 3:
+✅ docs/architecture.md
+✅ ai-instructions.md
+
+Phase 5:
+✅ docs/code-standards.md
+
+Phase 6:
+✅ docs/testing.md
+
+Phase 7:
+✅ docs/performance.md
+✅ docs/operations.md
+✅ specs/configuration.md
+✅ .env.example
+
+Phase 8:
+✅ docs/components-guide.md
+✅ docs/state-management.md
+✅ docs/contributing.md
+✅ README.md
+✅ AGENT.md
+
+[If framework initialized:]
+✅ [FRAMEWORK_NAME] project initialized
+
+[If README merged:]
+✅ README.md merged with framework's setup instructions
+
+Tool-specific configs:
+✅ [List generated configs]
+
+---
+
+📁 Project Structure:
+
+your-project/
+├── .ai-flow/                    # AI Flow documentation
+│   ├── AGENT.md                 ⭐ Start here!
+│   ├── project-brief.md
+│   ├── ai-instructions.md
+│   ├── docs/
+│   │   ├── ui-structure.md
+│   │   ├── architecture.md
+│   │   ├── components-guide.md
+│   │   ├── state-management.md
+│   │   ├── code-standards.md
+│   │   ├── testing.md
+│   │   ├── performance.md
+│   │   ├── operations.md
+│   │   └── contributing.md
+│   ├── specs/
+│   │   └── configuration.md
+│   └── templates/               # Original templates
+├── [framework files]            # If initialized
+├── README.md
+├── .env.example
+└── [tool configs]               # .clauderules, .cursorrules, etc.
+
+---
+
+Next steps:
+
+1. ⭐ **Read `.ai-flow/AGENT.md`** - Master index of all documentation
+2. 📖 **Review generated documents** - Customize as needed
+3. 🔧 **Set up environment** - Copy `.env.example` to `.env` and configure
+[If NOT initialized:]
+4. 🚀 **Initialize framework** - Run: `[show command from Phase 3]`
+[If initialized:]
+4. 🚀 **Install dependencies** - Run: `npm install` / `yarn install`
+5. 💾 **Initialize git** (if not done) - `git init && git add . && git commit -m "Initial commit with AI Flow docs"`
+6. 🧪 **Start developing!** - Your AI assistant now has complete project context
+
+---
+
+💡 **Remember:**
+- Documents are **living artifacts** - update them as project evolves
+- All AI assistants will reference these docs for future work
+- AGENT.md is the **single source of truth** for AI context
+
+🤖 **AI Assistant Usage:**
+Your AI assistant (Claude, Cursor, Copilot) will now:
+- ✅ Understand complete project context
+- ✅ Follow your architecture patterns
+- ✅ Generate code matching your standards
+- ✅ Reference your component structure
+- ✅ Apply your state management patterns
+- ✅ Write tests per your guidelines
+
+Happy building! 🎉
+```
+
+---
+
+## EXECUTION CHECKLIST FOR AI ASSISTANT
+
+When executing Phase 8:
+
+**8.1 Project State Detection:**
+
+- [ ] Scan for source directories (src/, app/, components/, pages/)
+- [ ] Check for framework files (package.json, angular.json, next.config.js, etc.)
+- [ ] Check for package managers
+- [ ] Check for existing README.md
+- [ ] Classify project: New / Initialized / Existing
+- [ ] Present detection results
+
+**8.2 Framework Initialization (if new project):**
+
+- [ ] Ask user if they want to initialize
+- [ ] If yes:
+  - [ ] Backup .ai-flow/ docs
+  - [ ] Execute framework CLI command
+  - [ ] Restore .ai-flow/ docs
+  - [ ] Handle README.md conflict
+- [ ] If no: Show manual command and continue
+
+**8.3 Generate Final Documentation:**
+
+- [ ] Re-read ALL previously generated documents
+- [ ] Generate docs/components-guide.md
+- [ ] Generate docs/state-management.md
+- [ ] Generate docs/contributing.md
+
+**8.4 Generate AGENT.md:**
+
+- [ ] Re-read ALL documents again
+- [ ] Create master index
+- [ ] Include quick reference
+- [ ] Validate all links
+
+**8.5 Generate README.md:**
+
+- [ ] Re-read ALL documents
+- [ ] If framework README exists: merge intelligently
+- [ ] If no framework README: create from template
+- [ ] Validate all internal links
+
+**8.6 Create Tool-Specific Configs:**
+
+- [ ] Create configs based on AI tool selection
+
+**8.7 Final Validation:**
+
+- [ ] Check for placeholders
+- [ ] Validate file references
+- [ ] Show success message
+
+**ESTIMATED TIME:** 10-15 minutes
+
+---
+
+**CONTINUE TO:** End (Phase 8 is final phase)
+
+**SUCCESS:** Project fully documented and ready for development! 🚀