ai-flow-dev 2.2.4 → 2.4.0

package/README.md

@@ -140,7 +140,7 @@ Or using uv (Python tool manager):
 uv tool install ai-flow-dev
 ```
 
-## **Current version:** 2.2.4
+## **Current version:** 2.4.0
 
 ## 🚀 Quick Start
 
@@ -310,13 +310,45 @@ After initialization, use these slash commands in your AI tool:
 
 **Workflows (All project types):**
 
-- `/flow-work` - **Unified orchestrator** for Features/Refactors/Fixes with smart detection
+- `/flow-work` - **Unified orchestrator** for Features/Refactors/Fixes with smart detection, automatic completion tracking, and consolidated planning
 - `/flow-check` - **Combined validation**: Tests + Code Review in one command
 - `/flow-commit` - Automate commits with Conventional Commits (3-5 min)
 - `/flow-docs-sync` - **Sync documentation** when code changes occur
 
+> **Note:** `/flow-work` automatically marks tasks as complete in `planning/roadmap.md` and user story DoD checklists when implementation finishes. It generates a consolidated `work.md` file for efficient planning and context management.
+
 ## **📚 See [GETTING-STARTED.md](GETTING-STARTED.md) for complete command reference**
 
+---
+
+## 📁 Project Structure
+
+AI Flow organizes your project with clear separation of concerns:
+
+### Documentation & Specifications
+
+- **`docs/`** - Descriptive documentation (WHAT the project IS)
+  - `architecture.md` - System architecture and design patterns
+  - `data-model.md` - Entities, relationships, database schema
+  - `api.md` - Available endpoints and contracts
+  - `testing.md` - Testing strategy and guidelines
+
+- **`specs/`** - Technical specifications (HOW to IMPLEMENT)
+  - `security.md` - Security rules and constraints (MUST/NEVER)
+  - `configuration.md` - Environment variables and settings
+
+### Planning & Requirements
+
+- **`planning/`** - Requirements and roadmap (WHAT to DO)
+  - `roadmap.md` - Technical implementation roadmap with Story Points
+  - `user-stories/` - Agile user stories with acceptance criteria
+
+### Development State
+
+- **`.ai-flow/`** - AI workflow state (temporary, can be gitignored)
+  - `work/` - Active development tasks
+  - `archive/` - Completed tasks (organized by month)
+
 ## 💡 How It Works
 
 1. **Smart Detection** - Analyzes existing projects in 3 layers (15s to 5min)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-flow-dev",
-  "version": "2.2.4",
+  "version": "2.4.0",
   "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-0.md

@@ -322,7 +322,7 @@ C) Cancel /flow-build (fix manually first)
       "reason": "Final documentation complete and up-to-date"
     },
     "phase9": {
-      "file": "docs/roadmap.md",
+      "file": "planning/roadmap.md",
       "exists": false,
       "consistencyScore": 0,
       "recommendation": "SKIP",
@@ -330,7 +330,7 @@ C) Cancel /flow-build (fix manually first)
       "reason": "Project already implemented - roadmap not needed for existing code"
     },
     "phase10": {
-      "file": "docs/user-stories/",
+      "file": "planning/user-stories/",
       "exists": false,
       "consistencyScore": 0,
       "recommendation": "SKIP",

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

@@ -29,7 +29,7 @@ Break down technical roadmap tasks into user-centric Agile requirements (User St
 // turbo
 ### Step 10.1: Load Context from Roadmap
 
-**Extract from `docs/roadmap.md`:**
+**Extract from `planning/roadmap.md`:**
 
 ```
 CONTEXT LOADED
@@ -66,7 +66,7 @@ SCOPE SELECTION
 
 ### Step 10.3: Generate User Story Documents
 
-**For each Feature in roadmap, create `docs/user-stories/EP-XXX/HU-XXX-YYY.md`:**
+**For each Feature in roadmap, create `planning/user-stories/EP-XXX/HU-XXX-YYY.md`:**
 
 ```markdown
 # User Story: HU-{{EPIC}}-{{FEATURE}}
@@ -123,7 +123,7 @@ SCOPE SELECTION
 
 ## Tasks
 
-> Inherited from docs/roadmap.md Feature {{FEATURE_NUMBER}}
+> Inherited from planning/roadmap.md Feature {{FEATURE_NUMBER}}
 
 {{TASKS_FROM_ROADMAP}}
 
@@ -169,7 +169,7 @@ SCOPE SELECTION
 
 ### Step 10.4: Generate Test Cases (Separate Files)
 
-**For each User Story, create `docs/user-stories/EP-XXX/tests/TC-XXX-YYY.md`:**
+**For each User Story, create `planning/user-stories/EP-XXX/tests/TC-XXX-YYY.md`:**
 
 ```markdown
 # Test Cases: HU-{{EPIC}}-{{FEATURE}}
@@ -235,12 +235,12 @@ SCOPE SELECTION
 
 ### Step 10.5: Update Roadmap with Links
 
-**After generating, update `docs/roadmap.md`:**
+**After generating, update `planning/roadmap.md`:**
 
 ```markdown
 ### Feature 1.1: {{FEATURE_NAME}} • {{SP}} SP
 
-**User Story:** [HU-001-001](docs/user-stories/EP-001/HU-001-001.md)
+**User Story:** [HU-001-001](planning/user-stories/EP-001/HU-001-001.md)
 **Status:** Not Started
 
 **Tasks:**
@@ -311,11 +311,11 @@ PHASE 10 COMPLETE
 ├── Generated: X User Stories
 ├── Total SP: X SP
 ├── Test Cases: X
-├── Files: docs/user-stories/EP-XXX/
-└── Updated: docs/roadmap.md (added links)
+├── Files: planning/user-stories/EP-XXX/
+└── Updated: planning/roadmap.md (added links)
 
 Next steps:
-1. Review User Stories in docs/user-stories/
+1. Review User Stories in planning/user-stories/
 2. Start implementing: /flow-dev-feature HU-001-001
 3. Generate more: /flow-build fase 10 EP-XXX
 ```
@@ -326,8 +326,8 @@ Next steps:
 
 After Phase 10, generate/update:
 
-- `docs/user-stories/*.md` - Detailed Agile requirements
-- `docs/roadmap.md` - (updated with story links)
+- `planning/user-stories/*.md` - Detailed Agile requirements
+- `planning/roadmap.md` - (updated with story links)
 
 ---
 

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

@@ -312,7 +312,7 @@ COVERAGE VALIDATION
 
 ---
 
-**Write `docs/roadmap.md` with this structure:**
+**Write `planning/roadmap.md` with this structure:**
 
 ```markdown
 # Implementation Roadmap: {{PROJECT_NAME}}
@@ -419,7 +419,7 @@ PHASE 9 COMPLETE
 ├── Coverage: 100% (all components have [E][R][S][C][T][D])
 └── Ready for: /flow-dev-feature
 
-Next: Open docs/roadmap.md and start with EP-000, or continue to Phase 10 for detailed User Stories.
+Next: Open planning/roadmap.md and start with EP-000, or continue to Phase 10 for detailed User Stories.
 
 **OFFER PHASE 10:**
 
@@ -427,7 +427,7 @@ Next: Open docs/roadmap.md and start with EP-000, or continue to Phase 10 for de
 ---
 ✅ PHASE 9 COMPLETE: IMPLEMENTATION ROADMAP GENERATED
 ---
-🎯 Roadmap created in docs/roadmap.md
+🎯 Roadmap created in planning/roadmap.md
 📊 Total Story Points: {{SP}}
 🏗️ Epics defined: {{EPICS_COUNT}}
 ---
@@ -462,7 +462,7 @@ Your choice (A/B): __
 
 After Phase 9, generate/update:
 
-- `docs/roadmap.md` - Technical implementation plan
+- `planning/roadmap.md` - Technical implementation plan
 
 ---
 

package/prompts/backend/flow-work-feature.md

@@ -9,33 +9,39 @@ This file contains the detailed execution logic for implementing new features, i
 ---
 ## 🚀 Feature Implementation Flow
 
-### 1. Specification (auto-skip if User Story)
-- Extract requirements from User Story or Roadmap.
-- If interactive, ask clarification questions (Multiple Choice).
-- Save to `specs/ai-flow/work/[feature]/spec.md`.
+### 1. Context Analysis (auto-skip if User Story with detailed tasks)
+- Extract requirements from User Story or Roadmap
+- If User Story has detailed tasks: Skip to work.md generation
+- If Roadmap or Manual: Analyze and refine
+- Read relevant documentation (ai-instructions.md, architecture.md, etc.)
 
-### 2. Technical Planning
-- Analyze codebase for patterns.
-- Generate `plan.md` with Fibonacci estimation.
-- Organize tasks into layers (Data, Logic, API, Test, Docs).
-- **User Confirmation Required.**
+### 2. work.md Generation
+- Generate consolidated work.md (see Phase 2 in flow-work.md)
+- Include: Context, Objective, Constraints, Approach, Tasks, Validation
+- **User Confirmation Required**
 
 ### 3. Progressive Implementation
 Choose mode:
-- **Auto**: Complete all tasks without pausing.
-- **Phase-by-phase**: Pause and validate after each phase.
-- **Task-by-task**: Pause after each task.
+- **Auto**: Complete all tasks without pausing
+- **Phase-by-phase**: Pause and validate after each phase
+- **Task-by-task**: Pause after each task
+
+Follow tasks in `work.md`:
+- Update checkboxes as completed
+- Update `status.json` progress
+- Follow patterns and constraints specified
 
 ### 4. Definition of Done (DoD)
-- If HU mode: Validate against Gherkin scenarios.
-- Run tests and linting.
-- Perform security check.
+- If HU mode: Validate against Gherkin scenarios
+- Run tests and linting
+- Perform security check
+- **Update completion status** in source documents (see Phase 4 Step 1 in flow-work.md)
 
 ---
 ## 🌿 Git Branching Strategy
-- Generate slug from name.
-- Execute `git checkout -b feature/[slug]`.
-- Maintain `status.json` with commit history.
+- Generate slug from name
+- Execute `git checkout -b feature/[slug]`
+- Maintain `status.json` with commit history
 
 ---
 ## 📦 status.json Persistence

package/prompts/backend/flow-work-fix.md

@@ -10,23 +10,26 @@ This file contains the detailed execution logic for bug fixes, imported by `@flo
 ## 🔧 Bug Fix Workflow
 
 ### 1. Classification
-- **QUICK**: 1 file, obvious cause (typo, null check).
-- **COMPLEX**: Multiple files, investigation needed.
+- **QUICK**: 1 file, obvious cause (typo, null check)
+- **COMPLEX**: Multiple files, investigation needed
 
-### 2. Deep Analysis (Complex Fix)
-- Create work directory.
-- Document root cause in `analysis.md`.
-- Map side effects.
+### 2. Analysis & work.md Generation
+- **QUICK**: Minimal work.md (objective + 1-2 tasks)
+- **COMPLEX**: Full work.md with root cause analysis
+  - Document root cause in Objective section
+  - Map side effects in Approach section
+  - Generate detailed tasks
 
 ### 3. Implementation
-- **Test-First Approach**: Add a failing test case that reproduces the bug before fixing it.
-- Apply the fix.
-- Verify tests pass.
+- **Test-First Approach**: Add failing test that reproduces bug
+- Apply the fix following work.md tasks
+- Verify tests pass
+- **Update completion status** if fix was tracked in roadmap/user stories (see Phase 4 Step 1 in flow-work.md)
 
 ---
 ## 🌿 Git Branching Strategy
-- **QUICK**: Usually work on current branch.
-- **COMPLEX**: Execute `git checkout -b fix/[slug]`.
+- **QUICK**: Usually work on current branch
+- **COMPLEX**: Execute `git checkout -b fix/[slug]`
 
 ---
 ## 📦 status.json Persistence

package/prompts/backend/flow-work-refactor.md

@@ -9,23 +9,29 @@ This file contains the detailed execution logic for code refactoring, imported b
 ---
 ## 🔄 Refactoring Workflow
 
-### 1. Scope Identification
-- Map affected files and dependencies.
-- Confirm no behavior change is expected.
-- Validate against architecture patterns.
-
-### 2. Implementation Strategy
-- Use `plan.md` to map extraction/renaming/moving steps.
-- Set "No behavior change" as the primary constraint.
-
-### 3. Execution & Safety
-- Update imports and references across the codebase.
-- **Critical**: Existing tests must pass without modification (unless test itself is refactored).
-- Run `/flow-check` to verify no regressions.
+### 1. Scope Identification & work.md Generation
+- Map affected files and dependencies
+- Confirm no behavior change expected
+- Validate against architecture patterns
+- Generate work.md with:
+  - Clear scope (what to extract/move/rename)
+  - Affected files list
+  - Step-by-step tasks
+  - "No behavior change" constraint
+
+### 2. Implementation
+- Follow work.md tasks sequentially
+- Update imports and references across codebase
+- **Critical**: Existing tests must pass without modification (unless test itself is refactored)
+
+### 3. Validation
+- Run `/flow-check` to verify no regressions
+- Confirm all tests pass
+- **Update completion status** if refactor was tracked in roadmap/user stories (see Phase 4 Step 1 in flow-work.md)
 
 ---
 ## 🌿 Git Branching Strategy
-- Execute `git checkout -b refactor/[slug]`.
+- Execute `git checkout -b refactor/[slug]`
 
 ---
 ## 📦 status.json Persistence

package/prompts/backend/flow-work-resume.md

@@ -10,22 +10,24 @@ This file contains the logic for detecting and resuming paused work items, impor
 ## ⏸️ Resume Workflow
 
 ### 1. Work Detection
-- Scan `specs/ai-flow/work/` for any directories.
-- Group by type and last updated timestamp.
+- Scan `.ai-flow/work/` for any directories
+- Group by type and last updated timestamp
 
 ### 2. Selection Menu
-- Show active tasks with percentage and current branch.
-- Identify current Git branch and match with work items (⭐⭐ marker).
+- Show active tasks with percentage and current branch
+- Identify current Git branch and match with work items (⭐⭐ marker)
 
 ### 3. Context Restoration
-- Load `spec.md`, `plan.md`, `task.md`, and `status.json`.
+- Load `work.md` and `status.json`
 - Verify Git branch:
-  - If mismatch: Prompt to switch to `git.branchName`.
-- Identify the first incomplete task in `task.md`.
+  - If mismatch: Prompt to switch to `git.branchName`
+- Identify the first incomplete task in `work.md`
+- Read Documentation Constraints section to refresh context
 
 ### 4. Implementation Continuation
-- Resume with the previously saved `implementationMode`.
-- Continue execution from where it was paused.
+- Resume with the previously saved `implementationMode`
+- Continue execution from where it was paused
+- Follow remaining tasks in `work.md`
 
 ---
 ## 📦 status.json Persistence