ai-flow-dev 2.6.0 → 2.8.0

package/prompts/frontend/flow-work.md

@@ -27,12 +27,95 @@ 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:**
 
 | Input Pattern                  | Mode              | Source / Action                                                      |
 | ------------------------------ | ----------------- | -------------------------------------------------------------------- |
+| `api\s+([a-z0-9\-_]+)`         | `API_MODULE`      | Invoke `.ai-flow/prompts/frontend/flow-work-api.md` analyzer         |
 | `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`)                    |
@@ -53,6 +136,453 @@ Provide a single, intelligent entry point for all development work (New Features
 
 ---
 
+## Phase 0.1: API Module Analysis (Conditional)
+
+**ONLY execute if `mode == "API_MODULE"`**
+
+This phase manages API URL configuration, invokes the specialized API analyzer, and enriches workflow context with OpenAPI metadata.
+
+**🏗️ Architecture Design:**
+
+- **This prompt (flow-work)**: Orchestrator with state management (cache, validation, retry logic)
+- **Sub-prompt (flow-work-api)**: Pure analyzer (stateless, receives validated URL)
+- **Cache location**: `.ai-flow/cache/api-config.json`
+- **Why this separation?**:
+  - Reusability: analyzer can be used from different orchestrators
+  - Testability: pure analyzers are easier to test
+  - Maintainability: state management centralized in one place
+
+### Step 1: Load or Detect API URL (Cache Management)
+
+**1.1. Parse User Input**
+
+Extract module name and optional API URL override:
+
+```typescript
+// Input examples:
+// - "/flow-work api users"
+// - "api organizations --api-url=http://localhost:3000/api/docs-json"
+
+const pattern = /api\s+([a-z0-9\-_]+)(\s+--api-url=(.+))?/;
+const match = userInput.match(pattern);
+
+const moduleName = match[1]; // 'users', 'organizations', etc.
+const customApiUrl = match[3]; // Optional override from user
+```
+
+**1.2. Check Cache**
+
+```javascript
+const cacheFile = '.ai-flow/cache/api-config.json';
+let apiUrl = null;
+let cacheStatus = 'none';
+
+if (await fileExists(cacheFile)) {
+  const cache = JSON.parse(await readFile(cacheFile));
+
+  // Check if cache is recent (< 24 hours)
+  const lastVerified = new Date(cache.lastVerified);
+  const hoursSinceVerified = (Date.now() - lastVerified) / 3600000;
+
+  if (hoursSinceVerified < 24) {
+    apiUrl = cache.apiUrl;
+    cacheStatus = 'valid';
+    console.log(`✅ Using cached API URL (verified ${Math.round(hoursSinceVerified)}h ago)`);
+    console.log(`   ${apiUrl}`);
+  } else {
+    apiUrl = cache.apiUrl; // Still use it, but will re-validate
+    cacheStatus = 'expired';
+    console.log(`⚠️  Cache expired (${Math.round(hoursSinceVerified)}h old), will re-validate`);
+    console.log(`   ${apiUrl}`);
+  }
+}
+
+// User override via --api-url flag takes precedence
+if (customApiUrl) {
+  apiUrl = customApiUrl;
+  cacheStatus = 'override';
+  console.log(`🔧 Using URL override from command: ${apiUrl}`);
+}
+
+// Default fallback
+if (!apiUrl) {
+  apiUrl = 'http://localhost:3001/api/docs-json';
+  cacheStatus = ' default';
+  console.log(`🔗 Using default API URL: ${apiUrl}`);
+}
+```
+
+**1.3. Validate URL (Quick Test)**
+
+```typescript
+if (cacheStatus === 'valid') {
+  // Skip validation for recent cache (trust it)
+  console.log(`⏭️  Skipping validation (cache is recent)`);
+} else {
+  // Validate URL before invoking analyzer
+  console.log(`\n🔗 Validating API URL: ${apiUrl}`);
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000); // 5s quick test
+
+    const response = await fetch(apiUrl, {
+      method: 'HEAD', // Just check if endpoint exists
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      console.log(`✅ Connection successful`);
+    } else {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+  } catch (error) {
+    // Connection failed - prompt user
+    return await handleConnectionError(error, apiUrl, cacheFile);
+  }
+}
+```
+
+**1.4. Handle Connection Errors (Interactive)**
+
+```typescript
+async function handleConnectionError(error: Error, attemptedUrl: string, cacheFile: string) {
+  const errorMessage =
+    error.name === 'AbortError'
+      ? 'Connection timeout (backend might not be running)'
+      : error.message;
+
+  console.log(`
+❌ Failed to connect to OpenAPI documentation
+
+Attempted URL: ${attemptedUrl}
+Error: ${errorMessage}
+
+Common causes:
+  1. Backend server is not running (npm run dev / npm start)
+  2. Wrong port (check backend .env or package.json)
+  3. Different path (/api/docs vs /api/docs-json)
+  4. CORS not configured for your frontend origin
+
+Options:
+  a) Provide correct URL ⭐
+  b) Retry current URL (if backend is starting up)
+  c) Skip API analysis (manual mode - no OpenAPI specs)
+  d) Cancel
+
+Your choice: _
+  `);
+
+  const choice = await readUserInput();
+
+  if (choice === 'a') {
+    const newUrl = await promptForUrl(cacheFile);
+    return { apiUrl: newUrl, validated: true };
+  }
+
+  if (choice === 'b') {
+    console.log('\n⏳ Waiting 3 seconds for backend to start...');
+    await sleep(3000);
+
+    // Retry validation
+    try {
+      await fetch(attemptedUrl, { method: 'HEAD', signal: AbortSignal.timeout(5000) });
+      console.log('✅ Connection successful after retry');
+      return { apiUrl: attemptedUrl, validated: true };
+    } catch (retryError) {
+      console.log('❌ Still failing. Please check backend status.');
+      return await handleConnectionError(retryError, attemptedUrl, cacheFile);
+    }
+  }
+
+  if (choice === 'c') {
+    console.log('\n⏭️  Skipping API analysis. Switching to manual FEATURE mode...');
+    return { mode: 'FEATURE', apiUrl: null, validated: false };
+  }
+
+  if (choice === 'd') {
+    throw new Error('User cancelled operation');
+  }
+
+  // Invalid choice - ask again
+  console.log('\n❌ Invalid option. Please enter a, b, c, or d.');
+  return await handleConnectionError(error, attemptedUrl, cacheFile);
+}
+```
+
+**1.5. Prompt for URL (with Validation)**
+
+```typescript
+async function promptForUrl(cacheFile: string): Promise<string> {
+  console.log(`\n📝 Enter OpenAPI Documentation URL\n
+Common patterns:
+  NestJS:     http://localhost:3000/api/docs-json
+  Express:    http://localhost:3001/api-docs
+  FastAPI:    http://localhost:8000/openapi.json
+  Spring:     http://localhost:8080/v3/api-docs
+
+URL: _
+  `);
+
+  const url = await readUserInput();
+
+  // Validate format
+  if (!url.startsWith('http://') && !url.startsWith('https://')) {
+    console.log('\n❌ URL must start with http:// or https://');
+    return await promptForUrl(cacheFile);
+  }
+
+  // Test URL
+  console.log(`\n🔗 Testing connection to: ${url}`);
+
+  try {
+    const response = await fetch(url, {
+      method: 'HEAD',
+      signal: AbortSignal.timeout(5000),
+      headers: { Accept: 'application/json' },
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    console.log(`
+✅ Connection successful!
+
+💾 Saving URL to cache for future commands...
+    `);
+
+    // Save to cache
+    await saveToCache(cacheFile, {
+      apiUrl: url,
+      lastVerified: new Date().toISOString(),
+      projectType: 'frontend',
+    });
+
+    return url;
+  } catch (error) {
+    const errorMsg = error.name === 'AbortError' ? 'Connection timeout' : error.message;
+
+    console.log(`\n❌ Failed to connect to ${url}\n   Error: ${errorMsg}\n
+Try again? (y/n): _
+    `);
+
+    const retry = await readUserInput();
+    if (retry.toLowerCase() === 'y') {
+      return await promptForUrl(cacheFile);
+    } else {
+      throw new Error('User cancelled after failed URL validation');
+    }
+  }
+}
+```
+
+**1.6. Cache Management Functions**
+
+```typescript
+async function saveToCache(
+  cacheFile: string,
+  data: { apiUrl: string; lastVerified: string; projectType: string }
+) {
+  const cacheDir = '.ai-flow/cache';
+
+  // Ensure directory exists
+  if (!(await fileExists(cacheDir))) {
+    await createDirectory(cacheDir);
+  }
+
+  // Load existing cache or create new
+  let cache: any = { history: [] };
+  if (await fileExists(cacheFile)) {
+    try {
+      cache = JSON.parse(await readFile(cacheFile));
+    } catch {
+      // Corrupted cache, start fresh
+      cache = { history: [] };
+    }
+  }
+
+  // Update cache
+  cache.apiUrl = data.apiUrl;
+  cache.lastVerified = data.lastVerified;
+  cache.projectType = data.projectType;
+
+  // Add to history
+  cache.history = cache.history || [];
+  cache.history.unshift({
+    url: data.apiUrl,
+    timestamp: data.lastVerified,
+    status: 'success',
+  });
+
+  // Keep only last 10 entries
+  cache.history = cache.history.slice(0, 10);
+
+  // Save
+  await writeFile(cacheFile, JSON.stringify(cache, null, 2));
+}
+
+async function clearCache(cacheFile: string) {
+  if (await fileExists(cacheFile)) {
+    await deleteFile(cacheFile);
+    console.log('✅ API cache cleared');
+  }
+}
+```
+
+### Step 2: Invoke API Module Analyzer
+
+**Call sub-prompt with validated URL:**
+
+```typescript
+console.log(`\n🔍 Analyzing API module: ${moduleName}`);
+console.log(`📡 Fetching OpenAPI spec from: ${apiUrl}\n`);
+
+const analysisResult: OpenAPIAnalysisResult = await invoke_subprompt(
+  '.ai-flow/prompts/frontend/flow-work-api.md',
+  {
+    module: moduleName,
+    apiUrl: apiUrl, // Validated URL
+  }
+);
+```
+
+**Sub-prompt responsibilities:**
+
+- Fetch OpenAPI spec from backend
+- Detect project stack (MUI, MRT, React Hook Form, Zod, TanStack Query, etc.)
+- Extract all endpoints for the module
+- Parse DTOs (Response, Create, Update)
+- Detect field specifications with validation rules
+- Identify relationships (foreign keys, populated entities)
+- Detect features (pagination, search, sorting, filters)
+- Calculate complexity (SIMPLE/MEDIUM/COMPLEX)
+- Return structured `OpenAPIAnalysisResult` JSON
+
+### Step 3: Handle Sub-Prompt Result
+
+**IF `analysisResult.success === true`:**
+
+```
+✅ API Analysis Complete
+
+Module: ${analysisResult.module}
+Endpoints: ${analysisResult.endpoints.length}
+Complexity: ${analysisResult.complexity.level}
+
+💾 Updating cache with successful connection...
+
+Proceeding with enriched context...
+```
+
+Store in workflow context:
+
+```typescript
+workflow_context.analysis = analysisResult;
+workflow_context.mode = 'API_MODULE';
+workflow_context.module = analysisResult.module;
+
+// Update cache with successful analysis
+await saveToCache(cacheFile, {
+  apiUrl: apiUrl,
+  lastVerified: new Date().toISOString(),
+  projectType: 'frontend',
+});
+```
+
+**IF `analysisResult.success === false`:**
+
+```
+❌ API Analysis Failed
+
+Error: ${analysisResult.error}
+Details: ${analysisResult.details}
+
+Suggestions:
+${analysisResult.suggestions.map((s, i) => `  ${i+1}. ${s}`).join('\n')}
+
+The API URL might have changed or the backend spec is invalid.
+
+Options:
+  A) Update URL and retry
+  B) Clear cache and try default URL
+  C) Proceed with manual mode (no OpenAPI analysis)
+  D) Cancel
+
+Your choice: _
+```
+
+**User selects:**
+
+- **A**: Prompt for new URL, save to cache, retry Phase 0.1
+- **B**: Clear cache, use default, retry Phase 0.1
+- **C**: Switch to `FEATURE` mode, continue without OpenAPI
+- **D**: Abort workflow
+
+### Step 4: Enrich Workflow Context
+
+Merge analysis into workflow context for use in subsequent phases:
+
+```typescript
+workflow_context = {
+  ...workflow_context,
+
+  // From API analysis
+  projectStandards: analysisResult.projectStandards,
+  openapi: analysisResult.openapi,
+  endpoints: analysisResult.endpoints,
+  schemas: analysisResult.schemas,
+  fields: analysisResult.fields,
+  features: analysisResult.features,
+  relationships: analysisResult.relationships,
+
+  // For Phase 2 (work.md generation)
+  template: 'api-module', // Use specialized template
+
+  // For Phase 0.5 (complexity override)
+  complexity_override: analysisResult.complexity.level,
+  estimatedSP: analysisResult.complexity.estimatedSP,
+  estimatedHours: analysisResult.complexity.estimatedHours,
+};
+```
+
+### Step 5: Show Analysis Summary
+
+Present structured summary to user (condensed version):
+
+```
+📋 API Module Analysis Summary
+
+📊 Module: ${moduleName}
+🔗 API: ${apiUrl}
+
+📐 Detected Project Stack:
+  UI: ${projectStandards.stack.ui}
+  Table: ${projectStandards.stack.table} ✅
+  Forms: ${projectStandards.stack.forms} + ${projectStandards.stack.validation} ✅
+  Data: ${projectStandards.stack.query} ✅
+
+🔧 Endpoints: ${endpoints.length} detected
+📦 Entity: ${schemas.response.fields.length} fields
+🔗 Relationships: ${relationships.length}
+🏗️ Complexity: ${complexity.level} (${complexity.estimatedHours}h estimated)
+
+✅ All standards locked. Module will match existing patterns.
+
+Proceeding to Phase 0.5...
+```
+
+### Step 6: Continue to Phase 0.5
+
+With enriched context, proceed to complexity classification.
+
+**Note**: In API_MODULE mode, complexity is already determined by the analyzer, so Phase 0.5 will use `workflow_context.complexity_override` instead of calculating it.
+
+---
+
 ## Phase 0.5: Complexity Classification (CRITICAL)
 
 **Analyze task scope to determine workflow:**
@@ -89,7 +619,10 @@ Provide a single, intelligent entry point for all development work (New Features
 **Detection Logic:**
 
 ```python
-if files_affected == 1 and lines_changed < 20 and no_tests_needed and no_architecture_impact:
+# Special case: API_MODULE mode (complexity already determined)
+if mode == "API_MODULE":
+    complexity = workflow_context.complexity_override  # From API analyzer
+elif files_affected == 1 and lines_changed < 20 and no_tests_needed and no_architecture_impact:
     complexity = "SIMPLE"
 elif files_affected <= 5 and lines_changed <= 100 and architecture_impact == "minimal":
     complexity = "MEDIUM"
@@ -661,48 +1194,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:**
 
@@ -766,262 +1260,324 @@ 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
 
-Current work:
-- Branch: [branch-name]
-- Files changed: [N]
-- Commits: [N]
-- Duration: [X min]
+**To proceed:** Type `/flow-finish` in the chat
 
-What do you want to do?
+---
 
-a) Complete & Archive ⭐
-   → Record analytics, delete work files, clean state
+### Option B: Manual Finalization
 
-b) Complete & Keep
-   → Record analytics, rename folder to [task]-completed
+If you prefer granular control over each step:
 
-c) Mark as Paused
-   → Keep work files for later resume
+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
 
-d) Cancel
-   → Go back to editing
+---
+
+**What would you like to do?**
+
+```
+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):**
+**If 'a':** Execute `/flow-finish` immediately
+
+**If 'b':** Show confirmation and end workflow:
 
 ```
-✅ Archiving task...
-```
+✅ Understood. Development complete.
 
-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,
-   };
-   ```
+📋 Manual finalization checklist:
+- [ ] Run validation: /flow-check
+- [ ] Commit changes: /flow-commit
+- [ ] Archive work folder
+- [ ] Push to remote
+- [ ] Create PR/MR
 
-2. **Append to analytics:**
+💡 Tip: You can run /flow-finish anytime to automate these steps.
 
-   ```bash
-   echo '{json}' >> .ai-flow/archive/analytics.jsonl
-   ```
+🎉 Great work!
+```
 
-3. **Delete work folder:**
+**If 'c':** Show detailed explanation:
 
-   ```bash
-   rm -rf .ai-flow/work/[task-name]/
-   ```
+```
+📖 About /flow-finish
 
-4. **Show confirmation:**
+/flow-finish is an intelligent finalization workflow that:
 
-   ```
-   ✅ Task archived successfully
+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
 
-   📊 Analytics recorded:
-   - Duration: [X] min
-   - Story Points: [N]
-   - Commits: [N]
-   - Validation: [✅ Passed | ❌ Failed]
-   ```
+2️⃣ **Smart Commit (Step 2)**
+   - Detects uncommitted changes automatically
+   - Runs /flow-commit only if needed
+   - Generates conventional commit messages
 
-**IF 'b' (Complete & Keep):**
+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
 
-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/`
+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 'c' (Mark as Paused):**
+5️⃣ **Optional Push (Step 5)**
+   - Always asks for confirmation
+   - Shows branch name and remote
+   - Never pushes without explicit approval
 
-1. Add marker file:
-   ```bash
-   echo "Paused: $(date)" > .ai-flow/work/[task]/PAUSED
-   ```
-2. Show: `⏸️ Task paused. Resume with: /flow-work`
-3. **END finalization**
+**Would you like to run it now?** (y/n): _
+```
+
+**END WORKFLOW**
 
-**IF 'd' (Cancel):**
+---
 
-1. Show: `❌ Finalization cancelled. Task remains active.`
-2. **END finalization**
+## 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 `.ai-flow/work/[name]/status.json` to maintain state across sessions.
 
 ---
 
-### Step 4: Ticket Summary (Optional)
+## Phase 99: Informative Response
 
-**Only ask if task was archived (option 'a' or 'b'):**
+**This phase handles questions, reports, and analysis requests WITHOUT creating work files or branches.**
 
-```
-📋 Generate ticket summary?
+### 1. Analyze Request Type
 
-(For ClickUp, Jira, Linear, Asana, Trello, GitHub Projects, etc.)
+**Classify the informative request:**
 
-y/n: _
-```
+- **Technical Question:** How does X work? Why do we use Y?
+- **Component Explanation:** Explain this component/hook/utility
+- **Architecture Review:** Show me the component structure/state management
+- **Project Report:** Generate report on bundle size/dependencies/performance
+- **File Location:** Where is X component? Find Y hook
+- **Comparison:** Compare X vs Y approach
+- **Best Practices:** What's the best way to do X in React/Vue/Angular?
 
-**IF 'y':**
+### 2. Load Relevant Context
 
-1. Check if template exists:
+**Based on request type, load specific documentation:**
 
-   ```bash
-   [ -f .ai-flow/prompts/shared/task-summary-template.md ]
-   ```
+**IF question about architecture/patterns:**
 
-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
+- Read `ai-instructions.md` (NEVER/ALWAYS rules)
+- Read `docs/architecture.md` (component structure, state management)
+- Search codebase for examples
 
-3. **IF template doesn't exist:**
-   - Generate basic summary:
+**IF question about specific component:**
 
-   ```
-   📋 Task Summary
+- Search codebase for component files
+- Read relevant specs from `specs/`
+- Check related hooks/utilities
 
-   **Task**: [task-name]
-   **Type**: [feature|refactor|fix]
-   **Duration**: [X min]
-   **Story Points**: [N]
-   **Commits**: [N]
-   **Branch**: [branch-name]
-   **Status**: ✅ Complete
+**IF report request:**
 
-   **Changes**:
-   [git diff --stat output]
+- Run appropriate analysis (bundle size, performance, dependencies)
+- Read relevant docs for context
+- Generate structured report
 
-   **Commits**:
-   [git log --oneline output]
-   ```
+**IF file location request:**
 
-4. Show: `📋 Copy the summary above to your ticket system`
+- Search codebase with grep/semantic search
+- List relevant components with descriptions
 
-**IF 'n':**
+### 3. Provide Comprehensive Answer
 
-```
-⏭️ Skipping ticket summary
-```
+**Structure your response:**
 
----
+```markdown
+## [Question/Request]
 
-### Step 5: Git Push (Final Step)
+### Answer
 
-```
-🚀 Push changes to remote?
+[Detailed explanation with code examples if relevant]
+
+### Related Documentation
+
+- [Link to relevant docs]
+- [Link to component examples]
 
-git push origin [branch-name]
+### Additional Context
 
-y/n: _
+[Architecture decisions, design patterns, performance considerations]
+
+### Related User Stories/Features
+
+[If applicable, link to planning docs]
 ```
 
-**IF 'y':**
+**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 pattern chosen over Y?
+- **Provide sources:** Always cite where information comes from
+
+### 4. Offer Follow-up Actions
+
+**After answering, offer next steps:**
 
-```bash
-git push origin [branch-name]
 ```
+✅ Answer provided.
 
-Show result:
+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): _
 ```
-✅ Pushed to origin/[branch-name]
 
-Next steps:
-- Create Pull Request/Merge Request
-- Request code review
-- Update project board
+**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
+
+**IF user chooses D or asks another question:**
+
+- **END WORKFLOW** (no files created, no branches)
+
+### 5. Example Interactions
+
+**Example 1: Technical Question**
+
+````
+User: /flow-work ¿cómo funciona el state management con Context API?
+
+Agent:
+🔍 Detected: Informative request (question)
+
+## How State Management Works in This Project
+
+### Implementation
+
+We use Context API with custom hooks in `src/contexts/`:
+- `AuthContext.tsx` - User authentication state
+- `ThemeContext.tsx` - Theme preferences
+- `AppContext.tsx` - Global app state
+
+[Shows actual code from project]
+
+### Pattern
+```typescript
+// Example from AuthContext.tsx
+const AuthProvider: FC<Props> = ({ children }) => {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  // Context value
+  const value = { user, loading, login, logout };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+};
+````
+
+### Usage in Components
+
+```typescript
+// Any component
+const { user, login, logout } = useAuth();
 ```
 
-**IF 'n':**
+### Why Context API vs Redux?
+
+- Lighter weight for our use case
+- No external dependencies
+- Sufficient for current app complexity
+- Can migrate to Redux if state grows
+
+### Related Documentation
+
+- `docs/architecture.md` - State management patterns
+- `docs/components.md` - Component guidelines
+
+Would you like me to implement any changes to this? (Y/N): \_
 
 ```
-⏭️ Skipping push
 
-⚠️ Remember to push later:
-   git push origin [branch-name]
+**Example 2: Report Request**
+
 ```
 
----
+User: /flow-work genera un informe del tamaño del bundle
 
-### Finalization Complete
+Agent:
+🔍 Detected: Informative request (report)
 
-```
-✅ Task Finalization Complete
+## Bundle Size Report
 
-📊 Summary:
-- [✅|⚠️] Validation passed
-- [✅|⏭️] Documentation updated
-- [✅|⏭️] Task archived
-- [✅|⏭️] Ticket summary generated
-- [✅|⏭️] Pushed to remote
+[Runs bundle analysis]
 
-Task: [task-name]
-Branch: [branch-name]
-Duration: [X min]
-Commits: [N]
+### Total Bundle Size: 245 KB (gzipped: 78 KB)
 
-🎉 Great work!
-```
+| Asset      | Size   | Gzipped | % of Total |
+| ---------- | ------ | ------- | ---------- |
+| main.js    | 180 KB | 58 KB   | 73.5%      |
+| vendor.js  | 45 KB  | 15 KB   | 18.4%      |
+| styles.css | 20 KB  | 5 KB    | 8.1%       |
 
-**END WORKFLOW**
+### Largest Dependencies
 
----
+1. `react-dom` - 42 KB
+2. `axios` - 15 KB
+3. `date-fns` - 12 KB
+4. `lodash` - 8 KB (⚠️ not tree-shaken)
 
-## Orchestration Rules
+### Recommendations
 
-- **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.
+1. Use `lodash-es` for tree-shaking (saves ~6 KB)
+2. Consider lazy loading routes (saves ~30 KB initial)
+3. Move `date-fns` locales to dynamic imports
+
+### Comparison to Target
+
+- Target: <100 KB gzipped ✅
+- Current: 78 KB gzipped ✅
+- Margin: 22 KB available
+
+Would you like me to create a work plan to optimize further? (Y/N): \_
+
+```
 
 ---
 
 **BEGIN EXECUTION when user runs `/flow-work [args]`**
+```