ai-flow-dev 2.1.9 → 2.2.1

package/prompts/mobile/flow-commit.md

@@ -0,0 +1,51 @@
+---
+description: Conventional Commits Automation
+---
+
+# AI Flow - Commit Automation
+
+**YOU ARE AN EXPERT GIT WORKFLOW SPECIALIST.**
+
+Your mission is to analyze changes, group them intelligently, and create atomic commits following Conventional Commits standard when the user executes `/flow-commit`.
+
+---
+## Command: `/flow-commit`
+
+### Objective
+Automate commit creation with:
+- **Intelligent grouping** by functional relationship.
+- **Conventional Commits** compliance (type, scope, description).
+- **Atomic commits** (one logical change per commit).
+
+---
+## Workflow: 4 Steps
+
+### Step 1: Detect Changes
+- Modified files (unstaged/staged).
+- **Untracked files** (`git status --porcelain`).
+- Deleted files.
+
+### Step 2: Intelligent Grouping
+Group files by:
+- **Feature Complete**: Entity + Service + Controller + Tests + Docs.
+- **Refactoring**: Helper + Tests + Usages.
+- **Configuration**: Docker, Env, CI/CD.
+- **Independent Tests/Docs**.
+
+### Step 3: Create Commits
+1. Generate Conventional Commit message.
+2. `git add [files] && git commit -m "[message]"`.
+3. **Wait for user confirmation.**
+
+### Step 4: Summary & Push
+- Show `git log` of new commits.
+- Suggest `git push origin [branch]`.
+
+---
+## Integration with `status.json`
+- Update `git.commits` array.
+- Set `git.uncommittedChanges: false` when done.
+- Update `finalChecklist.committed: true`.
+
+---
+**BEGIN EXECUTION when user runs `/flow-commit`**

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

@@ -18,31 +18,33 @@ Detect changes in the mobile codebase compared to the last documented state (sto
 
 ### 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 mobile code analysis (as described in Phase 0)
+  - Run complete mobile 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 (mobile/flow-build-phase-0-context.md):
-     - File structure analysis
-     - Screen and component detection
-     - Navigation pattern detection
-     - State management pattern detection
-     - Permission detection (iOS Info.plist, Android AndroidManifest.xml)
-     - Native module detection
-     - Build configuration analysis
-     - Dependency analysis
+   - Execute project-wide discovery using cross-platform commands:
+     // turbo
+     ```bash
+     ls -R . --exclude-standard
+     ```
+   - Analyze current state for:
+     - View structures (Screens, Components, Layouts)
+     - Navigation hierarchies and routing patterns
+     - State management and data flow (Stores, Providers, Hooks)
+     - Platform-specific manifestations (Permissions, Native bridges, Config files)
+     - Manifest changes (build.gradle, Podfile, pubspec.yaml, package.json)
    - Generate current state snapshot
 
 2. **Compare with Previous State:**
@@ -50,15 +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:
-     - **Screens:** New, modified, or deleted screens
-     - **Navigation:** New routes, navigation pattern changes
-     - **State Management:** New stores, hooks, or state patterns
-     - **Permissions:** New permissions requested
-     - **Native Features:** New native modules or integrations
-     - **Dependencies:** New libraries, updated versions
-     - **Architecture:** New modules, changed patterns
-     - **Build Configuration:** Changes in build.gradle, Podfile, app.json
-     - **Configuration:** New environment variables, external services
+     - **Interfaces:** New, modified, or deleted "entry points" (Screens, Routes)
+     - **State Logic:** New, modified, or deleted state containers/logic
+     - **Capabilities:** New permissions or native feature integrations
+     - **Dependencies:** Manifest changes (version bumps, new packages)
+     - **Architecture:** Structural changes (new modules, moved folders)
+     - **Configuration:** New environment keys or build settings
 
 3. **Generate Change Report:**
    - Categorize changes by type
@@ -221,35 +220,33 @@ Update cancelled. Run `/flow-docs-sync` when you're ready to update the document
 ---
 ## Change Detection Rules
 
-### Screens Detection
+### View & Interface Detection (Agnostic)
 
-**What triggers `docs/navigation.md` update:**
+**What triggers document update (e.g., `docs/navigation.md`):**
 
-- New screen files (`.tsx`, `.jsx`, `.dart`, `.swift`, `.kt`)
-- New screen directories (`screens/`, `pages/`)
-- Modified navigation structure
-- Deleted screens
+- New view markers (e.g., Screen definitions, route mappings, or public component exports)
+- Modified navigation paths, hierarchies, or routing logic
+- Deleted views or screens
 
 **How to update:**
 
-- Add new screens following existing navigation conventions from Phase 2
-- Use same format, navigation patterns as existing screens
-- Maintain all existing screens unchanged
+- Add new views following the established patterns in the project
+- Update navigation diagrams (Mermaid) to reflect new hierarchies
+- Maintain existing documentation for unchanged segments
 
-### Permissions Detection
+### Capabilities & Native Detection (Agnostic)
 
-**What triggers `docs/permissions.md` update:**
+**What triggers document update (e.g., `docs/permissions.md`, `docs/native-features.md`):**
 
-- New permissions in `Info.plist` (iOS)
-- New permissions in `AndroidManifest.xml` (Android)
-- Modified permission descriptions
-- Deleted permissions
+- New platform capabilities requested (e.g., Info.plist keys, AndroidManifest permissions, or native package declarations)
+- New native bridges or modules detected in codebase
+- Modified permission usage or descriptions
 
 **How to update:**
 
-- Add new permissions to permissions documentation
-- Update permission descriptions if changed
-- Maintain all existing permissions
+- Document new capabilities and their usage rationale
+- Update native integration guides if patterns changed
+- Maintain existing documentation for stable features
 
 ### Native Features Detection
 

package/prompts/mobile/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/mobile/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/mobile/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/mobile/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/mobile/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]`**

package/prompts/shared/smart-skip-preflight.md

@@ -0,0 +1,214 @@
+# Smart Skip Pre-Flight Check (Shared Template)
+
+## 🔍 Pre-Flight Check Logic
+
+**This section is automatically included in Phases 1-7 to enable smart skip functionality.**
+
+### How It Works
+
+1. **Read audit data** from Phase 0: `.ai-flow/cache/audit-data.json`
+2. **Check consistency score** for the current phase
+3. **Execute appropriate scenario** based on score
+
+---
+
+## Execution Flow
+
+```javascript
+// Read audit data from Phase 0
+const auditData = readJSON('.ai-flow/cache/audit-data.json');
+const phaseData = auditData?.phases?.[currentPhase];
+
+if (phaseData?.exists) {
+  // Documentation exists, check consistency
+  if (phaseData.consistencyScore >= 95) {
+    executeScenarioA(); // SKIP
+  } else if (phaseData.consistencyScore >= 80) {
+    executeScenarioB(); // HYBRID
+  } else {
+    executeScenarioC(); // FULL
+  }
+} else {
+  // No existing docs, proceed with full phase
+  executeScenarioC();
+}
+```
+
+---
+
+## Scenario A: High Confidence (≥95%) - SKIP
+
+**Display format:**
+
+```
+---
+✅ [PHASE NAME] ALREADY DOCUMENTED
+
+File: [target-file]
+Consistency: [score]%
+Status: Complete documentation
+
+Documented Information:
+✅ [Key item 1]
+✅ [Key item 2]
+✅ [Key item 3]
+...
+
+---
+
+Use existing documentation? (Y/n) ⭐
+> _
+```
+
+**User Actions:**
+- **Y**: Skip to next phase
+- **n**: Proceed with full phase questionnaire
+
+---
+
+## Scenario B: Medium Confidence (80-94%) - HYBRID
+
+**Display format:**
+
+```
+---
+📚 [PHASE NAME] PARTIALLY DOCUMENTED
+
+File: [target-file]
+Consistency: [score]%
+Status: Most information present, some gaps
+
+Documented:
+✅ [Item 1]
+✅ [Item 2]
+
+Missing:
+❌ [Gap 1]
+❌ [Gap 2]
+
+---
+
+Options:
+A) Answer only [N] missing questions ⭐
+B) Re-answer everything (full phase)
+C) Skip entirely (use docs as-is)
+
+> _
+```
+
+**User Actions:**
+- **A**: Ask only missing questions, merge with existing docs
+- **B**: Full phase questionnaire
+- **C**: Skip with warning
+
+---
+
+## Scenario C: Low Confidence (<80%) or No Docs - FULL PHASE
+
+**Display format:**
+
+```
+---
+⚠️ [PHASE NAME] NEEDS DOCUMENTATION
+
+Reason: [target-file] is outdated or missing
+Consistency: [score]% (or N/A if file doesn't exist)
+
+Issues detected:
+❌ [Issue 1]
+❌ [Issue 2]
+
+Recommendation: Complete full phase questionnaire
+
+Proceeding with full phase...
+[Continue to first question]
+```
+
+---
+
+## Phase-Specific Configuration
+
+Each phase references this template with specific parameters:
+
+### Phase 1: Discovery & Business
+- **Target File**: `project-brief.md`
+- **Phase Name**: "BUSINESS CONTEXT"
+- **Key Items**: Project name, description, users, objectives, system type, features, scope, constraints, metrics, business flows
+- **Typical Gaps**: Business objectives, success metrics, constraints
+
+### Phase 2: Data Architecture
+- **Target File**: `docs/data-model.md`
+- **Phase Name**: "DATA ARCHITECTURE"
+- **Key Items**: Entities, relationships, data patterns, indexes
+- **Typical Gaps**: Missing entities, undocumented relationships, missing fields
+
+### Phase 3: System Architecture
+- **Target File**: `docs/architecture.md`
+- **Phase Name**: "SYSTEM ARCHITECTURE"
+- **Key Items**: Framework, architecture pattern, API style, database, caching, background jobs, integrations
+- **Typical Gaps**: API versioning, rate limiting, caching strategy
+
+### Phase 4: Security & Authentication
+- **Target File**: `specs/security.md`
+- **Phase Name**: "SECURITY & AUTHENTICATION"
+- **Key Items**: Auth strategy, encryption, security patterns, compliance
+- **Typical Gaps**: Compliance requirements, audit logging, security policies
+
+### Phase 5: Code Standards
+- **Target File**: `docs/code-standards.md`
+- **Phase Name**: "CODE STANDARDS"
+- **Key Items**: Linters, formatters, naming conventions, code review process
+- **Typical Gaps**: Team-specific conventions, code review workflow
+
+### Phase 6: Testing Strategy
+- **Target File**: `docs/testing.md`
+- **Phase Name**: "TESTING STRATEGY"
+- **Key Items**: Test framework, coverage targets, test types, CI/CD integration
+- **Typical Gaps**: E2E strategy, load testing, performance testing
+
+### Phase 7: Operations & Deployment
+- **Target File**: `docs/deployment.md`
+- **Phase Name**: "OPERATIONS & DEPLOYMENT"
+- **Key Items**: CI/CD pipeline, deployment platform, monitoring, logging
+- **Typical Gaps**: Incident runbooks, disaster recovery, scaling strategy
+
+---
+
+## Usage in Phase Prompts
+
+**In each phase prompt (1-7), add this reference:**
+
+```markdown
+## 🔍 Pre-Flight Check (Smart Skip Logic)
+
+> 📎 **Reference:** See [prompts/shared/smart-skip-preflight.md](../shared/smart-skip-preflight.md) for the complete smart skip logic.
+
+**Execute Pre-Flight Check for this phase:**
+
+- **Phase**: [Phase Number]
+- **Target File**: [file path]
+- **Phase Name**: [display name]
+
+[Proceed with appropriate scenario based on audit data]
+
+---
+
+## Phase [N] Questions (Full Mode)
+
+[Continue with phase-specific questions...]
+```
+
+---
+
+## Benefits of This Approach
+
+✅ **DRY Principle**: Single source of truth for skip logic
+✅ **Easy Maintenance**: Update once, applies to all phases
+✅ **Consistency**: Same UX across all phases
+✅ **Reduced File Size**: Each phase prompt is ~100 lines shorter
+✅ **Clear Separation**: Logic vs content
+
+---
+
+**Last Updated:** 2025-12-22
+**Version:** 1.0