Merge a88bb43eba into 572074d2a6

fix(bmm): normalize dev-story trigger naming

src/core/tasks/workflow.xml

@@ -63,6 +63,8 @@
           <tag>invoke-workflow xml tag → Execute another workflow with given inputs and the workflow.xml runner</tag>
           <tag>invoke-task xml tag → Execute specified task</tag>
           <tag>invoke-protocol name="protocol_name" xml tag → Execute reusable protocol from protocols section</tag>
+          <tag>invoke-bash cmd="command" → Execute shell command, capture stdout/stderr, set {{bash_exit_code}}, {{bash_stdout}}, {{bash_stderr}}</tag>
+          <tag>set-var name="varname" value="..." → Set runtime variable {{varname}} to specified value (supports expressions)</tag>
           <tag>goto step="x" → Jump to specified step</tag>
         </execute-tags>
       </substep>
@@ -126,6 +128,8 @@
       <tag>invoke-workflow - Call another workflow</tag>
       <tag>invoke-task - Call a task</tag>
       <tag>invoke-protocol - Execute a reusable protocol (e.g., discover_inputs)</tag>
+      <tag>invoke-bash cmd="..." - Execute shell command, results in {{bash_exit_code}}, {{bash_stdout}}, {{bash_stderr}}</tag>
+      <tag>set-var name="..." value="..." - Set runtime variable dynamically</tag>
     </execution>
     <output>
       <tag>template-output - Save content checkpoint</tag>

src/modules/bmgd/agents/game-dev.agent.yaml

@@ -16,7 +16,7 @@ agent:
       - 60fps is non-negotiable. Write code designers can iterate without fear. Ship early, ship often, iterate on player feedback.
 
   menu:
-    - trigger: develop-story
+    - trigger: dev-story
       workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml"
       workflow-install: "{project-root}/.bmad/bmgd/workflows/4-production/dev-story/workflow.yaml"
       description: "Execute Dev Story workflow, implementing tasks and tests, or performing updates to the story"

src/modules/bmm/README.md

@@ -93,7 +93,7 @@ BMM automatically adjusts to project complexity (Levels 0-4):
 
 ### Story-Centric Implementation
 
-Stories move through a defined lifecycle: `backlog → drafted → ready → in-progress → review → done`
+Stories move through a defined lifecycle: `backlog → ready-for-dev → in-progress → review → done`
 
 Just-in-time epic context and story context provide exact expertise when needed.
 

src/modules/bmm/agents/dev.agent.yaml

@@ -35,7 +35,7 @@ agent:
     - "NEVER lie about tests being written or passing - tests must actually exist and pass 100%"
 
   menu:
-    - trigger: develop-story
+    - trigger: dev-story
       workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml"
       description: "Execute Dev Story workflow (full BMM path with sprint-status)"
 

src/modules/bmm/agents/sm.agent.yaml

@@ -30,11 +30,11 @@ agent:
 
     - trigger: create-story
       workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
-      description: Create a Draft Story (Required to prepare stories for development)
+      description: Create Story (Required to prepare stories for development)
 
     - trigger: validate-create-story
       validate-workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
-      description: Validate Story Draft (Highly Recommended, use fresh context and different LLM for best results)
+      description: Validate Story (Highly Recommended, use fresh context and different LLM for best results)
 
     - trigger: epic-retrospective
       workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml"

src/modules/bmm/docs/agents-guide.md

@@ -180,11 +180,13 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 
 - `workflow-status` - Check what to do next
 - `sprint-planning` - Initialize `sprint-status.yaml` tracking
-- `create-story` - Draft next story from epic
-- `validate-create-story` - Independent story validation
+- `create-story` - Create next story from epic (sets status to `ready-for-dev`)
+- `validate-create-story` - Optional quality check (does not change status; run before dev-story for extra validation)
 - `epic-retrospective` - Post-epic review
 - `correct-course` - Handle changes during implementation
 
+**Story handoff sequence:** `create-story` → (optional) `validate-create-story` → `dev-story`
+
 **Communication Style:** Task-oriented and efficient. Direct and eliminates ambiguity. Focuses on clear handoffs and developer-ready specifications.
 
 **Expertise:**
@@ -212,7 +214,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 **Workflows:**
 
 - `workflow-status` - Check what to do next
-- `develop-story` - Implement story with:
+- `dev-story` - Implement story with:
   - Task-by-task iteration
   - Test-driven development
   - Multi-run capability (initial + fixes)
@@ -449,7 +451,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 **Workflows:**
 
 - `workflow-status` - Check what to do next
-- `develop-story` - Execute Dev Story workflow, implementing tasks and tests
+- `dev-story` - Execute Dev Story workflow, implementing tasks and tests
 - `code-review` - Perform thorough clean context QA code review on a story
 
 **Communication Style:** Direct and energetic. Execution-focused. Breaks down complex game challenges into actionable steps. Celebrates performance wins.
@@ -644,7 +646,7 @@ Many workflows have optional validation workflows that perform independent revie
 | -------------------------- | ----------- | ------------------------------------------ |
 | `implementation-readiness` | Architect   | PRD + Architecture + Epics + UX (optional) |
 | `validate-design`          | UX Designer | UX specification and artifacts             |
-| `validate-create-story`    | SM          | Story draft                                |
+| `validate-create-story`    | SM          | Story file                                 |
 
 **When to use validation:**
 
@@ -900,7 +902,7 @@ Load the customized agent and verify the changes are reflected in its behavior a
 
 ```
 1. SM: *create-story
-2. DEV: *develop-story
+2. DEV: *dev-story
 3. DEV: *code-review
 4. Repeat steps 1-3 for next story
 ```
@@ -910,7 +912,7 @@ Load the customized agent and verify the changes are reflected in its behavior a
 ```
 1. TEA: *framework (once per project, early)
 2. TEA: *atdd (before implementing features)
-3. DEV: *develop-story (includes tests)
+3. DEV: *dev-story (includes tests)
 4. TEA: *automate (comprehensive test suite)
 5. TEA: *trace (quality gate)
 6. TEA: *ci (pipeline setup)
@@ -975,12 +977,12 @@ Quick reference for agent selection:
 | **UX Designer**         | 🎨   | 2 (Planning)            | create-ux-design, validate-design             | UX-heavy projects, design               |
 | **Architect**           | 🏗️   | 3 (Solutioning)         | architecture, implementation-readiness        | Technical design, architecture          |
 | **SM**                  | 🏃   | 4 (Implementation)      | sprint-planning, create-story                 | Story management, sprint coordination   |
-| **DEV**                 | 💻   | 4 (Implementation)      | develop-story, code-review                    | Implementation, coding                  |
+| **DEV**                 | 💻   | 4 (Implementation)      | dev-story, code-review                        | Implementation, coding                  |
 | **TEA**                 | 🧪   | All Phases              | framework, atdd, automate, trace, ci          | Testing, quality assurance              |
 | **Paige (Tech Writer)** | 📚   | All Phases              | document-project, diagrams, validation        | Documentation, diagrams                 |
 | **Principal Engineer**  | ⚡   | Quick Flow (All phases) | create-tech-spec, quick-dev, code-review      | Rapid development, technical leadership |
 | **Game Designer**       | 🎲   | 1-2 (Games)             | brainstorm-game, gdd, narrative               | Game design, creative vision            |
-| **Game Developer**      | 🕹️   | 4 (Games)               | develop-story, code-review                    | Game implementation                     |
+| **Game Developer**      | 🕹️   | 4 (Games)               | dev-story, code-review                        | Game implementation                     |
 | **Game Architect**      | 🏛️   | 3 (Games)               | architecture, implementation-readiness        | Game systems architecture               |
 | **BMad Master**         | 🧙   | Meta                    | party-mode, list tasks/workflows              | Orchestration, multi-agent              |
 
@@ -1070,7 +1072,7 @@ Quick reference for agent selection:
 
 - [ ] SM: `*sprint-planning` (once)
 - [ ] SM: `*create-story`
-- [ ] DEV: `*develop-story`
+- [ ] DEV: `*dev-story`
 - [ ] DEV: `*code-review`
 
 **Testing Strategy:**

src/modules/bmm/docs/brownfield-guide.md

@@ -340,7 +340,7 @@ flowchart TD
 **Status Progression:**
 
 - Epic: `backlog → in-progress → done`
-- Story: `backlog → drafted → ready-for-dev → in-progress → review → done`
+- Story: `backlog → ready-for-dev → in-progress → review → done`
 
 **Brownfield-Specific Implementation Tips:**
 
@@ -397,7 +397,7 @@ Document in tech-spec/architecture:
 ### 8. Use Sprint Planning Effectively
 
 - Run `sprint-planning` at Phase 4 start
-- Context epics before drafting stories
+- Context epics before creating stories
 - Update `sprint-status.yaml` as work progresses
 
 ### 9. Learn Continuously

src/modules/bmm/docs/glossary.md

@@ -186,12 +186,11 @@ Multi-agent collaboration feature where all installed agents (19+ from BMM, CIS,
 ### Story Status Progression
 
 ```
-backlog → drafted → ready-for-dev → in-progress → review → done
+backlog → ready-for-dev → in-progress → review → done
 ```
 
-- **backlog** - Story exists in epic but not yet drafted
-- **drafted** - Story file created by SM via create-story
-- **ready-for-dev** - Story drafted and reviewed, ready for DEV
+- **backlog** - Story exists in epic but not yet created
+- **ready-for-dev** - Story file created via create-story; validation is optional (run `validate-create-story` for quality check before dev picks it up)
 - **in-progress** - DEV is implementing via dev-story
 - **review** - Implementation complete, awaiting code-review
 - **done** - Completed with DoD met

src/modules/bmm/docs/quick-start.md

@@ -200,12 +200,12 @@ Once planning and architecture are complete, you'll move to Phase 4. **Important
 3. Tell the agent: "Run sprint-planning"
 4. This creates your `sprint-status.yaml` file that tracks all epics and stories
 
-#### 3.2 Draft Your First Story
+#### 3.2 Create Your First Story
 
 1. **Start a new chat** with the **SM agent**
 2. Wait for the menu
 3. Tell the agent: "Run create-story"
-4. This drafts the story file from the epic
+4. This creates the story file from the epic
 
 #### 3.3 Implement the Story
 

src/modules/bmm/module.yaml

@@ -51,3 +51,23 @@ tea_use_playwright_utils:
     - "You must install packages yourself, or use test architect's *framework command."
   default: false
   result: "{value}"
+
+# External Code Review Agent Selection
+# Allows delegating code reviews to an external AI agent CLI for independent, unbiased reviews
+# Useful when using a different AI as primary IDE agent (e.g., Codex/Gemini users can use Claude for reviews)
+external_review_agent:
+  prompt:
+    - "Which external agent should perform code reviews?"
+    - "External agents provide independent, unbiased reviews separate from your primary IDE agent."
+    - "The selected CLI must be installed and configured on your system."
+  default: "none"
+  result: "{value}"
+  single-select:
+    - value: "codex"
+      label: "Codex (OpenAI) - Code review using OpenAI Codex CLI"
+    - value: "gemini"
+      label: "Gemini (Google) - Code review using Google Gemini CLI"
+    - value: "claude"
+      label: "Claude Code (Anthropic) - Code review using Claude Code CLI"
+    - value: "none"
+      label: "None - Use built-in review (no external agent)"

src/modules/bmm/tasks/daily-standup.xml

@@ -10,7 +10,7 @@
     <step n="1" title="Project Context Discovery">
       <action>Check for stories folder at {project-root}{output_folder}/stories/</action>
       <action>Find current story by identifying highest numbered story file</action>
-      <action>Read story status (In Progress, Ready for Review, etc.)</action>
+      <action>Read story status (in-progress, review, etc.)</action>
       <action>Extract agent notes from Dev Agent Record, TEA Results, PO Notes sections</action>
       <action>Check for next story references from epics</action>
       <action>Identify blockers from story sections</action>

src/modules/bmm/workflows/4-implementation/code-review/checklist.md

@@ -1,5 +1,7 @@
 # Senior Developer Review - Validation Checklist
 
+## Story Setup
+
 - [ ] Story file loaded from `{{story_path}}`
 - [ ] Story Status verified as reviewable (review)
 - [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
@@ -7,12 +9,33 @@
 - [ ] Epic Tech Spec located or warning recorded
 - [ ] Architecture/standards docs loaded (as available)
 - [ ] Tech stack detected and documented
-- [ ] MCP doc search performed (or web fallback) and references captured
+
+## External Agent Detection (Runtime)
+
+- [ ] `invoke-bash cmd="command -v codex"` executed → {{codex_available}}
+- [ ] `invoke-bash cmd="command -v gemini"` executed → {{gemini_available}}
+- [ ] `invoke-bash cmd="command -v claude"` executed → {{claude_available}}
+- [ ] Review method determined: {{use_external_agent}} = true/false
+- [ ] If external: {{external_agent_cmd}} = codex OR gemini OR claude
+- [ ] Config updated with detection results and timestamp
+
+## Code Review Execution
+
+- [ ] Git vs Story discrepancies identified ({{git_findings}})
+- [ ] If external agent available: Prompt written to /tmp/code-review-prompt.txt
+- [ ] If external agent available: CLI invoked via `invoke-bash` (MANDATORY - NO EXCEPTIONS)
+- [ ] External agent output captured in {{bash_stdout}}
+- [ ] If external agent CLI failed (non-zero exit): Fallback to built-in review
+- [ ] ⚠️ VIOLATION CHECK: Did you skip external agent with a rationalization? If yes, RE-RUN with external agent.
 - [ ] Acceptance Criteria cross-checked against implementation
 - [ ] File List reviewed and validated for completeness
 - [ ] Tests identified and mapped to ACs; gaps noted
-- [ ] Code quality review performed on changed files
-- [ ] Security review performed on changed files and dependencies
+- [ ] Code quality review performed (security, performance, maintainability)
+- [ ] Minimum 3 issues found (adversarial review requirement)
+
+## Finalization
+
+- [ ] Findings categorized: HIGH/MEDIUM/LOW severity
 - [ ] Outcome decided (Approve/Changes Requested/Blocked)
 - [ ] Review notes appended under "Senior Developer Review (AI)"
 - [ ] Change Log updated with review entry
@@ -21,3 +44,4 @@
 - [ ] Story saved successfully
 
 _Reviewer: {{user_name}} on {{date}}_
+_External Agent: {{external_agent_cmd}} (codex:{{codex_available}} / gemini:{{gemini_available}} / claude:{{claude_available}})_

src/modules/bmm/workflows/4-implementation/code-review/external-agent-prompt.md

@@ -0,0 +1,35 @@
+You are an ADVERSARIAL code reviewer. Your job is to find problems, not approve code.
+
+VERY IMPORTANT!
+
+- This is a READ ONLY operation. You are not to change anything in this code.
+- You are FORBIDDEN to write to any files.
+- You are FORBIDDEN to change any files.
+- You are FORBIDDEN to delete any files.
+
+REQUIREMENTS:
+
+- Find 3-10 specific issues minimum - no lazy looks good reviews
+- Categorize as HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)
+- For each issue: specify file:line, describe problem, suggest fix
+- Check: Security vulnerabilities, performance issues, error handling, test quality
+- Verify: Tasks marked [x] are actually done, ACs are actually implemented
+
+STORY CONTEXT: {{story_path}}
+FILES TO REVIEW: {{comprehensive_file_list}}
+ACCEPTANCE CRITERIA: {{acceptance_criteria_list}}
+TASKS: {{task_list}}
+
+OUTPUT FORMAT:
+
+## HIGH SEVERITY
+
+- [file:line] Issue description | Suggested fix
+
+## MEDIUM SEVERITY
+
+- [file:line] Issue description | Suggested fix
+
+## LOW SEVERITY
+
+- [file:line] Issue description | Suggested fix

src/modules/bmm/workflows/4-implementation/code-review/instructions.xml

@@ -4,16 +4,56 @@
   <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
   <critical>Generate all documents in {document_output_language}</critical>
 
-  <critical>🔥 YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! 🔥</critical>
+  <!-- ================================================================ -->
+  <!-- CLAUDE CODE CLEANUP - MANDATORY KILL OF ALL BACKGROUND SHELLS   -->
+  <!-- ================================================================ -->
+  <!-- CRITICAL: Stale external agent processes cause context pollution.
+       You MUST kill ALL background shells BEFORE doing ANYTHING else.
+       DO NOT read their output. DO NOT check what they're doing.
+       Just KILL them unconditionally. -->
+  <critical>🚨 FIRST ACTION REQUIRED: Kill all background shells 🚨</critical>
+  <critical>Before ANY other workflow step, you MUST terminate all background processes.</critical>
+  <critical>DO NOT use BashOutput to read from stale shells - this causes context pollution.</critical>
+  <critical>DO NOT try to "check what they're doing" - just kill them.</critical>
+
+  <check if="BMAD is running as Claude Code (KillShell tool is available)">
+    <action>IMMEDIATELY use KillShell to terminate ALL background shells - no exceptions</action>
+    <action>Do NOT read output from these shells first - kill them blind</action>
+    <action>Do NOT rationalize keeping them alive - they contain stale data</action>
+    <action>If multiple shells exist, kill ALL of them one by one</action>
+    <output>🔪 Killed all background shells to prevent stale data contamination</output>
+  </check>
+  <critical>Only proceed to Step 1 AFTER all background shells are terminated.</critical>
+
+  <!-- ================================================================ -->
+  <!-- EXTERNAL AGENT MANDATE - THIS IS THE MOST IMPORTANT RULE        -->
+  <!-- ================================================================ -->
+  <critical>🚨 MANDATORY EXTERNAL AGENT RULE - NO EXCEPTIONS 🚨</critical>
+  <critical>If an external agent CLI (codex, gemini, or claude) is detected as available, you MUST delegate the code review to that agent.</critical>
+  <critical>You are FORBIDDEN from performing your own code review analysis if an external agent is available.</critical>
+  <critical>The external agent provides an independent, unbiased review. Your job is to INVOKE it, not replace it.</critical>
+  <critical>Only perform built-in review if ALL external agents fail detection OR the CLI invocation actually fails with a non-zero exit code.</critical>
+  <critical>DO NOT SKIP the invoke-bash commands for detection and invocation - they are MANDATORY.</critical>
+
+  <!-- PROHIBITED EXCUSES - DO NOT USE THESE TO SKIP EXTERNAL AGENT -->
+  <critical>🚫 PROHIBITED RATIONALIZATIONS - You may NOT skip the external agent for ANY of these reasons:</critical>
+  <critical>❌ "The prompt is too long" - Long prompts are expected and supported. Invoke anyway.</critical>
+  <critical>❌ "CLI is meant for simple operations" - FALSE. The CLI handles complex prompts. Invoke anyway.</critical>
+  <critical>❌ "This is a re-review" - Re-reviews MUST use external agent. No exception.</critical>
+  <critical>❌ "I can do this myself" - You are FORBIDDEN from self-review when external agent is available.</critical>
+  <critical>❌ "It would be faster/better if I do it" - Irrelevant. External agent is MANDATORY.</critical>
+  <critical>❌ "The context is too complex" - The external agent handles complexity. Invoke anyway.</critical>
+  <critical>If you find yourself rationalizing why to skip the external agent, STOP and invoke it anyway.</critical>
+
+  <critical>🔥 ADVERSARIAL CODE REVIEW REQUIREMENTS 🔥</critical>
   <critical>Your purpose: Validate story file claims against actual implementation</critical>
   <critical>Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?</critical>
-  <critical>Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews - YOU are so much better than the dev agent
-    that wrote this slop</critical>
+  <critical>Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews</critical>
   <critical>Read EVERY file in the File List - verify implementation against story requirements</critical>
   <critical>Tasks marked complete but not done = CRITICAL finding</critical>
   <critical>Acceptance Criteria not implemented = HIGH severity finding</critical>
 
-  <step n="1" goal="Load story and discover changes">
+  <step n="1" goal="Load story and detect external agents">
     <action>Use provided {{story_path}} or ask user which story file to review</action>
     <action>Read COMPLETE story file</action>
     <action>Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story metadata</action>
@@ -38,6 +78,86 @@
 
     <invoke-protocol name="discover_inputs" />
     <action>Load {project_context} for coding standards (if exists)</action>
+
+    <!-- ============================================================== -->
+    <!-- EXTERNAL AGENT DETECTION - CHECK CONFIG FIRST, THEN DETECT     -->
+    <!-- ============================================================== -->
+    <set-var name="use_external_agent" value="false" />
+    <set-var name="external_agent_cmd" value="" />
+    <set-var name="codex_available" value="false" />
+    <set-var name="gemini_available" value="false" />
+    <set-var name="claude_available" value="false" />
+    <set-var name="external_agent_failed" value="false" />
+    <set-var name="preferred_agent" value="{external_review_agent}" />
+
+    <!-- Check if user has disabled external agents -->
+    <check if="{{preferred_agent}} == 'none'">
+      <output>📋 External agent disabled in config - will use built-in adversarial review</output>
+    </check>
+
+    <!-- Only detect and use external agents if not set to "none" -->
+    <check if="{{preferred_agent}} != 'none'">
+      <output>🔍 Detecting external agent availability...</output>
+
+      <!-- Detect Codex CLI availability -->
+      <invoke-bash cmd="command -v codex &amp;&amp; codex --version 2>/dev/null || echo 'NOT_FOUND'" />
+      <check if="{{bash_exit_code}} == 0 AND {{bash_stdout}} does not contain 'NOT_FOUND'">
+        <set-var name="codex_available" value="true" />
+        <output>✓ Codex CLI detected</output>
+      </check>
+
+      <!-- Detect Gemini CLI availability -->
+      <invoke-bash cmd="command -v gemini &amp;&amp; gemini --version 2>/dev/null || echo 'NOT_FOUND'" />
+      <check if="{{bash_exit_code}} == 0 AND {{bash_stdout}} does not contain 'NOT_FOUND'">
+        <set-var name="gemini_available" value="true" />
+        <output>✓ Gemini CLI detected</output>
+      </check>
+
+      <!-- Detect Claude CLI availability -->
+      <invoke-bash cmd="command -v claude &amp;&amp; claude --version 2>/dev/null || echo 'NOT_FOUND'" />
+      <check if="{{bash_exit_code}} == 0 AND {{bash_stdout}} does not contain 'NOT_FOUND'">
+        <set-var name="claude_available" value="true" />
+        <output>✓ Claude CLI detected</output>
+      </check>
+
+      <!-- Select which external agent to use based on availability and preference -->
+      <check if="{{preferred_agent}} == 'codex' AND {{codex_available}} == true">
+        <set-var name="use_external_agent" value="true" />
+        <set-var name="external_agent_cmd" value="codex" />
+      </check>
+      <check if="{{preferred_agent}} == 'gemini' AND {{gemini_available}} == true">
+        <set-var name="use_external_agent" value="true" />
+        <set-var name="external_agent_cmd" value="gemini" />
+      </check>
+      <check if="{{preferred_agent}} == 'claude' AND {{claude_available}} == true">
+        <set-var name="use_external_agent" value="true" />
+        <set-var name="external_agent_cmd" value="claude" />
+      </check>
+
+      <!-- Fallback selection if preferred agent not available -->
+      <check if="{{use_external_agent}} == false AND {{codex_available}} == true">
+        <set-var name="use_external_agent" value="true" />
+        <set-var name="external_agent_cmd" value="codex" />
+        <output>⚠️ Preferred agent ({{preferred_agent}}) not available, falling back to Codex</output>
+      </check>
+      <check if="{{use_external_agent}} == false AND {{gemini_available}} == true">
+        <set-var name="use_external_agent" value="true" />
+        <set-var name="external_agent_cmd" value="gemini" />
+        <output>⚠️ Preferred agent ({{preferred_agent}}) not available, falling back to Gemini</output>
+      </check>
+      <check if="{{use_external_agent}} == false AND {{claude_available}} == true">
+        <set-var name="use_external_agent" value="true" />
+        <set-var name="external_agent_cmd" value="claude" />
+        <output>⚠️ Preferred agent ({{preferred_agent}}) not available, falling back to Claude</output>
+      </check>
+
+      <check if="{{use_external_agent}} == true">
+        <output>🤖 External agent selected: {{external_agent_cmd}} - will delegate code review</output>
+      </check>
+      <check if="{{use_external_agent}} == false">
+        <output>📋 No external agent available - will use built-in adversarial review</output>
+      </check>
+    </check>
   </step>
 
   <step n="2" goal="Build review attack plan">
@@ -56,41 +176,105 @@
   <step n="3" goal="Execute adversarial review">
     <critical>VALIDATE EVERY CLAIM - Check git reality vs story claims</critical>
 
-    <!-- Git vs Story Discrepancies -->
+    <!-- Git vs Story Discrepancies - ALWAYS runs -->
     <action>Review git vs story File List discrepancies:
       1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation)
       2. **Story lists files but no git changes** → HIGH finding (false claims)
       3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue)
     </action>
-
-    <!-- Use combined file list: story File List + git discovered files -->
     <action>Create comprehensive review file list from story File List and git changes</action>
+    <action>Store git discrepancy findings in {{git_findings}}</action>
 
-    <!-- AC Validation -->
-    <action>For EACH Acceptance Criterion:
-      1. Read the AC requirement
-      2. Search implementation files for evidence
-      3. Determine: IMPLEMENTED, PARTIAL, or MISSING
-      4. If MISSING/PARTIAL → HIGH SEVERITY finding
-    </action>
+    <!-- ============================================================== -->
+    <!-- MANDATORY: INVOKE EXTERNAL AGENT IF AVAILABLE                  -->
+    <!-- ============================================================== -->
+    <critical>If {{use_external_agent}} == true, you MUST invoke the external agent via CLI.</critical>
+    <critical>DO NOT perform your own code review - delegate to the external agent.</critical>
 
-    <!-- Task Completion Audit -->
-    <action>For EACH task marked [x]:
-      1. Read the task description
-      2. Search files for evidence it was actually done
-      3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding
-      4. Record specific proof (file:line)
-    </action>
+    <check if="{{use_external_agent}} == true">
+      <output>🔄 Invoking {{external_agent_cmd}} CLI for adversarial code review...</output>
 
-    <!-- Code Quality Deep Dive -->
-    <action>For EACH file in comprehensive review list:
-      1. **Security**: Look for injection risks, missing validation, auth issues
-      2. **Performance**: N+1 queries, inefficient loops, missing caching
-      3. **Error Handling**: Missing try/catch, poor error messages
-      4. **Code Quality**: Complex functions, magic numbers, poor naming
-      5. **Test Quality**: Are tests real assertions or placeholders?
-    </action>
+      <!-- ============================================================== -->
+      <!-- INVOKE EXTERNAL AGENT - USE EXACT COMMANDS AS WRITTEN          -->
+      <!-- ============================================================== -->
+      <critical>🚨 USE EXACT COMMAND SYNTAX - DO NOT MODIFY OR SIMPLIFY 🚨</critical>
+      <critical>Copy the invoke-bash cmd attribute EXACTLY as written below.</critical>
+      <critical>DO NOT remove flags, reorder arguments, or "improve" the command.</critical>
 
+      <!-- External agent prompt is loaded from external-agent-prompt.md -->
+      <set-var name="external_prompt_file" value="{installed_path}/external-agent-prompt.md" />
+      <action>Load {{external_prompt_file}} content into {{external_prompt}}</action>
+
+      <check if="{{external_agent_cmd}} == 'codex'">
+        <critical>CODEX: Use codex exec with read-only sandbox and full-auto</critical>
+        <invoke-bash cmd="codex exec --sandbox read-only --full-auto &quot;$(cat '{{external_prompt_file}}')&quot;" timeout="300000" />
+      </check>
+      <check if="{{external_agent_cmd}} == 'gemini'">
+        <critical>GEMINI: Use gemini -p with prompt from file and --yolo</critical>
+        <invoke-bash cmd="gemini -p &quot;$(cat '{{external_prompt_file}}')&quot; --yolo" timeout="300000" />
+      </check>
+      <check if="{{external_agent_cmd}} == 'claude'">
+        <critical>CLAUDE: Use claude -p with prompt from file</critical>
+        <invoke-bash cmd="claude -p &quot;$(cat '{{external_prompt_file}}')&quot; --dangerously-skip-permissions" timeout="300000" />
+      </check>
+
+      <check if="{{bash_exit_code}} != 0 OR {{bash_stdout}} is empty">
+        <output>⚠️ External agent CLI failed (exit code: {{bash_exit_code}}), falling back to built-in review</output>
+        <output>Error: {{bash_stderr}}</output>
+        <set-var name="use_external_agent" value="false" />
+        <set-var name="external_agent_failed" value="true" />
+      </check>
+
+      <check if="{{bash_exit_code}} == 0 AND {{bash_stdout}} is not empty">
+        <set-var name="external_findings" value="{{bash_stdout}}" />
+        <action>Parse {{external_findings}} into structured HIGH/MEDIUM/LOW lists</action>
+        <action>Merge {{git_findings}} with {{external_findings}} into {{all_findings}}</action>
+        <output>✅ External review complete - {{external_agent_cmd}} CLI findings received</output>
+      </check>
+    </check>
+
+    <!-- Fallback to built-in if external agent failed -->
+    <check if="{{external_agent_failed}} == true">
+      <set-var name="use_external_agent" value="false" />
+    </check>
+
+    <check if="{{use_external_agent}} == false">
+      <!-- ============================================================== -->
+      <!-- FALLBACK ONLY: Built-in Review (when NO external agent works)  -->
+      <!-- ============================================================== -->
+      <critical>This section should ONLY execute if ALL external agents failed detection or invocation.</critical>
+      <critical>If you are here but an external agent was available, you have violated the workflow rules.</critical>
+      <output>⚠️ No external agent available - performing built-in adversarial review</output>
+
+      <!-- AC Validation -->
+      <action>For EACH Acceptance Criterion:
+        1. Read the AC requirement
+        2. Search implementation files for evidence
+        3. Determine: IMPLEMENTED, PARTIAL, or MISSING
+        4. If MISSING/PARTIAL → HIGH SEVERITY finding
+      </action>
+
+      <!-- Task Completion Audit -->
+      <action>For EACH task marked [x]:
+        1. Read the task description
+        2. Search files for evidence it was actually done
+        3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding
+        4. Record specific proof (file:line)
+      </action>
+
+      <!-- Code Quality Deep Dive -->
+      <action>For EACH file in comprehensive review list:
+        1. **Security**: Look for injection risks, missing validation, auth issues
+        2. **Performance**: N+1 queries, inefficient loops, missing caching
+        3. **Error Handling**: Missing try/catch, poor error messages
+        4. **Code Quality**: Complex functions, magic numbers, poor naming
+        5. **Test Quality**: Are tests real assertions or placeholders?
+      </action>
+
+      <action>Merge {{git_findings}} with built-in findings into {{all_findings}}</action>
+    </check>
+
+    <!-- Minimum issue check - applies to both paths -->
     <check if="total_issues_found lt 3">
       <critical>NOT LOOKING HARD ENOUGH - Find more problems!</critical>
       <action>Re-examine code for:
@@ -113,6 +297,7 @@
     <output>**🔥 CODE REVIEW FINDINGS, {user_name}!**
 
       **Story:** {{story_file}}
+      **Review Method:** {{external_agent_cmd}} OR built-in
       **Git vs Story Discrepancies:** {{git_discrepancy_count}} found
       **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low
 
@@ -185,7 +370,7 @@
       <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
     </check>
 
-    <!-- Sync sprint-status.yaml when story status changes (only if sprint tracking enabled) -->
+    <!-- Sync sprint-status.yaml when story status changes -->
     <check if="{{current_sprint_status}} != 'no-sprint-tracking'">
       <action>Load the FULL file: {sprint_status}</action>
       <action>Find development_status key matching {{story_key}}</action>
@@ -221,4 +406,4 @@
     </output>
   </step>
 
-</workflow>
+</workflow>

src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -18,6 +18,7 @@ sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-
 installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/code-review"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
+external_agent_prompt: "{installed_path}/external-agent-prompt.md"
 template: false
 
 variables:
@@ -25,6 +26,11 @@ variables:
   project_context: "**/project-context.md"
   story_dir: "{sprint_artifacts}"
 
+  # External code review agent configuration
+  # User selects preferred agent during install; detection verifies availability at runtime
+  # Supported values: codex, gemini, claude, none
+  external_review_agent: "{config_source}:external_review_agent || 'none'"
+
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
 # Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
@@ -51,4 +57,3 @@ input_file_patterns:
     load_strategy: "INDEX_GUIDED"
 
 standalone: true
-web_bundle: false

src/modules/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -30,7 +30,7 @@
       <output>
         **Required Options:**
         1. Run `sprint-planning` to initialize sprint tracking (recommended)
-        2. Provide specific epic-story number to draft (e.g., "1-2-user-auth")
+        2. Provide specific epic-story number to create (e.g., "1-2-user-auth")
         3. Provide path to story documents if sprint status doesn't exist yet
       </output>
       <ask>Choose option [1], provide epic-story number, path to story docs, or [q] to quit:</ask>
@@ -72,7 +72,7 @@
       <check if="no backlog story found">
         <output>📋 No backlog stories found in sprint-status.yaml
 
-          All stories are either already drafted, in progress, or done.
+          All stories are either already created, in progress, or done.
 
           **Options:**
           1. Run sprint-planning to refresh story tracking
@@ -129,7 +129,7 @@
     <check if="no backlog story found">
       <output>📋 No backlog stories found in sprint-status.yaml
 
-        All stories are either already drafted, in progress, or done.
+        All stories are either already created, in progress, or done.
 
         **Options:**
         1. Run sprint-planning to refresh story tracking

src/modules/bmm/workflows/4-implementation/create-story/template.md

@@ -1,6 +1,8 @@
 # Story {{epic_num}}.{{story_num}}: {{story_title}}
 
-Status: drafted
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
 
 ## Story
 
@@ -36,10 +38,6 @@ so that {{benefit}}.
 
 ## Dev Agent Record
 
-### Context Reference
-
-<!-- Path(s) to story context XML will be added here by context workflow -->
-
 ### Agent Model Used
 
 {{agent_model_name_version}}

src/modules/bmm/workflows/4-implementation/dev-story/checklist.md

@@ -57,7 +57,7 @@ validation-rules:
 
 ## 🔚 Final Status Verification
 
-- [ ] **Story Status Updated:** Story Status set to "Ready for Review"
+- [ ] **Story Status Updated:** Story Status set to "review"
 - [ ] **Sprint Status Updated:** Sprint status updated to "review" (when sprint tracking is used)
 - [ ] **Quality Gates Passed:** All quality checks and validations completed successfully
 - [ ] **No HALT Conditions:** No blocking issues or incomplete work remaining

src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml

@@ -40,9 +40,11 @@
 
           **What would you like to do?**
           1. Run `create-story` to create next story from epics with comprehensive context
-          2. Run `*validate-create-story` to improve existing drafted stories before development
+          2. Run `*validate-create-story` to improve existing stories before development (recommended quality check)
           3. Specify a particular story file to develop (provide full path)
           4. Check {{sprint_status}} file to see current sprint status
+
+          💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality check.
         </output>
         <ask>Choose option [1], [2], [3], or [4], or specify story file path:</ask>
 
@@ -85,7 +87,7 @@
 
           **Available Options:**
           1. Run `create-story` to create next story from epics with comprehensive context
-          2. Run `*validate-create-story` to improve existing drafted stories
+          2. Run `*validate-create-story` to improve existing stories
           3. Specify which story to develop
         </output>
         <ask>What would you like to do? Choose option [1], [2], or [3]:</ask>
@@ -322,7 +324,7 @@
     <action>Run the full regression suite (do not skip)</action>
     <action>Confirm File List includes every changed file</action>
     <action>Execute enhanced definition-of-done validation</action>
-    <action>Update the story Status to: "Ready for Review"</action>
+    <action>Update the story Status to: "review"</action>
 
     <!-- Enhanced Definition of Done Validation -->
     <action>Validate definition-of-done checklist with essential requirements:
@@ -346,17 +348,17 @@
       <action>Verify current status is "in-progress" (expected previous state)</action>
       <action>Update development_status[{{story_key}}] = "review"</action>
       <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
-      <output>✅ Story marked Ready for Review in sprint status</output>
+      <output>✅ Story status updated to "review" in sprint-status.yaml</output>
     </check>
 
     <check if="{sprint_status} file does NOT exist OR {{current_sprint_status}} == 'no-sprint-tracking'">
-      <output>ℹ️ Story marked Ready for Review in story file (no sprint tracking configured)</output>
+      <output>ℹ️ Story status updated to "review" in story file (no sprint tracking configured)</output>
     </check>
 
     <check if="story key not found in sprint status">
       <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
 
-        Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync.
+        Story status is set to "review" in file, but sprint-status.yaml may be out of sync.
       </output>
     </check>
 
@@ -373,7 +375,7 @@
 
     <action>Communicate to {user_name} that story implementation is complete and ready for review</action>
     <action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
-    <action>Provide the story file path and current status (now "Ready for Review")</action>
+    <action>Provide the story file path and current status (now "review")</action>
 
     <action>Based on {user_skill_level}, ask if user needs any explanations about:
       - What was implemented and how it works

src/modules/bmm/workflows/4-implementation/retrospective/instructions.md

@@ -1396,7 +1396,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need
   {{else}}
 
 4. **Begin Epic {{next_epic_num}} when ready**
-   - Start drafting stories with SM agent's `create-story`
+   - Start creating stories with SM agent's `create-story`
    - Epic will be marked as `in-progress` automatically when first story is created
    - Ensure all critical path items are done first
      {{/if}}

src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -73,22 +73,17 @@ development_status:
 **Story file detection:**
 
 - Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`)
-- If exists → upgrade status to at least `drafted`
-
-**Story context detection:**
-
-- Check: `{story_location_absolute}/{story-key}-context.md` (e.g., `stories/1-1-user-authentication-context.md`)
 - If exists → upgrade status to at least `ready-for-dev`
 
 **Preservation rule:**
 
 - If existing `{status_file}` exists and has more advanced status, preserve it
-- Never downgrade status (e.g., don't change `done` to `drafted`)
+- Never downgrade status (e.g., don't change `done` to `ready-for-dev`)
 
 **Status Flow Reference:**
 
 - Epic: `backlog` → `in-progress` → `done`
-- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Story: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
 - Retrospective: `optional` ↔ `completed`
   </step>
 
@@ -117,8 +112,7 @@ development_status:
 #
 # Story Status:
 #   - backlog: Story only exists in epic file
-#   - drafted: Story file created in stories folder
-#   - ready-for-dev: Draft approved and story context created
+#   - ready-for-dev: Story file created in stories folder
 #   - in-progress: Developer actively working on implementation
 #   - review: Ready for code review (via Dev's code-review workflow)
 #   - done: Story completed
@@ -131,7 +125,7 @@ development_status:
 # ===============
 # - Epic transitions to 'in-progress' automatically when first story is created
 # - Stories can be worked in parallel if team capacity allows
-# - SM typically drafts next story after previous one is 'done' to incorporate learnings
+# - SM typically creates next story after previous one is 'done' to incorporate learnings
 # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
 
 generated: { date }
@@ -198,18 +192,17 @@ backlog → in-progress → done
 ```
 
 - **backlog**: Epic not yet started
-- **in-progress**: Epic actively being worked on (stories being drafted/implemented)
+- **in-progress**: Epic actively being worked on (stories being created/implemented)
 - **done**: All stories in epic completed
 
 **Story Status Flow:**
 
 ```
-backlog → drafted → ready-for-dev → in-progress → review → done
+backlog → ready-for-dev → in-progress → review → done
 ```
 
 - **backlog**: Story only exists in epic file
-- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
-- **ready-for-dev**: Draft approved + story context created
+- **ready-for-dev**: Story file created (e.g., `stories/1-3-plant-naming.md`)
 - **in-progress**: Developer actively working
 - **review**: Ready for code review (via Dev's code-review workflow)
 - **done**: Completed
@@ -229,4 +222,4 @@ optional ↔ completed
 2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported
 3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
 4. **Review Before Done**: Stories should pass through `review` before `done`
-5. **Learning Transfer**: SM typically drafts next story after previous one is `done` to incorporate learnings
+5. **Learning Transfer**: SM typically creates next story after previous one is `done` to incorporate learnings

src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml

@@ -17,8 +17,7 @@
 #
 # Story Status:
 #   - backlog: Story only exists in epic file
-#   - drafted: Story file created in stories folder
-#   - ready-for-dev: Draft approved, ready for development
+#   - ready-for-dev: Story file created, ready for development
 #   - in-progress: Developer actively working on implementation
 #   - review: Implementation complete, ready for review
 #   - done: Story completed
@@ -30,7 +29,7 @@
 # WORKFLOW NOTES:
 # ===============
 # - Mark epic as 'in-progress' when starting work on its first story
-# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings
+# - SM typically creates next story ONLY after previous one is 'done' to incorporate learnings
 # - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM)
 
 # EXAMPLE STRUCTURE (your actual epics/stories will replace these):
@@ -44,7 +43,7 @@ story_location: "{story_location}"
 development_status:
   epic-1: backlog
   1-1-user-authentication: done
-  1-2-account-management: drafted
+  1-2-account-management: ready-for-dev
   1-3-plant-data-model: backlog
   1-4-add-plant-manual: backlog
   epic-1-retrospective: optional

src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md

@@ -40,12 +40,14 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
   - Epics: keys starting with "epic-" (and not ending with "-retrospective")
   - Retrospectives: keys ending with "-retrospective"
   - Stories: everything else (e.g., 1-2-login-form)
-  <action>Count story statuses: backlog, drafted, ready-for-dev, in-progress, review, done</action>
+  <action>If any story has status `drafted`, treat as `ready-for-dev` (legacy status)</action>
+  <action>Count story statuses: backlog, ready-for-dev, in-progress, review, done</action>
   <action>Count epic statuses: backlog, contexted</action>
   <action>Detect risks:</action>
   - Stories in review but no reviewer assigned context → suggest `/bmad:bmm:workflows:code-review`
   - Stories in in-progress with no ready-for-dev items behind them → keep focus on the active story
-  - All epics backlog/contexted but no stories drafted → prompt to run `/bmad:bmm:workflows:create-story`
+  - All epics backlog/contexted but no stories ready-for-dev → prompt to run `/bmad:bmm:workflows:create-story`
+  - Stories in ready-for-dev may be unvalidated → suggest `/bmad:bmm:workflows:validate-create-story` before `dev-story` for quality check
 </step>
 
 <step n="3" goal="Select next action recommendation">
@@ -67,7 +69,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
 - Tracking: {{tracking_system}}
 - Status file: {sprint_status_file}
 
-**Stories:** backlog {{count_backlog}}, drafted {{count_drafted}}, ready-for-dev {{count_ready}}, in-progress {{count_in_progress}}, review {{count_review}}, done {{count_done}}
+**Stories:** backlog {{count_backlog}}, ready-for-dev {{count_ready}}, in-progress {{count_in_progress}}, review {{count_review}}, done {{count_done}}
 
 **Epics:** backlog {{epic_backlog}}, contexted {{epic_contexted}}
 
@@ -85,7 +87,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
 **Per Epic:**
 {{#each by_epic}}
 
-- {{epic_id}}: context={{context_status}}, stories → backlog {{backlog}}, drafted {{drafted}}, ready {{ready_for_dev}}, in-progress {{in_progress}}, review {{review}}, done {{done}}
+- {{epic_id}}: context={{context_status}}, stories → backlog {{backlog}}, ready {{ready_for_dev}}, in-progress {{in_progress}}, review {{review}}, done {{done}}
   {{/each}}
   {{/if}}
   </output>
@@ -110,7 +112,6 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
 - In Progress: {{stories_in_progress}}
 - Review: {{stories_in_review}}
 - Ready for Dev: {{stories_ready_for_dev}}
-- Drafted: {{stories_drafted}}
 - Backlog: {{stories_backlog}}
 - Done: {{stories_done}}
     </output>
@@ -135,7 +136,6 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
   <template-output>next_workflow_id = {{next_workflow_id}}</template-output>
   <template-output>next_story_id = {{next_story_id}}</template-output>
   <template-output>count_backlog = {{count_backlog}}</template-output>
-  <template-output>count_drafted = {{count_drafted}}</template-output>
   <template-output>count_ready = {{count_ready}}</template-output>
   <template-output>count_in_progress = {{count_in_progress}}</template-output>
   <template-output>count_review = {{count_review}}</template-output>