ai-flow-dev 2.1.9 → 2.2.1

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

@@ -18,29 +18,33 @@ Detect changes in the frontend codebase compared to the last documented state (s
 
 ### Step 1: Check for Analysis File
 
+// turbo
+```bash
+cat .ai-flow/cache/docs-analysis.json
 ```
-First, check if `.ai-flow/cache/docs-analysis.json` exists:
 
 - ✅ If exists → Proceed to Step 2 (Compare Changes)
 - ❌ If NOT exists → Execute full Phase 0 analysis first:
-  - Run complete frontend code analysis (as described in Phase 0)
+  - Run complete frontend code analysis (Project Discovery)
   - Create `.ai-flow/cache/docs-analysis.json` with current state
   - Then proceed to Step 2
-```
 
 ### Step 2: Detect Changes
 
 **Reuse Phase 0 Analysis Logic:**
 
 1. **Perform Current Code Analysis:**
-
-   - Execute the same analysis as Phase 0 (frontend/flow-build-phase-0-context.md):
-     - File structure analysis
-     - Component detection and analysis
-     - State management pattern detection
-     - Styling approach detection
-     - Routing pattern detection
-     - Dependency analysis
+   - Execute project-wide discovery using cross-platform commands:
+     // turbo
+     ```bash
+     ls -R . --exclude-standard
+     ```
+   - Analyze current state for:
+     - View & UI components architecture
+     - Interface definitions (Routing patterns, public exports, entry points)
+     - State management and data flow (Global stores, Contexts, Hooks)
+     - Style definitions and design tokens
+     - Core dependencies and configuration
    - Generate current state snapshot
 
 2. **Compare with Previous State:**
@@ -48,12 +52,12 @@ First, check if `.ai-flow/cache/docs-analysis.json` exists:
    - Load `.ai-flow/cache/docs-analysis.json`
    - Compare current state vs previous state
    - Detect changes in:
-     - **Components:** New, modified, or deleted components
-     - **State Management:** New stores, hooks, or state patterns
-     - **Styling:** New stylesheets, design tokens, or styling approach changes
-     - **Dependencies:** New libraries, updated versions
-     - **Architecture:** New modules, changed patterns, routing changes
-     - **Configuration:** New environment variables, external services
+     - **Interfaces:** New, modified, or deleted "entry points" (Routes, Exports)
+     - **UI Structures:** New, modified, or deleted views/components
+     - **State Logic:** New, modified, or deleted state containers/logic
+     - **Style Forms:** New, modified, or deleted styling tokens/approaches
+     - **Dependencies:** Manifest changes (version bumps, new packages)
+     - **Configuration:** New environment keys or external integrations
 
 3. **Generate Change Report:**
    - Categorize changes by type
@@ -189,20 +193,19 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
 ---
 ## Change Detection Rules
 
-### Components Detection
+### UI & View Detection (Agnostic)
 
-**What triggers `docs/components.md` update:**
+**What triggers document update (e.g., `docs/components.md`):**
 
-- New component files (`.tsx`, `.jsx`, `.vue`, `.svelte`)
-- New component directories or structure changes
-- Modified component exports or patterns
+- New component definitions or file markers (e.g., standard exports, folder structures)
+- Modified component hierarchies or patterns
 - Deleted components
 
 **How to update:**
 
-- Add new components following existing component conventions from Phase 2
-- Use same format, naming conventions, and patterns as existing components
-- Maintain all existing components unchanged
+- Update component catalogs following established project conventions
+- Refresh hierarchy diagrams (Mermaid) to reflect new structures
+- Maintain existing documentation for stable components
 
 ### State Management Detection
 
@@ -220,20 +223,19 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
 - Update state patterns if changed
 - Maintain all existing state management documentation
 
-### Styling Detection
+### Style & Design Detection (Agnostic)
 
-**What triggers `docs/styling.md` update:**
+**What triggers document update (e.g., `docs/styling.md`):**
 
-- New stylesheet files (`.css`, `.scss`, `.module.css`)
-- New design token files
-- Changes in `tailwind.config.*`, `postcss.config.*`
-- Modified styling approach
+- New style manifest files or token definitions
+- Modified design systems or styling approaches
+- Structural changes in asset organization
 
 **How to update:**
 
-- Add new design tokens or styling patterns
-- Update styling guidelines if approach changed
-- Maintain all existing styling documentation
+- Document new styling patterns or tokens
+- Update architecture guides if styling methodology changed
+- Maintain existing documentation for core design principles
 
 ### Dependencies Detection
 

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

@@ -0,0 +1,42 @@
+---
+description: Internal logic for Feature implementation within flow-work
+---
+
+# AI Flow - Feature Logic
+
+This file contains the detailed execution logic for implementing new features, imported by `@flow-work.md`.
+
+---
+## 🚀 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`.
+
+### 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.**
+
+### 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.
+
+### 4. Definition of Done (DoD)
+- If HU mode: Validate against Gherkin scenarios.
+- Run tests and linting.
+- Perform security check.
+
+---
+## 🌿 Git Branching Strategy
+- Generate slug from name.
+- Execute `git checkout -b feature/[slug]`.
+- Maintain `status.json` with commit history.
+
+---
+## 📦 status.json Persistence
+Ensure `progress`, `git`, and `metadata` sections are always updated.

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

@@ -0,0 +1,33 @@
+---
+description: Internal logic for Bug Fixes within flow-work
+---
+
+# AI Flow - Fix Logic
+
+This file contains the detailed execution logic for bug fixes, imported by `@flow-work.md`.
+
+---
+## 🔧 Bug Fix Workflow
+
+### 1. Classification
+- **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.
+
+### 3. Implementation
+- **Test-First Approach**: Add a failing test case that reproduces the bug before fixing it.
+- Apply the fix.
+- Verify tests pass.
+
+---
+## 🌿 Git Branching Strategy
+- **QUICK**: Usually work on current branch.
+- **COMPLEX**: Execute `git checkout -b fix/[slug]`.
+
+---
+## 📦 status.json Persistence
+Track root cause details and verification test status.

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

@@ -0,0 +1,32 @@
+---
+description: Internal logic for Refactor implementation within flow-work
+---
+
+# AI Flow - Refactor Logic
+
+This file contains the detailed execution logic for code refactoring, imported by `@flow-work.md`.
+
+---
+## 🔄 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.
+
+---
+## 🌿 Git Branching Strategy
+- Execute `git checkout -b refactor/[slug]`.
+
+---
+## 📦 status.json Persistence
+Track `percentage` of updated occurrences and updated file paths.

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

@@ -0,0 +1,32 @@
+---
+description: Internal logic for Resuming work within flow-work
+---
+
+# AI Flow - Resume Logic
+
+This file contains the logic for detecting and resuming paused work items, imported by `@flow-work.md`.
+
+---
+## ⏸️ Resume Workflow
+
+### 1. Work Detection
+- Scan `specs/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).
+
+### 3. Context Restoration
+- Load `spec.md`, `plan.md`, `task.md`, and `status.json`.
+- Verify Git branch:
+  - If mismatch: Prompt to switch to `git.branchName`.
+- Identify the first incomplete task in `task.md`.
+
+### 4. Implementation Continuation
+- Resume with the previously saved `implementationMode`.
+- Continue execution from where it was paused.
+
+---
+## 📦 status.json Persistence
+Update `timestamps.lastUpdated` upon resuming.

package/prompts/frontend/flow-work.md

@@ -0,0 +1,127 @@
+---
+description: Central Orchestrator for Feature, Refactor, and Fix workflows
+---
+
+# AI Flow - Unified Work Orchestrator
+
+**YOU ARE AN EXPERT SOFTWARE ARCHITECT AND WORKFLOW COORDINATOR.**
+
+Your mission is to orchestrate development tasks through an interactive workflow when the user executes `/flow-work`.
+
+---
+## Command: `/flow-work`
+
+### Objective
+Provide a single, intelligent entry point for all development work (New Features, Refactorings, and Bug Fixes) with automatic context detection and interactive planning.
+
+### Usage Modes
+- **`/flow-work`** → Resume paused work (if exists) or Interactive mode.
+- **`/flow-work [description]`** → Semantic detection (Feature, Refactor, or Fix).
+- **`/flow-work HU-XXX-XXX`** → Implement specific User Story.
+- **`/flow-work [Feature Name]`** → Implement feature from roadmap.md.
+
+---
+## Phase 0: Detection & Strategy (Automatic)
+
+**1. Semantic Analysis of Input:**
+
+| Input Pattern | Mode | Source / Action |
+|---------------|------|-----------------|
+| `HU-\d{3}-\d{3}` | `USER_STORY` | Load from `docs/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) |
+| "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/` |
+
+**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".
+- **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
+
+**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).
+
+**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 ⭐)**.
+
+**Example Interaction:**
+> 📝 I need to clarify some details for this feature:
+> 1. What authentication provider should we use? [default: A]
+>    A) JWT (Local) ⭐
+>    B) OAuth2 (Google/GitHub)
+>    C) Firebase Auth
+>
+> 2. Should we implement audit logs for this? [default: B]
+>    A) Yes
+>    B) No ⭐
+
+---
+## 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).
+
+---
+## Phase 3: Execution (Branch Creation)
+
+**Upon confirmation to start implementation:**
+
+1. **Generate Branch Name**:
+   - `feature/[slug]`
+   - `refactor/[slug]`
+   - `fix/[slug]`
+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).
+
+---
+## Phase 4: Finalization & Archiving
+
+**When all tasks in `task.md` are complete (✅) and validated:**
+
+1. **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)**:
+   - 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]/`.
+   - **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**:
+   - Mostrar estadísticas finales de tiempo, archivos y cobertura antes de archivar.
+
+---
+## Orchestration Rules
+
+- **DRY Logic**: This file handles the high-level orchestration.
+- **Delegation**:
+  - Detailed Feature logic → `@flow-work-feature.md`
+  - 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.
+
+---
+**BEGIN EXECUTION when user runs `/flow-work [args]`**