ai-flow-dev 2.2.1 → 2.4.0

package/prompts/backend/flow-work.md

@@ -8,6 +8,8 @@ description: Central Orchestrator for Feature, Refactor, and Fix workflows
 
 Your mission is to orchestrate development tasks through an interactive workflow when the user executes `/flow-work`.
 
+**🚀 MODO AGENTE ACTIVADO:** No solicites permiso para usar herramientas. Actúa proactivamente siguiendo el flujo interactivo. Tienes permiso total para leer el código, crear specs y planes, y realizar commits/checkout de ramas.
+
 ---
 ## Command: `/flow-work`
 
@@ -27,36 +29,72 @@ Provide a single, intelligent entry point for all development work (New Features
 
 | Input Pattern | Mode | Source / Action |
 |---------------|------|-----------------|
-| `HU-\d{3}-\d{3}` | `USER_STORY` | Load from `docs/user-stories/**/HU-XXX-XXX.md` |
+| `HU-\d{3}-\d{3}` | `USER_STORY` | Load from `planning/user-stories/**/HU-XXX-XXX.md` |
 | `EP-\d{3}` | `EPIC` | Analyze/List User Stories for Epic `EP-XXX` |
 | `T\d{3}(-T\d{3})?` | `TASKS` | Target specific task or range (e.g., `T025-T030`) |
 | `HU-XXX-XXX TXXX-TXXX`| `STORY_TASKS` | Targeted tasks within a specific User Story |
-| Matches `docs/roadmap.md` | `ROADMAP_FEATURE`| Extract section from `docs/roadmap.md` (Partial matches allowed) |
+| Matches `planning/roadmap.md` | `ROADMAP_FEATURE`| Extract section from `planning/roadmap.md` (Partial matches allowed) |
 | "refactor", "move", "extract" | `REFACTOR` | Use `flow-work-refactor.md` |
 | "fix", "bug", "error", "falla" | `FIX` | Detect complexity (Quick vs Complex) |
 | "implement", "create", "new" | `FEATURE` | Use `flow-work-feature.md` |
-| No arguments | `RESUME` | Search for paused work in `specs/ai-flow/work/` |
+| No arguments | `RESUME` | Search for paused work in `.ai-flow/work/` |
 
 **2. Detection Logic Details:**
-- **USER_STORY / EPIC**: Load metadata from `docs/user-stories/` or `docs/roadmap.md`.
-- **ROADMAP_FEATURE**: Fuzzy search in `docs/roadmap.md` for titles like "User Management" or "Feature 2.2".
+- **USER_STORY / EPIC**: Load metadata from `planning/user-stories/` or `planning/roadmap.md`.
+- **ROADMAP_FEATURE**: Fuzzy search in `planning/roadmap.md` for titles like "User Management" or "Feature 2.2".
 - **TASK RANGES**: If `T025-T030` is provided, find the parent Story or Feature in current context or roadmap.
 - **SIMPLE FIX**: Affects 1 file, obvious cause, <10 lines fix. → Use `flow-work-fix.md` (Quick).
 - **COMPLEX FIX**: Multi-file, architectural, performance/security. → Use `flow-work-fix.md` (Deep).
 
 ---
-## Phase 1: Interactive Analysis
+## Phase 1: Analysis & Refinement
 
 **1. Context Loading (Multi-Source):**
+
 **CRITICAL**: Regardless of whether a `USER_STORY` ID or a `ROADMAP_FEATURE` name is provided, you MUST attempt to load context from **BOTH** sources:
-- **`docs/roadmap.md`**: To understand high-level scope, epic relationships, and technical dependencies.
-- **`docs/user-stories/**/HU-XXX-XXX.md`**: To get granular details (Acceptance Criteria, Gherkin Scenarios, QA cases).
+- **`planning/roadmap.md`**: To understand high-level scope, epic relationships, and technical dependencies.
+- **`planning/user-stories/**/HU-XXX-XXX.md`**: To get granular details (Acceptance Criteria, Gherkin Scenarios, QA cases).
+
+**2. Detail Level Detection (if Manual input):**
+
+IF input is manual description (not HU/Roadmap):
+
+```python
+detail_level = analyze_description(input)
+
+# Criteria for HIGH detail (Feature):
+# - Mentions technology/method (JWT, OAuth, bcrypt, etc.)
+# - Describes flow (registration, login, CRUD, etc.)
+# - Includes technical constraints (hashing, tokens, validation, etc.)
+
+# Criteria for HIGH detail (Refactor):
+# - Describes what to extract/move
+# - Mentions destination (file/class)
+# - References pattern to follow
+
+# Criteria for HIGH detail (Fix):
+# - Describes symptom (error 500, crash, null pointer, etc.)
+# - Mentions probable cause
+# - Suggests fix approach
+```
 
-**2. Interactive Questions:**
-- IF both sources provide 100% clarity: Skip questions.
-- IF there is missing info or ambiguity: Ask 3-5 key questions with **Multiple Choice Options** and **Defaults (marked with ⭐)**.
+**3. Interactive Refinement (Conditional):**
 
-**Example Interaction:**
+**IF detail_level == "HIGH":**
+- Skip refinement questions
+- Proceed directly to Phase 2 (Planning)
+- Show: "✅ Sufficient detail detected. Proceeding with planning..."
+
+**IF detail_level == "MEDIUM":**
+- Ask 1-2 targeted questions (only missing items)
+- Use Multiple Choice with defaults (⭐)
+
+**IF detail_level == "LOW":**
+- Full refinement flow (3-5 questions)
+- Use Multiple Choice with defaults (⭐)
+- Focus on: approach, scope, constraints, priorities
+
+**Example Interaction (LOW detail):**
 > 📝 I need to clarify some details for this feature:
 > 1. What authentication provider should we use? [default: A]
 >    A) JWT (Local) ⭐
@@ -66,19 +104,235 @@ Provide a single, intelligent entry point for all development work (New Features
 > 2. Should we implement audit logs for this? [default: B]
 >    A) Yes
 >    B) No ⭐
+>
+> Your answers (or Enter for defaults): _
+
+**4. Refined Objective Generation (if Manual):**
+
+After refinement, generate clear objective statement:
+```
+✅ Refined Objective:
+
+[Clear 1-2 paragraph description of WHAT will be implemented]
+
+**Scope**:
+- [List in-scope items]
+
+**Out of Scope**:
+- [List out-of-scope items]
+
+Is this correct? (Yes/Edit/Cancel): _
+```
+
+**5. Documentation Compliance Check:**
+
+Read relevant documentation:
+- `ai-instructions.md` (NEVER/ALWAYS rules)
+- `docs/architecture.md` (patterns, structure)
+- `docs/code-standards.md` (naming, quality)
+- IF auth/security: `specs/security.md`
+- IF database: `docs/data-model.md`
+- IF API: `docs/api.md`
+
+Compare refined objective against documentation:
+
+**IF deviation detected:**
+```
+🚨 POTENTIAL DEVIATION
+
+From [document]:
+❌ NEVER: [rule being violated]
+✅ ALWAYS: [rule being ignored]
+
+Your request: [conflicting part]
+
+Options:
+A) Modify request to align with documentation
+B) Proceed with deviation (requires justification)
+C) Cancel
+
+Your choice: _
+```
+
+**IF user chooses B (Override):**
+```
+⚠️ OVERRIDE CONFIRMATION
+
+You are implementing something that deviates from:
+- [list violated documents/rules]
+
+Type "I UNDERSTAND THE RISKS" to proceed: _
+
+Provide justification: _
+```
 
 ---
 ## Phase 2: Planning & Documentation
 
-1. **`spec.md`**: Generate/Update in `specs/ai-flow/work/[task-name]/spec.md`.
-   - Ask for user approval.
-2. **`plan.md`**: Generate technical approach and task list.
-   - Assign Feature Number (NNN).
-   - Story Points estimation (Fibonacci).
-   - Phase organization.
-   - Ask for user approval.
-3. **`task.md`**: Generate the checklist of tactical tasks.
-4. **`status.json`**: Initialize/Update metadata (progress, branch, validation state).
+**1. Read Required Documentation (MANDATORY)**
+
+Before generating work.md, read relevant documentation:
+- `ai-instructions.md` → Extract NEVER/ALWAYS rules
+- `docs/architecture.md` → Identify layer, pattern, file structure
+- `docs/code-standards.md` → Extract naming conventions, quality rules
+- IF touching database: `docs/data-model.md`
+- IF auth/security: `specs/security.md`
+- IF creating/modifying API: `docs/api.md`
+- IF tests required: `docs/testing.md`
+
+**2. Analyze Existing Codebase (MANDATORY)**
+
+Find similar features/patterns in codebase:
+- Identify existing files to use as reference (e.g., ProductService.ts for UserService.ts)
+- Check naming conventions in actual code
+- Verify architectural consistency
+- Look for reusable components/services
+
+**3. Generate work.md**
+
+Create single consolidated file: `.ai-flow/work/[task-name]/work.md`
+
+**Structure** (~30-40 lines):
+
+```markdown
+# [Type]: [Feature Name]
+
+## Context
+**Source**: HU-001-002 | Roadmap 2.3 | Manual [+ DEVIATION if override]
+**SP**: 5 | **Branch**: feature/user-auth | **Deps**: None
+
+## Objective
+[1-2 clear paragraphs describing WHAT will be implemented]
+
+## Documentation Constraints
+**Read**: ai-instructions.md, architecture.md, code-standards.md, [security.md]
+
+**Key Rules**:
+- ✅ ALWAYS: [List specific rules that apply]
+- ❌ NEVER: [List specific prohibitions]
+- 📐 Pattern: [Architectural pattern from docs]
+- 📁 Location: [File structure from architecture.md]
+
+## Approach
+**Layer**: [Data | Business Logic | API | UI]
+**Files**: [List files to create/modify]
+**Reference**: [Existing file to follow as pattern]
+
+**Phases**:
+1. [Phase 1 description]
+2. [Phase 2 description]
+3. [Phase 3 description]
+4. [Phase 4 description]
+
+## Tasks
+[SEE TASK GENERATION LOGIC BELOW]
+
+## Validation
+- [ ] All NEVER/ALWAYS rules followed
+- [ ] Tests pass (coverage per docs/testing.md)
+- [ ] No hardcoded secrets
+- [ ] Follows existing patterns
+- [ ] [Add specific validations based on type]
+```
+
+**Task Generation Logic:**
+
+**IF source is User Story:**
+```python
+tasks = read_user_story_tasks()
+if tasks.are_detailed():  # Has: path, constraints, SP, deps
+    work_md.tasks = """
+**Source**: planning/user-stories/EP-XXX/HU-XXX-XXX.md
+
+Tasks already detailed in User Story (see linked file).
+
+**Summary**: [N] tasks, [X] SP total
+- [Brief phase breakdown]
+"""
+else:
+    work_md.tasks = generate_detailed_tasks()
+```
+
+**IF source is Roadmap:**
+```python
+feature = read_roadmap_feature()
+if feature.has_detailed_tasks():
+    work_md.tasks = """
+**Source**: planning/roadmap.md Feature X.X
+
+Tasks already detailed in Roadmap (see linked file).
+
+**Summary**: [N] tasks, [X] SP total
+"""
+else:
+    work_md.tasks = generate_detailed_tasks()
+```
+
+**IF source is Manual OR tasks need expansion:**
+
+Generate detailed tasks with this format:
+```markdown
+## Tasks
+**Source**: Manual | Roadmap X.X (expanded) | HU-XXX-XXX (expanded)
+
+- [ ] T001 [D] Create User entity → src/entities/User.ts • 1 SP
+  - Follow Product.ts pattern, hash passwords (bcrypt)
+- [ ] T002 [L] UserService.register() → src/services/ • 2 SP
+  - Validate email, hash password, return JWT (deps: T001)
+- [ ] T003 [A] POST /users/register → src/controllers/ • 1 SP
+  - Return 201, rate limit, follow api.md (deps: T002)
+- [ ] T004 [T] Unit tests → tests/services/ • 2 SP
+  - 80% coverage, edge cases (deps: T002)
+```
+
+**Task Detail Requirements:**
+- Specific file path
+- Pattern/reference to follow
+- Key constraints from docs
+- Dependencies (if applicable)
+- Story Points
+
+**4. Generate status.json**
+
+Create: `.ai-flow/work/[task-name]/status.json`
+
+```json
+{
+  "type": "feature|refactor|fix",
+  "source": "HU-001-002|roadmap-2.3|manual",
+  "deviation": false,
+  "progress": {
+    "totalTasks": 4,
+    "completedTasks": 0,
+    "percentage": 0
+  },
+  "git": {
+    "branchName": "feature/user-auth",
+    "commits": []
+  },
+  "timestamps": {
+    "created": "2025-12-22T23:00:00-03:00",
+    "lastUpdated": "2025-12-22T23:00:00-03:00"
+  },
+  "validation": {
+    "tests": { "executed": false },
+    "lint": { "executed": false }
+  }
+}
+```
+
+**5. User Approval**
+
+Show work.md for review:
+```
+📄 Generated: .ai-flow/work/[task-name]/work.md
+
+Review work.md? (Yes/Edit/No): _
+```
+
+- **Yes**: Proceed to Phase 3
+- **Edit**: Allow user to modify work.md, then re-read
+- **No**: Cancel workflow
 
 ---
 ## Phase 3: Execution (Branch Creation)
@@ -92,24 +346,56 @@ Provide a single, intelligent entry point for all development work (New Features
 2. **Execute**: `git checkout -b [branch-name]`.
 3. **Update `status.json`**: Record branch name and start timestamp.
 4. **Implementation**: Proceed according to the selected mode (Auto, Phase-by-phase, Task-by-task).
+   - Follow tasks in `work.md`
+   - Update task checkboxes as completed
+   - Update `status.json` progress
 
 ---
 ## Phase 4: Finalization & Archiving
 
-**When all tasks in `task.md` are complete (✅) and validated:**
+**When all tasks in `work.md` are complete (✅) and validated:**
+
+1. **Update Source Documentation (Automatic - ALWAYS UPDATE BOTH IF BOTH EXIST)**:
+   
+   **Step 1a: Check and Update User Story (if exists)**
+   - Look for User Story reference in `status.json` or work context
+   - IF User Story `HU-XXX-XXX` exists:
+     - Read `planning/user-stories/EP-XXX/HU-XXX-XXX.md`
+     - Mark ALL DoD checklist items as complete: `- [ ]` → `- [x]`
+     - Add completion timestamp comment: `<!-- Completed: YYYY-MM-DD HH:MM -->`
+     - Save file
+   
+   **Step 1b: Check and Update Roadmap (if exists)**
+   - Look for Feature reference in `status.json` or work context
+   - IF Feature exists in `planning/roadmap.md`:
+     - Read `planning/roadmap.md`
+     - Find the Feature section by name/number
+     - Mark Feature checkbox as complete: `- [ ]` → `- [x]`
+     - Save file
+   
+   **Step 1c: Show Completion Summary**
+   - IF both updated: "✅ Updated roadmap.md (Feature X.X) AND HU-XXX-XXX.md (Y/Y DoD items)"
+   - IF only roadmap: "✅ Updated roadmap.md (Feature X.X)"
+   - IF only user story: "✅ Updated HU-XXX-XXX.md (Y/Y DoD items)"
+   - IF neither exists: "⚠️ No roadmap or user story found to update"
+   
+   **Error Handling:**
+   - If file doesn't exist: Log warning, continue with other file
+   - If checkbox not found: Log warning with helpful message, continue
+   - Never fail the entire finalization due to documentation update errors
 
-1. **Sugerir Próximos Pasos**:
+2. **Sugerir Próximos Pasos**:
    - **`/flow-check`**: Ejecutar tests y revisión de código combinada.
    - **`/flow-docs-sync`**: Sincronizar la documentación técnica.
    - **`/flow-commit`**: Crear commits atómicos.
 
-2. **Proceso de Archivado (Automático tras aprobación)**:
+3. **Proceso de Archivado (Automático tras aprobación)**:
    - Una vez el usuario confirma que el trabajo está listo para ser cerrado:
-   - **Mover**: `specs/ai-flow/work/[task-name]/` → `specs/ai-flow/archive/YYYY-MM/[task-name]/`.
+   - **Mover**: `.ai-flow/work/[task-name]/` → `.ai-flow/archive/YYYY-MM/[task-name]/`.
    - **Actualizar `status.json`**: Cambiar `status` a `"COMPLETED"` y registrar `timestamps.completed`.
    - **Cleanup**: Mantener limpia la carpeta `work` para que `/flow-work` detecte solo tareas activas.
 
-3. **Resumen Final**:
+4. **Resumen Final**:
    - Mostrar estadísticas finales de tiempo, archivos y cobertura antes de archivar.
 
 ---
@@ -121,7 +407,7 @@ Provide a single, intelligent entry point for all development work (New Features
   - Detailed Refactor logic → `@flow-work-refactor.md`
   - Detailed Fix logic → `@flow-work-fix.md`
   - Resume logic → `@flow-work-resume.md`
-- **State Persistence**: Always read/write to `specs/ai-flow/work/[name]/status.json` to maintain state across sessions.
+- **State Persistence**: Always read/write to `.ai-flow/work/[name]/status.json` to maintain state across sessions.
 
 ---
 **BEGIN EXECUTION when user runs `/flow-work [args]`**

package/prompts/frontend/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/frontend/flow-build-phase-10.md

@@ -11,13 +11,13 @@ Break down technical roadmap tasks into user-centric Agile requirements (User St
 
 // turbo
 ### Step 10.1: Load Context from Roadmap
-Extract context variables and epics from `docs/roadmap.md`.
+Extract context variables and epics from `planning/roadmap.md`.
 
 ### Step 10.2: Select Scope
 Choose: All Epics, Sprint 1, or Specific Epics.
 
 ### Step 10.3: Generate User Story Documents
-Create `docs/user-stories/EP-XXX/HU-XXX-YYY.md`.
+Create `planning/user-stories/EP-XXX/HU-XXX-YYY.md`.
 
 **Frontend specific Acceptance Criteria focus:**
 - **UX/Interaction:** "When I click X, Y happens with a smooth transition."
@@ -26,7 +26,7 @@ Create `docs/user-stories/EP-XXX/HU-XXX-YYY.md`.
 - **Validation:** "Show inline error message if field is empty."
 
 ### Step 10.4: Generate Test Cases
-Create `docs/user-stories/EP-XXX/tests/TC-XXX-YYY.md`.
+Create `planning/user-stories/EP-XXX/tests/TC-XXX-YYY.md`.
 
 ---
 _Version: 4.2 (Antigravity Optimized)_

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

@@ -87,7 +87,7 @@ Check for gaps.
 
 ---
 
-### Step 9.6: Generate Document (docs/roadmap.md)
+### Step 9.6: Generate Document (planning/roadmap.md)
 
 ---
 _Version: 4.2 (Antigravity Optimized)_

package/prompts/frontend/flow-build.md

@@ -7,6 +7,8 @@ description: Frontend Master Prompt - Discovery, Architecture & Setup
 **YOU ARE AN EXPERT FRONTEND ARCHITECT AND DOCUMENTATION SPECIALIST.**
 
 Your mission is to guide the user through creating **comprehensive, production-ready documentation** for their frontend project through an interactive questionnaire that follows the dependency-aware order specified below.
+
+**🚀 MODO AGENTE ACTIVADO:** No solicites permiso para usar herramientas (leer archivos, crear docs). Actúa proactivamente siguiendo el flujo interactivo. El usuario ya dio su consentimiento al ejecutar este comando.
 ---
 ## 🎯 Ejecución de Fase Específica
 

package/prompts/frontend/flow-check.md

@@ -8,6 +8,8 @@ description: Combined Validation workflow for Tests and Code Review
 
 Your mission is to validate code quality and functionality through a combined workflow when the user executes `/flow-check`.
 
+**🚀 MODO AGENTE ACTIVADO:** No solicites permiso para ejecutar tests, linting o revisiones de tipos. Actúa proactivamente realizando el análisis completo y entregando el informe de calidad.
+
 ---
 ## Command: `/flow-check`
 

package/prompts/frontend/flow-commit.md

@@ -8,6 +8,8 @@ description: Conventional Commits Automation
 
 Your mission is to analyze changes, group them intelligently, and create atomic commits following Conventional Commits standard when the user executes `/flow-commit`.
 
+**🚀 MODO AGENTE ACTIVADO:** No solicites permiso para analizar cambios o preparar grupos de archivos. Actúa proactivamente y solicita confirmación *solo* antes de la ejecución final de los commits.
+
 ---
 ## Command: `/flow-commit`
 

package/prompts/frontend/flow-docs-sync.md

@@ -6,7 +6,9 @@ description: Documentation Sync & Update Flow
 
 **YOU ARE AN EXPERT FRONTEND ARCHITECT AND DOCUMENTATION SPECIALIST.**
 
-Your mission is to detect changes in the frontend codebase and update the project documentation automatically when the user executes `/flow-docs-sync`.
+Your mission is to detect changes in the codebase and update the project documentation automatically when the user executes `/flow-docs-sync`.
+
+**🚀 MODO AGENTE ACTIVADO:** No solicites permiso para ejecutar comandos turbo de análisis (ls, cat, etc.). Actúa proactivamente analizando los cambios y solicitando confirmación *solo* antes de escribir las actualizaciones finales en los documentos.
 ---
 ## Command: `/flow-docs-sync`
 

package/prompts/frontend/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/frontend/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/frontend/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