ai-flow-dev 2.6.0 → 2.8.0

package/prompts/backend/flow-work.md

@@ -27,6 +27,88 @@ Provide a single, intelligent entry point for all development work (New Features
 
 ---
 
+## Phase -1: Intent Classification (PRE-DETECTION)
+
+**CRITICAL: Determine if this is an INFORMATIVE request vs EXECUTION request BEFORE any workflow.**
+
+**🔍 INFORMATIVE Patterns (Answer directly, NO execution workflow):**
+
+- **Questions:** Starts with `¿`, `how`, `why`, `what`, `when`, `cómo`, `por qué`, `qué`, `cuál`
+- **Analysis verbs:** `explain`, `show`, `list`, `analyze`, `describe`, `compare`, `explica`, `muestra`, `analiza`, `describe`, `compara`
+- **Report requests:** `report`, `informe`, `document`, `documenta`, `summary`, `resumen`, `generate report`, `genera informe`
+- **Exploration:** `find`, `search`, `busca`, `encuentra`, `where is`, `dónde está`
+- **Review requests:** `review`, `revisa`, `check`, `verifica`, `audit`, `audita`
+
+**🛠️ EXECUTION Patterns (Enter workflow):**
+
+- **Action verbs:** `implement`, `create`, `refactor`, `fix`, `add`, `remove`, `update`, `delete`, `build`, `develop`
+- **Task codes:** `HU-\d{3}-\d{3}`, `EP-\d{3}`, `T\d{3}`
+- **Imperative:** `new feature`, `nueva feature`, `crear`, `implementar`
+
+**Detection Logic:**
+
+```python
+import re
+
+# Normalize input
+input_lower = input.strip().lower()
+
+# INFORMATIVE patterns (high priority)
+informative_patterns = [
+    r'^(¿|how|why|what|when|where|cómo|por qué|qué|cuál|dónde)',
+    r'^(explain|show|list|analyze|describe|compare|explica|muestra|analiza|describe|compara)',
+    r'(report|informe|document|documenta|summary|resumen)',
+    r'(find|search|busca|encuentra)',
+    r'(review|revisa|check|verifica|audit|audita)',
+]
+
+for pattern in informative_patterns:
+    if re.search(pattern, input_lower):
+        return "INFORMATIVE"  # → Jump to Phase 99
+
+# EXECUTION patterns
+execution_patterns = [
+    r'(HU-\d{3}-\d{3}|EP-\d{3}|T\d{3})',  # Task codes
+    r'^(implement|create|refactor|fix|add|remove|update|delete|build|develop)',
+    r'(implementar|crear|nueva feature|new feature)',
+]
+
+for pattern in execution_patterns:
+    if re.search(pattern, input_lower):
+        return "EXECUTION"  # → Continue to Phase 0
+
+# Ambiguous case - ask user
+return "AMBIGUOUS"
+```
+
+**Action based on detection:**
+
+**IF mode == "INFORMATIVE":**
+
+```
+🔍 Detected: Informative request (question/report/analysis)
+
+I'll provide a detailed answer without creating work files or branches.
+```
+
+→ **Jump to Phase 99: Informative Response**
+
+**IF mode == "EXECUTION":**
+
+→ **Continue to Phase 0** (current workflow)
+
+**IF mode == "AMBIGUOUS":**
+
+```
+❓ I'm not sure if this is:
+  A) A question/report request (I'll answer directly)
+  B) A task to implement (I'll create work plan and execute)
+
+Please clarify (A/B): _
+```
+
+---
+
 ## Phase 0: Detection & Strategy (Automatic)
 
 **1. Semantic Analysis of Input:**
@@ -657,48 +739,9 @@ git status --porcelain
 - All checkboxes in work.md marked complete
 - User explicitly requests finalization
 
-**CRITICAL: This phase requires EXPLICIT user confirmations at each step.**
-
----
-
-### Step 1: Validation Check
-
-```
-🔍 Running validation...
-```
-
-Execute:
-
-```bash
-npm test  # or project-specific test command
-npm run lint  # or project-specific lint command
-```
-
-Show results:
-
-```
-📊 Validation Results
-
-Tests: [✅ Passed | ❌ Failed (N tests)]
-Lint: [✅ Clean | ⚠️ N warnings | ❌ N errors]
-Coverage: [X%]
-
-Proceed with finalization?
-
-a) Yes, continue ⭐
-b) No, let me fix issues
-c) Skip validation (not recommended)
-
-Your choice: _
-```
-
-- **'b'**: Return to Phase 3 for fixes, END finalization
-- **'c'**: Show warning, ask confirmation again, then continue
-- **'a'**: Continue to Step 2
-
 ---
 
-### Step 2: Source Documentation Update (Interactive)
+### Source Documentation Update (Interactive)
 
 **Detect source references:**
 
@@ -762,261 +805,293 @@ Your choice: _
 
 ---
 
-### Step 3: Archiving Decision (Explicit Confirmation)
+## ✅ Development Work Complete
 
-**Show current state:**
+Your code is ready for finalization. You have two options:
 
-```bash
-git diff --stat
-git log --oneline origin/[base-branch]..HEAD
-```
+### Option A: Run Full Finalization Now (Recommended) ⭐
 
-**Present archiving options:**
+Execute `/flow-finish` to complete all finalization steps automatically:
 
-```
-💾 Task Completion Options
+- ✅ **Smart Validation** - Runs tests + lint only if needed (or revalidates if requested)
+- 📦 **Work Archiving** - Records analytics to `.ai-flow/archive/analytics.jsonl`, cleans workspace
+- 🤖 **AI-Powered Summaries** - Generates professional PR/Jira descriptions (~1,200 tokens)
+- 🚀 **Optional Push** - Pushes to remote with explicit confirmation
+
+**To proceed:** Type `/flow-finish` in the chat
+
+---
 
-Current work:
-- Branch: [branch-name]
-- Files changed: [N]
-- Commits: [N]
-- Duration: [X min]
+### Option B: Manual Finalization
 
-What do you want to do?
+If you prefer granular control over each step:
 
-a) Complete & Archive ⭐
-   → Record analytics, delete work files, clean state
+1. **Validation:** `/flow-check` - Run comprehensive validation (tests + code review)
+2. **Commit:** `/flow-commit` - Create conventional commit with auto-generated message
+3. **Archive:** Manually record analytics and clean `.ai-flow/work/[task-name]/`
+4. **Push:** `git push origin [branch-name]` when ready
 
-b) Complete & Keep
-   → Record analytics, rename folder to [task]-completed
+---
 
-c) Mark as Paused
-   → Keep work files for later resume
+**What would you like to do?**
 
-d) Cancel
-   → Go back to editing
+```
+a) Run /flow-finish now ⭐ (Recommended - comprehensive automation)
+b) I'll handle finalization manually (granular control)
+c) Tell me more about what /flow-finish does
 
 Your choice: _
 ```
 
-**IF 'a' (Complete & Archive):**
-
-```
-✅ Archiving task...
-```
-
-1. **Extract metadata:**
-
-   ```javascript
-   // IF complexity == "COMPLEX" (has status.json):
-   analytics = {
-     task: '[task-name]',
-     type: '[feature|refactor|fix]',
-     src: '[HU-001-002|roadmap-2.3|manual]',
-     dur: Math.round((completed - created) / 60000), // minutes
-     start: timestamps.created,
-     end: new Date().toISOString(),
-     tasks: progress.totalTasks,
-     sp: extract_story_points_from_work_md(),
-     commits: git.commits.length,
-     valid: validation.tests.passed && validation.lint.passed,
-   };
-
-   // IF complexity == "MEDIUM" (only work.md):
-   analytics = {
-     task: '[task-name]',
-     type: '[detected-from-folder-name]',
-     src: 'manual',
-     dur: estimate_duration_from_git_log(),
-     start: get_first_commit_timestamp(),
-     end: new Date().toISOString(),
-     tasks: count_checkboxes_in_work_md(),
-     sp: extract_story_points_from_work_md() || null,
-     commits: count_commits_in_branch(),
-     valid: validation_passed,
-   };
-   ```
+**If 'a':** Execute `/flow-finish` immediately
 
-2. **Append to analytics:**
+**If 'b':** Show confirmation and end workflow:
 
-   ```bash
-   echo '{json}' >> .ai-flow/archive/analytics.jsonl
-   ```
+```
+✅ Understood. Development complete.
 
-3. **Delete work folder:**
+📋 Manual finalization checklist:
+- [ ] Run validation: /flow-check
+- [ ] Commit changes: /flow-commit
+- [ ] Archive work folder
+- [ ] Push to remote
+- [ ] Create PR/MR
 
-   ```bash
-   rm -rf .ai-flow/work/[task-name]/
-   ```
+💡 Tip: You can run /flow-finish anytime to automate these steps.
 
-4. **Show confirmation:**
+🎉 Great work!
+```
 
-   ```
-   ✅ Task archived successfully
+**If 'c':** Show detailed explanation:
 
-   📊 Analytics recorded:
-   - Duration: [X] min
-   - Story Points: [N]
-   - Commits: [N]
-   - Validation: [✅ Passed | ❌ Failed]
-   ```
+```
+📖 About /flow-finish
 
-**IF 'b' (Complete & Keep):**
+/flow-finish is an intelligent finalization workflow that:
 
-1. Record analytics (same as 'a')
-2. Rename folder:
-   ```bash
-   mv .ai-flow/work/[task] .ai-flow/work/[task]-completed/
-   ```
-3. Show: `✅ Task marked complete. Files kept in: .ai-flow/work/[task]-completed/`
+1️⃣ **Smart Validation (Step 1)**
+   - Detects if /flow-check was already run successfully
+   - Only re-runs if explicitly requested or validation failed
+   - Shows comprehensive test + lint results
 
-**IF 'c' (Mark as Paused):**
+2️⃣ **Smart Commit (Step 2)**
+   - Detects uncommitted changes automatically
+   - Runs /flow-commit only if needed
+   - Generates conventional commit messages
 
-1. Add marker file:
-   ```bash
-   echo "Paused: $(date)" > .ai-flow/work/[task]/PAUSED
-   ```
-2. Show: `⏸️ Task paused. Resume with: /flow-work`
-3. **END finalization**
+3️⃣ **Work Archiving (Step 3)**
+   - Extracts analytics: duration, story points, commits
+   - Appends to .ai-flow/archive/analytics.jsonl
+   - Deletes .ai-flow/work/[task-name]/ folder
+
+4️⃣ **AI Summaries (Step 4)**
+   - Reads git diff + commit history
+   - Generates professional PR description
+   - Generates ticket update (Jira/ClickUp/Linear)
+   - ~1,200 tokens, markdown-formatted
 
-**IF 'd' (Cancel):**
+5️⃣ **Optional Push (Step 5)**
+   - Always asks for confirmation
+   - Shows branch name and remote
+   - Never pushes without explicit approval
 
-1. Show: `❌ Finalization cancelled. Task remains active.`
-2. **END finalization**
+**Would you like to run it now?** (y/n): _
+```
+
+**END WORKFLOW**
 
 ---
 
-### Step 4: Ticket Summary (Optional)
+## Orchestration Rules
 
-**Only ask if task was archived (option 'a' or 'b'):**
+- **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 `.ai-flow/work/[name]/status.json` to maintain state across sessions.
 
-```
-📋 Generate ticket summary?
+---
 
-(For ClickUp, Jira, Linear, Asana, Trello, GitHub Projects, etc.)
+## Phase 99: Informative Response
 
-y/n: _
-```
+**This phase handles questions, reports, and analysis requests WITHOUT creating work files or branches.**
 
-**IF 'y':**
+### 1. Analyze Request Type
 
-1. Check if template exists:
+**Classify the informative request:**
 
-   ```bash
-   [ -f .ai-flow/prompts/shared/task-summary-template.md ]
-   ```
+- **Technical Question:** How does X work? Why do we use Y?
+- **Code Explanation:** Explain this component/service/function
+- **Architecture Review:** Show me the architecture/patterns
+- **Project Report:** Generate report on tests/coverage/dependencies
+- **File Location:** Where is X? Find Y
+- **Comparison:** Compare X vs Y
+- **Best Practices:** What's the best way to do X?
 
-2. **IF template exists:**
-   - Read template
-   - Extract data from:
-     - Last line of `analytics.jsonl`
-     - Git stats: `git diff --stat`, `git log --oneline`
-     - Branch info
-   - Populate template with real data
-   - Show formatted summary
+### 2. Load Relevant Context
 
-3. **IF template doesn't exist:**
-   - Generate basic summary:
+**Based on request type, load specific documentation:**
 
-   ```
-   📋 Task Summary
+**IF question about architecture/patterns:**
 
-   **Task**: [task-name]
-   **Type**: [feature|refactor|fix]
-   **Duration**: [X min]
-   **Story Points**: [N]
-   **Commits**: [N]
-   **Branch**: [branch-name]
-   **Status**: ✅ Complete
+- Read `ai-instructions.md` (NEVER/ALWAYS rules)
+- Read `docs/architecture.md` (patterns, layers, structure)
+- Search codebase for examples
 
-   **Changes**:
-   [git diff --stat output]
+**IF question about specific feature:**
 
-   **Commits**:
-   [git log --oneline output]
-   ```
+- Search codebase for related files
+- Read relevant specs from `specs/`
+- Check `planning/roadmap.md` or User Stories
 
-4. Show: `📋 Copy the summary above to your ticket system`
+**IF report request:**
 
-**IF 'n':**
+- Run appropriate analysis (coverage, dependencies, etc.)
+- Read relevant docs for context
+- Generate structured report
 
-```
-⏭️ Skipping ticket summary
-```
+**IF file location request:**
 
----
+- Search codebase with grep/semantic search
+- List relevant files with descriptions
 
-### Step 5: Git Push (Final Step)
+### 3. Provide Comprehensive Answer
 
-```
-🚀 Push changes to remote?
+**Structure your response:**
 
-git push origin [branch-name]
+```markdown
+## [Question/Request]
 
-y/n: _
-```
+### Answer
 
-**IF 'y':**
+[Detailed explanation with code examples if relevant]
 
-```bash
-git push origin [branch-name]
-```
+### Related Documentation
 
-Show result:
+- [Link to relevant docs]
+- [Link to code examples]
 
-```
-✅ Pushed to origin/[branch-name]
+### Additional Context
+
+[Architecture decisions, best practices, warnings]
 
-Next steps:
-- Create Pull Request/Merge Request
-- Request code review
-- Update project board
+### Related User Stories/Features
+
+[If applicable, link to planning docs]
 ```
 
-**IF 'n':**
+**Guidelines:**
+
+- **Be comprehensive:** Load all relevant context, don't guess
+- **Show examples:** Include actual code from the project
+- **Reference docs:** Link to `docs/`, `specs/`, `planning/`
+- **Explain trade-offs:** Why was X chosen over Y?
+- **Provide sources:** Always cite where information comes from
+
+### 4. Offer Follow-up Actions
+
+**After answering, offer next steps:**
 
 ```
-⏭️ Skipping push
+✅ Answer provided.
 
-⚠️ Remember to push later:
-   git push origin [branch-name]
+Would you like me to:
+  A) Implement changes based on this analysis
+  B) Create a work plan for improvements
+  C) Generate a spec/doc for this
+  D) Nothing, just the answer
+
+Your choice (or just ask another question): _
 ```
 
----
+**IF user chooses A or B:**
+
+- Return to Phase 0 with refined objective
+- Create appropriate work.md and proceed with execution
+
+**IF user chooses C:**
+
+- Create spec/doc file in appropriate location
+- Commit with descriptive message
 
-### Finalization Complete
+**IF user chooses D or asks another question:**
+
+- **END WORKFLOW** (no files created, no branches)
+
+### 5. Example Interactions
+
+**Example 1: Technical Question**
 
 ```
-✅ Task Finalization Complete
+User: /flow-work ¿cómo funciona la autenticación JWT?
 
-📊 Summary:
-- [✅|⚠️] Validation passed
-- [✅|⏭️] Documentation updated
-- [✅|⏭️] Task archived
-- [✅|⏭️] Ticket summary generated
-- [✅|⏭️] Pushed to remote
+Agent:
+🔍 Detected: Informative request (question)
 
-Task: [task-name]
-Branch: [branch-name]
-Duration: [X min]
-Commits: [N]
+## How JWT Authentication Works in This Project
 
-🎉 Great work!
+### Implementation
+
+Our JWT implementation is in `src/services/auth.service.ts`:
+- Token generation: `generateToken(userId, email)`
+- Token validation: `verifyToken(token)`
+- Refresh mechanism: `refreshToken(refreshToken)`
+
+[Shows actual code from project]
+
+### Flow
+1. User logs in → POST /auth/login
+2. Server validates credentials
+3. Generates JWT with 1h expiration
+4. Returns { accessToken, refreshToken }
+5. Client includes token in Authorization header
+
+### Security Considerations
+- Tokens are signed with HS256
+- Secret stored in environment variable
+- Refresh tokens have 7-day expiration
+- No sensitive data in payload
+
+### Related Documentation
+- `specs/security.md` - Authentication specs
+- `docs/api.md` - Auth endpoints
+
+Would you like me to implement any changes to this? (Y/N): _
 ```
 
-**END WORKFLOW**
+**Example 2: Report Request**
 
----
+```
+User: /flow-work genera un informe de cobertura de tests
 
-## Orchestration Rules
+Agent:
+🔍 Detected: Informative request (report)
 
-- **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 `.ai-flow/work/[name]/status.json` to maintain state across sessions.
+## Test Coverage Report
+
+[Runs coverage analysis]
+
+### Overall Coverage: 78.5%
+
+| Category        | Coverage | Files |
+|-----------------|----------|-------|
+| Services        | 92%      | 12/13 |
+| Controllers     | 85%      | 8/10  |
+| Repositories    | 95%      | 10/10 |
+| Utilities       | 45%      | 5/11  |
+
+### Areas Needing Improvement
+1. `src/utils/validators.ts` - 20% coverage
+2. `src/utils/formatters.ts` - 35% coverage
+3. `src/controllers/reports.controller.ts` - 60% coverage
+
+### Recommendation
+Focus on utilities first (high reusability, low coverage).
+
+Would you like me to create a work plan to improve coverage? (Y/N): _
+```
 
 ---