refactor(workflows): restructure bmad-review as loop module and clean up prompts

- Convert bmad-review from step to loop module in workflow configuration
- Remove interactive improvement process from story creation prompts
- Update instructions to prevent redundant document loading
- Clean up output messages and remove unnecessary sections

Author: moazbuilds

config/main.agents.js

@@ -241,18 +241,6 @@ module.exports = [
       path.join(promptsDir, 'bmad', '07-dev', '01-dev-story', 'checklist.md'),
     ],
   },
-  {
-    id: 'bmad-review',
-    name: 'Amelia [Dev: Review]',
-    description: 'BMAD Developer for code review',
-    promptPath: [
-      path.join(promptsDir, 'bmad', 'shared', 'system-files-protection.md'),
-      path.join(promptsDir, 'bmad', '07-dev', 'amelia.md'),
-      path.join(promptsDir, 'bmad', '07-dev', '02-code-review', 'instructions.xml'),
-      path.join(promptsDir, 'bmad', '07-dev', '02-code-review', 'checklist.md'),
-    ],
-  },
-
   // Test agents
   {
     id: 'test-agent-1',

config/modules.js

@@ -3,6 +3,22 @@ const path = require('node:path');
 const promptsDir = path.join(__dirname, '..', 'prompts');
 
 module.exports = [
+  // BMAD code review module with loop behavior
+  {
+    id: 'bmad-review',
+    name: 'Amelia [Dev: Review]',
+    description: 'BMAD Developer for code review',
+    promptPath: [
+      path.join(promptsDir, 'templates', 'bmad', 'shared', 'system-files-protection.md'),
+      path.join(promptsDir, 'templates', 'bmad', '07-dev', 'amelia.md'),
+      path.join(promptsDir, 'templates', 'bmad', '07-dev', '02-code-review', 'instructions.xml'),
+      path.join(promptsDir, 'templates', 'bmad', '07-dev', '02-code-review', 'checklist.md'),
+    ],
+    behavior: {
+      type: 'loop',
+      action: 'stepBack',
+    },
+  },
   {
     id: 'check-task',
     name: 'Task Loop Checker',

prompts/templates/bmad/06-sm/02-create-story/checklist.md

@@ -6,6 +6,8 @@ You are an independent quality validator in a **FRESH CONTEXT**. Your mission is
 
 **Your purpose is NOT just to validate - it's to FIX and PREVENT LLM developer mistakes, omissions, or disasters!**
 
+> 🚫 **REMINDER:** DO NOT load/search/fetch Epics, PRD, Architecture, UX Design Spec - these are already in-memory from source_documents.
+
 ### **🚨 CRITICAL MISTAKES TO PREVENT:**
 
 - **Reinventing wheels** - Creating duplicate functionality instead of reusing existing
@@ -48,7 +50,7 @@ You will systematically re-do the entire story creation process, but with a crit
 
 #### **2.1 Epics and Stories Analysis**
 
-- Extract **COMPLETE Epic {{epic_num}} context** from the Epics document:
+- The Epics document is already loaded in-memory. Analyze for **COMPLETE Epic {{epic_num}} context**:
   - Epic objectives and business value
   - ALL stories in this epic (for cross-story context)
   - Our specific story's requirements, acceptance criteria
@@ -57,7 +59,7 @@ You will systematically re-do the entire story creation process, but with a crit
 
 #### **2.2 Architecture Deep-Dive**
 
-- **Systematically scan the Architecture document for ANYTHING relevant to this story:**
+- The Architecture document is already loaded in-memory. Analyze for **ANYTHING relevant to this story:**
   - Technical stack with versions (languages, frameworks, libraries)
   - Code structure and organization patterns
   - API design patterns and contracts
@@ -214,86 +216,6 @@ You will systematically re-do the entire story creation process, but with a crit
 
 ---
 
-## **📋 INTERACTIVE IMPROVEMENT PROCESS**
-
-After completing your systematic analysis, present your findings to the user interactively:
-
-### **Step 5: Present Improvement Suggestions**
-
-```
-🎯 **STORY CONTEXT QUALITY REVIEW COMPLETE**
-
-**Story:** {{story_key}} - {{story_title}}
-
-I found {{critical_count}} critical issues, {{enhancement_count}} enhancements, and {{optimization_count}} optimizations.
-
-## **🚨 CRITICAL ISSUES (Must Fix)**
-
-{{list each critical issue with clear, actionable description}}
-
-## **⚡ ENHANCEMENT OPPORTUNITIES (Should Add)**
-
-{{list each enhancement with clear benefit description}}
-
-## **✨ OPTIMIZATIONS (Nice to Have)**
-
-{{list each optimization with benefit description}}
-
-## **🤖 LLM OPTIMIZATION (Token Efficiency & Clarity)**
-
-{{list each LLM optimization that will improve dev agent performance:
-- Reduce verbosity while maintaining completeness
-- Improve structure for better LLM processing
-- Make instructions more actionable and direct
-- Enhance clarity and reduce ambiguity}}
-```
-
-### **Step 6: Interactive User Selection**
-
-After presenting the suggestions, ask the user:
-
-```
-**IMPROVEMENT OPTIONS:**
-
-Which improvements would you like me to apply to the story?
-
-**Select from the numbered list above, or choose:**
-- **all** - Apply all suggested improvements
-- **critical** - Apply only critical issues
-- **select** - I'll choose specific numbers
-- **none** - Keep story as-is
-- **details** - Show me more details about any suggestion
-
-Your choice:
-```
-
-### **Step 7: Apply Selected Improvements**
-
-When user accepts improvements:
-
-- **Update the story file** at `.codemachine/artifacts/stories/{{story_key}}.md`
-- **Apply accepted changes** (make them look natural, as if they were always there)
-- **DO NOT reference** the review process, original LLM, or that changes were "added" or "enhanced"
-- **Ensure clean, coherent final story** that reads as if it was created perfectly the first time
-
-### **Step 8: Confirmation**
-
-After applying changes:
-
-```
-✅ **STORY IMPROVEMENTS APPLIED**
-
-Updated {{count}} sections in `.codemachine/artifacts/stories/{{story_key}}.md`
-
-The story now includes comprehensive developer guidance to prevent common implementation issues and ensure flawless execution.
-
-**Next Steps:**
-1. Review the updated story
-2. Run `dev-story` for implementation
-```
-
----
-
 ## **💪 COMPETITIVE EXCELLENCE MINDSET**
 
 **Your goal:** Improve the story file with dev agent needed context that makes flawless implementation inevitable while being optimized for LLM developer agent consumption. Remember the dev agent will ONLY have this file to use.

prompts/templates/bmad/06-sm/02-create-story/instructions.xml

@@ -49,9 +49,8 @@
     This is the most important function in the entire development process!</critical>
   <critical>🔬 UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly
     analyze different artifacts simultaneously and thoroughly</critical>
-  <critical>❓ SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is
-    written</critical>
   <critical>🎯 ZERO USER INTERVENTION: Process is fully automated - all data is pre-injected</critical>
+  <critical>🚫 DO NOT load/search/fetch: Epics, PRD, Architecture, UX Design Spec, Story Template, Story Checklist - these are already in-memory in source_documents above</critical>
 
   <step n="1" goal="Determine target story from sprint status">
     <action>From {sprint_status}, find the FIRST story (in order) where:
@@ -227,30 +226,13 @@
     <action>Save .codemachine/artifacts/sprint-status.yaml preserving all comments and structure</action>
 
     <action>Report completion</action>
-    <output>**🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!**
+    <output>**🎯 Story Context Created**
 
       **Story Details:**
       - Story ID: {{story_id}}
       - Story Key: {{story_key}}
       - File: .codemachine/artifacts/stories/{{story_key}}.md
       - Status: ready-for-dev
-
-      **Next Steps:**
-      1. Review the comprehensive story in .codemachine/artifacts/stories/{{story_key}}.md
-      2. **Optional Quality Competition:** Run the scrum masters `*validate-create-story` to have a fresh LLM systematically review and
-      improve the story context
-      3. Run dev agents `dev-story` for optimized implementation
-      4. Run `code-review` when complete (auto-marks done)
-
-      **Quality Competition Option:** The `*validate-create-story` command runs the story context through an independent LLM in fresh
-      context that will:
-      - Systematically re-analyze all source documents
-      - Identify any misses, omissions, or improvements
-      - Compete to create a more comprehensive story context
-      - Present findings interactively for your approval
-      - Apply improvements to create the ultimate developer implementation guide
-
-      **The developer now has everything needed for flawless implementation!**
     </output>
   </step>
 

prompts/templates/bmad/07-dev/02-code-review/instructions.xml

@@ -195,4 +195,32 @@
     </output>
   </step>
 
+  <step n="6" goal="Write directive to control workflow continuation">
+    <critical>MANDATORY: Write to .codemachine/memory/directive.json to signal workflow</critical>
+
+    <check if="{{new_status}} == 'done'">
+      <action>Write to `.codemachine/memory/directive.json`:
+      ```json
+      {
+        "action": "loop",
+        "reason": "Story {{story_key}} complete - continuing to next story"
+      }
+      ```
+      </action>
+      <output>📋 Directive: loop - continuing to next story</output>
+    </check>
+
+    <check if="HIGH issues remain unfixed OR critical errors occurred">
+      <action>Write to `.codemachine/memory/directive.json`:
+      ```json
+      {
+        "action": "error",
+        "reason": "Code review failed: {{unfixed_issues_summary}}"
+      }
+      ```
+      </action>
+      <output>🛑 Directive: error - escalating to user for unresolved issues</output>
+    </check>
+  </step>
+
 </workflow>

templates/workflows/bmad.workflow.js

@@ -63,7 +63,6 @@ export default {
     separator("⟲ Story Loop ⟲"),
     resolveStep('bmad-stories', {}),
     resolveStep('bmad-dev', {}),
-    resolveStep('bmad-review', {}),
-
+    resolveModule('bmad-review', { loopSteps: 2 }),
   ],
 };

templates/workflows/test2.workflow.js

@@ -8,7 +8,7 @@ export default {
     separator("❚❚ Human Review"),
 
     // Module with conditions
-    resolveModule('auto-loop', { loopSteps: 2, loopMaxIterations: 5 }),
+    resolveModule('auto-loop', { loopSteps: 2 }),
   ],
   subAgentIds: ['frontend-dev'],
 };