ai-flow-dev 2.8.1 → 2.8.2

package/README.md

@@ -140,7 +140,7 @@ Or using uv (Python tool manager):
 uv tool install ai-flow-dev
 ```
 
-## **Current version:** 2.7.0
+## **Current version:** 2.8.2
 
 ## 🚀 Quick Start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-flow-dev",
-  "version": "2.8.1",
+  "version": "2.8.2",
   "description": "AI-powered development workflow from idea to production. Generate specs, plan features, and build with AI assistance throughout your project lifecycle.",
   "type": "module",
   "main": "dist/cli.js",

package/prompts/backend/flow-finish.md

@@ -591,9 +591,15 @@ function generate_commit_links() {
       fi
 
       if [ -n "$COMMIT_URL_PATTERN" ]; then
-        COMMIT_HASHES_SUMMARY+="[${hash}](${COMMIT_URL_PATTERN}${hash})"
+        # Build markdown link in parts to avoid VSCode link detection
+        COMMIT_HASHES_SUMMARY+="["
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+="]("
+        COMMIT_HASHES_SUMMARY+="$COMMIT_URL_PATTERN"
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+=")"
       else
-        COMMIT_HASHES_SUMMARY+="\`${hash}\`"
+        COMMIT_HASHES_SUMMARY+='`'"${hash}"'`'
       fi
     fi
     count=$((count + 1))
@@ -702,7 +708,7 @@ Read the structured summary from `/tmp/ai-context-summary.md` (400-600 words) an
 
 **AI Prompt:**
 
-```markdown
+```````markdown
 Genera dos descripciones profesionales (PR y Jira) basándote en este resumen estructurado:
 
 <context-summary>
@@ -756,55 +762,50 @@ Commit Hashes Summary: $COMMIT_HASHES_SUMMARY
 - Si breaking changes, resáltalos con ⚠️ en sección Métricas
 - Si deployment notes, sé específico con cada requirement
 
-**Output en formato (CRÍTICO - respetar delimitadores):**
+**Output Format:**
 
-\`\`\`markdown
+IMPORTANTE: Responde directamente con este formato EXACTO usando 5 BACKTICKS (máxima robustez):
 
-<!-- PR_DESCRIPTION_START -->
+---
 
-[contenido completo de PR description aquí]
+## 📋 PULL REQUEST DESCRIPTION
 
-<!-- PR_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la PR description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-<!-- JIRA_DESCRIPTION_START -->
+---
 
-[contenido completo de Jira description aquí]
+## 🎫 JIRA DESCRIPTION
 
-<!-- JIRA_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la Jira description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-\`\`\`
+---
 
-Analiza el contexto y genera las descripciones óptimas ahora.
-```
+**Listo para copiar y pegar** 📋 Solo copia el contenido dentro de los bloques de código markdown.
 
-**After AI generates the descriptions, extract and save them:**
+**CRÍTICO PARA EVITAR CONFLICTOS:**
 
-```bash
-# Extract PR description
-sed -n '/<!-- PR_DESCRIPTION_START -->/,/<!-- PR_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/pr-description.md
+1. Los encabezados "## 📋 PULL REQUEST DESCRIPTION" y "## 🎫 JIRA DESCRIPTION" deben estar FUERA de los bloques de código
+2. USA EXACTAMENTE 5 BACKTICKS (\`\`\`\`\`) para abrir/cerrar cada bloque
+3. ¿Por qué 5? Cubre hasta 4 backticks internos (bloques anidados) sin conflictos
+4. Código normal usa 3 (```), nested usa 4 (````), entonces 5 (``````) es prácticamente imposible de conflictuar
+5. Más de 5 es innecesario (over-engineering)
 
-# Extract Jira description
-sed -n '/<!-- JIRA_DESCRIPTION_START -->/,/<!-- JIRA_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/jira-description.md
+Analiza el contexto y genera las descripciones óptimas ahora.
+```````
 
-# Display descriptions
-echo ""
-echo "---"
-echo "📋 DESCRIPCIÓN PARA PULL REQUEST (GitHub/GitLab/Bitbucket)"
-echo "---"
-echo ""
-cat /tmp/pr-description.md
-echo ""
-echo ""
-echo "---"
-echo "🎫 DESCRIPCIÓN PARA JIRA/CLICKUP/LINEAR (Markdown)"
-echo "---"
-echo ""
-cat /tmp/jira-description.md
-echo ""
+**After AI generates the descriptions:**
+
+```bash
+# La IA responde directamente en el chat con las descripciones
+# en formato markdown listo para copiar y pegar.
+# No requiere post-procesamiento ni archivos temporales.
 echo ""
-echo "💡 Copia las descripciones de arriba para tus tickets"
+echo "💡 Las descripciones han sido generadas arriba en el chat."
+echo "📋 Copia directamente el contenido de los bloques markdown."
 echo ""
 ```
 

package/prompts/desktop/flow-finish.md

@@ -591,9 +591,15 @@ function generate_commit_links() {
       fi
 
       if [ -n "$COMMIT_URL_PATTERN" ]; then
-        COMMIT_HASHES_SUMMARY+="[${hash}](${COMMIT_URL_PATTERN}${hash})"
+        # Build markdown link in parts to avoid VSCode link detection
+        COMMIT_HASHES_SUMMARY+="["
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+="]("
+        COMMIT_HASHES_SUMMARY+="$COMMIT_URL_PATTERN"
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+=")"
       else
-        COMMIT_HASHES_SUMMARY+="\`${hash}\`"
+        COMMIT_HASHES_SUMMARY+='`'"${hash}"'`'
       fi
     fi
     count=$((count + 1))
@@ -702,7 +708,7 @@ Read the structured summary from `/tmp/ai-context-summary.md` (400-600 words) an
 
 **AI Prompt:**
 
-```markdown
+```````markdown
 Genera dos descripciones profesionales (PR y Jira) basándote en este resumen estructurado:
 
 <context-summary>
@@ -756,55 +762,50 @@ Commit Hashes Summary: $COMMIT_HASHES_SUMMARY
 - Si breaking changes, resáltalos con ⚠️ en sección Métricas
 - Si deployment notes, sé específico con cada requirement
 
-**Output en formato (CRÍTICO - respetar delimitadores):**
+**Output Format:**
 
-\`\`\`markdown
+IMPORTANTE: Responde directamente con este formato EXACTO usando 5 BACKTICKS (máxima robustez):
 
-<!-- PR_DESCRIPTION_START -->
+---
 
-[contenido completo de PR description aquí]
+## 📋 PULL REQUEST DESCRIPTION
 
-<!-- PR_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la PR description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-<!-- JIRA_DESCRIPTION_START -->
+---
 
-[contenido completo de Jira description aquí]
+## 🎫 JIRA DESCRIPTION
 
-<!-- JIRA_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la Jira description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-\`\`\`
+---
 
-Analiza el contexto y genera las descripciones óptimas ahora.
-```
+**Listo para copiar y pegar** 📋 Solo copia el contenido dentro de los bloques de código markdown.
 
-**After AI generates the descriptions, extract and save them:**
+**CRÍTICO PARA EVITAR CONFLICTOS:**
 
-```bash
-# Extract PR description
-sed -n '/<!-- PR_DESCRIPTION_START -->/,/<!-- PR_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/pr-description.md
+1. Los encabezados "## 📋 PULL REQUEST DESCRIPTION" y "## 🎫 JIRA DESCRIPTION" deben estar FUERA de los bloques de código
+2. USA EXACTAMENTE 5 BACKTICKS (\`\`\`\`\`) para abrir/cerrar cada bloque
+3. ¿Por qué 5? Cubre hasta 4 backticks internos (bloques anidados) sin conflictos
+4. Código normal usa 3 (```), nested usa 4 (````), entonces 5 (``````) es prácticamente imposible de conflictuar
+5. Más de 5 es innecesario (over-engineering)
 
-# Extract Jira description
-sed -n '/<!-- JIRA_DESCRIPTION_START -->/,/<!-- JIRA_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/jira-description.md
+Analiza el contexto y genera las descripciones óptimas ahora.
+```````
 
-# Display descriptions
-echo ""
-echo "---"
-echo "📋 DESCRIPCIÓN PARA PULL REQUEST (GitHub/GitLab/Bitbucket)"
-echo "---"
-echo ""
-cat /tmp/pr-description.md
-echo ""
-echo ""
-echo "---"
-echo "🎫 DESCRIPCIÓN PARA JIRA/CLICKUP/LINEAR (Markdown)"
-echo "---"
-echo ""
-cat /tmp/jira-description.md
-echo ""
+**After AI generates the descriptions:**
+
+```bash
+# La IA responde directamente en el chat con las descripciones
+# en formato markdown listo para copiar y pegar.
+# No requiere post-procesamiento ni archivos temporales.
 echo ""
-echo "💡 Copia las descripciones de arriba para tus tickets"
+echo "💡 Las descripciones han sido generadas arriba en el chat."
+echo "📋 Copia directamente el contenido de los bloques markdown."
 echo ""
 ```
 

package/prompts/frontend/flow-finish.md

@@ -591,9 +591,15 @@ function generate_commit_links() {
       fi
 
       if [ -n "$COMMIT_URL_PATTERN" ]; then
-        COMMIT_HASHES_SUMMARY+="[${hash}](${COMMIT_URL_PATTERN}${hash})"
+        # Build markdown link in parts to avoid VSCode link detection
+        COMMIT_HASHES_SUMMARY+="["
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+="]("
+        COMMIT_HASHES_SUMMARY+="$COMMIT_URL_PATTERN"
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+=")"
       else
-        COMMIT_HASHES_SUMMARY+="\`${hash}\`"
+        COMMIT_HASHES_SUMMARY+='`'"${hash}"'`'
       fi
     fi
     count=$((count + 1))
@@ -702,7 +708,7 @@ Read the structured summary from `/tmp/ai-context-summary.md` (400-600 words) an
 
 **AI Prompt:**
 
-```markdown
+```````markdown
 Genera dos descripciones profesionales (PR y Jira) basándote en este resumen estructurado:
 
 <context-summary>
@@ -756,55 +762,50 @@ Commit Hashes Summary: $COMMIT_HASHES_SUMMARY
 - Si breaking changes, resáltalos con ⚠️ en sección Métricas
 - Si deployment notes, sé específico con cada requirement
 
-**Output en formato (CRÍTICO - respetar delimitadores):**
+**Output Format:**
 
-\`\`\`markdown
+IMPORTANTE: Responde directamente con este formato EXACTO usando 5 BACKTICKS (máxima robustez):
 
-<!-- PR_DESCRIPTION_START -->
+---
 
-[contenido completo de PR description aquí]
+## 📋 PULL REQUEST DESCRIPTION
 
-<!-- PR_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la PR description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-<!-- JIRA_DESCRIPTION_START -->
+---
 
-[contenido completo de Jira description aquí]
+## 🎫 JIRA DESCRIPTION
 
-<!-- JIRA_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la Jira description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-\`\`\`
+---
 
-Analiza el contexto y genera las descripciones óptimas ahora.
-```
+**Listo para copiar y pegar** 📋 Solo copia el contenido dentro de los bloques de código markdown.
 
-**After AI generates the descriptions, extract and save them:**
+**CRÍTICO PARA EVITAR CONFLICTOS:**
 
-```bash
-# Extract PR description
-sed -n '/<!-- PR_DESCRIPTION_START -->/,/<!-- PR_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/pr-description.md
+1. Los encabezados "## 📋 PULL REQUEST DESCRIPTION" y "## 🎫 JIRA DESCRIPTION" deben estar FUERA de los bloques de código
+2. USA EXACTAMENTE 5 BACKTICKS (\`\`\`\`\`) para abrir/cerrar cada bloque
+3. ¿Por qué 5? Cubre hasta 4 backticks internos (bloques anidados) sin conflictos
+4. Código normal usa 3 (```), nested usa 4 (````), entonces 5 (``````) es prácticamente imposible de conflictuar
+5. Más de 5 es innecesario (over-engineering)
 
-# Extract Jira description
-sed -n '/<!-- JIRA_DESCRIPTION_START -->/,/<!-- JIRA_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/jira-description.md
+Analiza el contexto y genera las descripciones óptimas ahora.
+```````
 
-# Display descriptions
-echo ""
-echo "---"
-echo "📋 DESCRIPCIÓN PARA PULL REQUEST (GitHub/GitLab/Bitbucket)"
-echo "---"
-echo ""
-cat /tmp/pr-description.md
-echo ""
-echo ""
-echo "---"
-echo "🎫 DESCRIPCIÓN PARA JIRA/CLICKUP/LINEAR (Markdown)"
-echo "---"
-echo ""
-cat /tmp/jira-description.md
-echo ""
+**After AI generates the descriptions:**
+
+```bash
+# La IA responde directamente en el chat con las descripciones
+# en formato markdown listo para copiar y pegar.
+# No requiere post-procesamiento ni archivos temporales.
 echo ""
-echo "💡 Copia las descripciones de arriba para tus tickets"
+echo "💡 Las descripciones han sido generadas arriba en el chat."
+echo "📋 Copia directamente el contenido de los bloques markdown."
 echo ""
 ```
 

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

@@ -43,12 +43,14 @@ Parse OpenAPI backend specification and return structured analysis data that `fl
 2. Execute CRUD implementation with project-specific patterns
 3. Ensure type-safety between frontend and backend
 
-**⚠️ CRITICAL: Do NOT create separate analysis files**
+**⚠️ CRITICAL: Do NOT create ANY files in this sub-prompt**
 
 - This sub-prompt ONLY returns a JSON object (`OpenAPIAnalysisResult`)
-- NO files like `.ai-flow/analysis/*.md` or `.ai-flow/work/[task]/analysis.md` should be created
-- The parent prompt (`flow-work`) handles all file creation (only `work.md` and `status.json`)
-- All analysis data is stored in memory and used to populate `work.md`
+- ❌ NO files like `.ai-flow/analysis/*.md` should be created
+- ❌ NO files like `.ai-flow/work/[task]/analysis.md` should be created
+- ❌ NO files like `.ai-flow/work/[task]/work.md` should be created here
+- ✅ The parent prompt (`flow-work`) will create `.ai-flow/work/[task]/work.md` and `status.json` in Phase 2
+- All analysis data is returned as JSON and will be embedded into `work.md` by the parent prompt
 
 ---
 

package/prompts/frontend/flow-work.md

@@ -492,10 +492,14 @@ await saveToCache(cacheFile, {
   projectType: 'frontend',
 });
 
-// ⚠️ IMPORTANT: Do NOT create separate analysis files
+// ⚠️ IMPORTANT: Do NOT create SEPARATE ANALYSIS FILES
 // The analysis result is stored in memory (workflow_context.analysis)
-// and will be used to generate the comprehensive work.md file.
-// NO files like .ai-flow/analysis/*.md or .ai-flow/work/[task]/analysis.md
+// and will be merged into work.md during Phase 2.
+//
+// ❌ DO NOT CREATE: .ai-flow/analysis/*.md or .ai-flow/work/[task]/analysis.md
+// ✅ MUST CREATE (in Phase 2): .ai-flow/work/[task]/work.md and status.json
+//
+// The analysis data is included INSIDE work.md, not as a separate file.
 ```
 
 **IF `analysisResult.success === false`:**
@@ -890,7 +894,15 @@ Find similar features/patterns in codebase:
 - The `work.md` file should be comprehensive and self-contained
 - For COMPLEX tasks with API analysis, include all OpenAPI metadata directly in `work.md`
 
-**IF complexity == "MEDIUM":**
+**📦 For API_MODULE mode specifically:**
+
+- The analysis from `flow-work-api.md` sub-prompt is stored in `workflow_context.analysis`
+- ✅ YOU MUST CREATE `.ai-flow/work/api-[module-name]/work.md` with all analysis data embedded
+- ✅ YOU MUST CREATE `.ai-flow/work/api-[module-name]/status.json` (API modules are COMPLEX)
+- Include OpenAPI endpoints, schemas, field specs, validation rules, and relationships in `work.md`
+- Do NOT skip file creation just because you received pre-analyzed data
+
+**IF complexity == "MEDIUM":\*\***
 
 - Create simplified `.ai-flow/work/[task-name]/work.md` (~15-20 lines)
 - Skip status.json

package/prompts/mobile/flow-finish.md

@@ -591,9 +591,15 @@ function generate_commit_links() {
       fi
 
       if [ -n "$COMMIT_URL_PATTERN" ]; then
-        COMMIT_HASHES_SUMMARY+="[${hash}](${COMMIT_URL_PATTERN}${hash})"
+        # Build markdown link in parts to avoid VSCode link detection
+        COMMIT_HASHES_SUMMARY+="["
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+="]("
+        COMMIT_HASHES_SUMMARY+="$COMMIT_URL_PATTERN"
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+=")"
       else
-        COMMIT_HASHES_SUMMARY+="\`${hash}\`"
+        COMMIT_HASHES_SUMMARY+='`'"${hash}"'`'
       fi
     fi
     count=$((count + 1))
@@ -702,7 +708,7 @@ Read the structured summary from `/tmp/ai-context-summary.md` (400-600 words) an
 
 **AI Prompt:**
 
-```markdown
+```````markdown
 Genera dos descripciones profesionales (PR y Jira) basándote en este resumen estructurado:
 
 <context-summary>
@@ -756,55 +762,50 @@ Commit Hashes Summary: $COMMIT_HASHES_SUMMARY
 - Si breaking changes, resáltalos con ⚠️ en sección Métricas
 - Si deployment notes, sé específico con cada requirement
 
-**Output en formato (CRÍTICO - respetar delimitadores):**
+**Output Format:**
 
-\`\`\`markdown
+IMPORTANTE: Responde directamente con este formato EXACTO usando 5 BACKTICKS (máxima robustez):
 
-<!-- PR_DESCRIPTION_START -->
+---
 
-[contenido completo de PR description aquí]
+## 📋 PULL REQUEST DESCRIPTION
 
-<!-- PR_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la PR description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-<!-- JIRA_DESCRIPTION_START -->
+---
 
-[contenido completo de Jira description aquí]
+## 🎫 JIRA DESCRIPTION
 
-<!-- JIRA_DESCRIPTION_END -->
+\`\`\`\`\`markdown
+[Aquí va el contenido completo de la Jira description, empezando con ## Refactor: ...]
+\`\`\`\`\`
 
-\`\`\`
+---
 
-Analiza el contexto y genera las descripciones óptimas ahora.
-```
+**Listo para copiar y pegar** 📋 Solo copia el contenido dentro de los bloques de código markdown.
 
-**After AI generates the descriptions, extract and save them:**
+**CRÍTICO PARA EVITAR CONFLICTOS:**
 
-```bash
-# Extract PR description
-sed -n '/<!-- PR_DESCRIPTION_START -->/,/<!-- PR_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/pr-description.md
+1. Los encabezados "## 📋 PULL REQUEST DESCRIPTION" y "## 🎫 JIRA DESCRIPTION" deben estar FUERA de los bloques de código
+2. USA EXACTAMENTE 5 BACKTICKS (\`\`\`\`\`) para abrir/cerrar cada bloque
+3. ¿Por qué 5? Cubre hasta 4 backticks internos (bloques anidados) sin conflictos
+4. Código normal usa 3 (```), nested usa 4 (````), entonces 5 (``````) es prácticamente imposible de conflictuar
+5. Más de 5 es innecesario (over-engineering)
 
-# Extract Jira description
-sed -n '/<!-- JIRA_DESCRIPTION_START -->/,/<!-- JIRA_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/jira-description.md
+Analiza el contexto y genera las descripciones óptimas ahora.
+```````
 
-# Display descriptions
-echo ""
-echo "---"
-echo "📋 DESCRIPCIÓN PARA PULL REQUEST (GitHub/GitLab/Bitbucket)"
-echo "---"
-echo ""
-cat /tmp/pr-description.md
-echo ""
-echo ""
-echo "---"
-echo "🎫 DESCRIPCIÓN PARA JIRA/CLICKUP/LINEAR (Markdown)"
-echo "---"
-echo ""
-cat /tmp/jira-description.md
-echo ""
+**After AI generates the descriptions:**
+
+```bash
+# La IA responde directamente en el chat con las descripciones
+# en formato markdown listo para copiar y pegar.
+# No requiere post-procesamiento ni archivos temporales.
 echo ""
-echo "💡 Copia las descripciones de arriba para tus tickets"
+echo "💡 Las descripciones han sido generadas arriba en el chat."
+echo "📋 Copia directamente el contenido de los bloques markdown."
 echo ""
 ```
 

package/prompts/mobile/flow-work-api.md

@@ -43,12 +43,14 @@ Parse OpenAPI backend specification and return structured analysis data that `fl
 2. Execute CRUD implementation with mobile-specific patterns (React Native)
 3. Ensure type-safety between mobile app and backend
 
-**⚠️ CRITICAL: Do NOT create separate analysis files**
+**⚠️ CRITICAL: Do NOT create ANY files in this sub-prompt**
 
 - This sub-prompt ONLY returns a JSON object (`OpenAPIAnalysisResult`)
-- NO files like `.ai-flow/analysis/*.md` or `.ai-flow/work/[task]/analysis.md` should be created
-- The parent prompt (`flow-work`) handles all file creation (only `work.md` and `status.json`)
-- All analysis data is stored in memory and used to populate `work.md`
+- ❌ NO files like `.ai-flow/analysis/*.md` should be created
+- ❌ NO files like `.ai-flow/work/[task]/analysis.md` should be created
+- ❌ NO files like `.ai-flow/work/[task]/work.md` should be created here
+- ✅ The parent prompt (`flow-work`) will create `.ai-flow/work/[task]/work.md` and `status.json` in Phase 2
+- All analysis data is returned as JSON and will be embedded into `work.md` by the parent prompt
 
 ---
 

package/prompts/mobile/flow-work.md

@@ -492,10 +492,14 @@ await saveToCache(cacheFile, {
   projectType: 'mobile',
 });
 
-// ⚠️ IMPORTANT: Do NOT create separate analysis files
+// ⚠️ IMPORTANT: Do NOT create SEPARATE ANALYSIS FILES
 // The analysis result is stored in memory (workflow_context.analysis)
-// and will be used to generate the comprehensive work.md file.
-// NO files like .ai-flow/analysis/*.md or .ai-flow/work/[task]/analysis.md
+// and will be merged into work.md during Phase 2.
+//
+// ❌ DO NOT CREATE: .ai-flow/analysis/*.md or .ai-flow/work/[task]/analysis.md
+// ✅ MUST CREATE (in Phase 2): .ai-flow/work/[task]/work.md and status.json
+//
+// The analysis data is included INSIDE work.md, not as a separate file.
 ```
 
 **IF `analysisResult.success === false`:**
@@ -887,7 +891,15 @@ Find similar features/patterns in codebase:
 - The `work.md` file should be comprehensive and self-contained
 - For COMPLEX tasks with API analysis, include all OpenAPI metadata directly in `work.md`
 
-**IF complexity == "MEDIUM":\*\***
+**📦 For API_MODULE mode specifically:**
+
+- The analysis from `flow-work-api.md` sub-prompt is stored in `workflow_context.analysis`
+- ✅ YOU MUST CREATE `.ai-flow/work/api-[module-name]/work.md` with all analysis data embedded
+- ✅ YOU MUST CREATE `.ai-flow/work/api-[module-name]/status.json` (API modules are COMPLEX)
+- Include OpenAPI endpoints, schemas, field specs, validation rules, and relationships in `work.md`
+- Do NOT skip file creation just because you received pre-analyzed data
+
+**IF complexity == "MEDIUM":**\*\*\*\*
 
 - Create simplified `.ai-flow/work/[task-name]/work.md` (~15-20 lines)
 - Skip status.json