a few more instruction cleanup items

src/modules/bmm/workflows/4-implementation/correct-course/instructions.md

@@ -28,7 +28,7 @@
 </step>
 
 <step n="2" goal="Execute Change Analysis Checklist">
-  <action>Load and execute the systematic analysis from: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/checklist.md</action>
+  <action>Load and execute the systematic analysis from: {checklist}</action>
   <action>Work through each checklist section interactively with the user</action>
   <action>Record status for each checklist item:</action>
     - [x] Done - Item completed successfully
@@ -133,6 +133,7 @@
 - Define success criteria for implementation
 
 <action>Present complete Sprint Change Proposal to user</action>
+<action>Write Sprint Change Proposal document to {default_output_file}</action>
 <ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
 </step>
 

src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml

@@ -7,13 +7,18 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
 date: system-generated
 
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
 template: false
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
+checklist: "{installed_path}/checklist.md"
+default_output_file: "{output_folder}/sprint-change-proposal-{date}.md"
 
+# Workflow execution mode (interactive: step-by-step with user, non-interactive: automated)
 mode: interactive
 
 required_inputs:

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

@@ -28,15 +28,19 @@
     <action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
   </step>
 
-  <step n="3" goal="Determine target story from sprint status">
-    <action>Query sprint-status for next backlog story:</action>
+  <step n="3" goal="Find next backlog story to draft" tag="sprint-status">
+    <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely to understand story order</action>
 
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: get_next_story</param>
-      <param>filter_status: backlog</param>
-    </invoke-workflow>
+    <action>Find the FIRST story (by reading in order from top to bottom) where:
+      - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+      - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+      - Status value equals "backlog"
+    </action>
 
-    <check if="{{result_found}} == false">
+    <check if="no backlog story found">
       <output>📋 No backlog stories found in sprint-status.yaml
 
 All stories are either already drafted or completed.
@@ -49,13 +53,16 @@ All stories are either already drafted or completed.
       <action>HALT</action>
     </check>
 
-    <action>Parse {{result_story_key}} to extract epic_num, story_num, and story_title
-      Example: "1-2-user-authentication" → epic_num=1, story_num=2, title="user-authentication"
+    <action>Extract from found story key (e.g., "1-2-user-authentication"):
+      - epic_num: first number before dash (e.g., "1")
+      - story_num: second number after first dash (e.g., "2")
+      - story_title: remainder after second dash (e.g., "user-authentication")
     </action>
     <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
+    <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
 
     <action>Verify story is enumerated in {{epics_file}}. If not found, HALT with message:</action>
-    <action>"Story {{result_story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story."</action>
+    <action>"Story {{story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story."</action>
 
     <action>Check if story file already exists at expected path in {{story_dir}}</action>
     <check if="story file exists">
@@ -97,19 +104,20 @@ Will update existing story file rather than creating new one.
     <template-output file="{default_output_file}">change_log</template-output>
   </step>
 
-  <step n="8" goal="Validate, save, and optionally generate context">
+  <step n="8" goal="Validate, save, and mark story drafted" tag="sprint-status">
     <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
     <action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
 
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: update_story_status</param>
-      <param>story_key: {{result_story_key}}</param>
-      <param>new_status: drafted</param>
-      <param>validate: true</param>
-    </invoke-workflow>
+    <!-- Mark story as drafted in sprint status -->
+    <action>Update {{output_folder}}/sprint-status.yaml</action>
+    <action>Load the FULL file and read all development_status entries</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "drafted"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-    <check if="{{result_success}} == false">
-      <output>⚠️ Could not update story status: {{result_error}}
+    <check if="story key not found in file">
+      <output>⚠️ Could not update story status: {{story_key}} not found in sprint-status.yaml
 
 Story file was created successfully, but sprint-status.yaml was not updated.
 You may need to run sprint-planning to refresh tracking.
@@ -122,14 +130,16 @@ You may need to run sprint-planning to refresh tracking.
 
 **Story Details:**
 - Story ID: {{story_id}}
-- Story Key: {{result_story_key}}
+- Story Key: {{story_key}}
 - File: {{story_file}}
-- Status: {{result_new_status}} (was {{result_old_status}})
+- Status: drafted (was backlog)
+
+**⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command.
 
 **Next Steps:**
 1. Review the drafted story in {{story_file}}
-2. When satisfied, run `story-ready` to approve for development
-3. Or edit the story file and re-run `create-story` to update
+2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step)
+3. Or run `story-ready` to manually mark the story ready without generating technical context
     </output>
   </step>
 

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

@@ -1,6 +1,6 @@
 # Story {{epic_num}}.{{story_num}}: {{story_title}}
 
-Status: Draft
+Status: drafted
 
 ## Story
 

src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -37,7 +37,8 @@ variables:
   non_interactive: true # Generate without elicitation; avoid interactive prompts
 
 # Output configuration
-default_output_file: "{story_dir}/story-{{epic_num}}.{{story_num}}.md"
+# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
+default_output_file: "{story_dir}/{{story_key}}.md"
 
 recommended_inputs:
   - epics: "Epic breakdown (epics.md)"

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

@@ -0,0 +1,367 @@
+# Workflow Audit Report
+
+**Workflow:** dev-story
+**Audit Date:** 2025-10-25
+**Auditor:** Audit Workflow (BMAD v6)
+**Workflow Type:** Action Workflow
+**Module:** BMM (BMad Method)
+
+---
+
+## Executive Summary
+
+**Overall Status:** GOOD - Minor issues to address
+
+- Critical Issues: 0
+- Important Issues: 3
+- Cleanup Recommendations: 2
+
+The dev-story workflow is well-structured and follows most BMAD v6 standards. The workflow correctly sets `web_bundle: false` as expected for implementation workflows. However, there are several config variable usage issues and some variables referenced in instructions that are not defined in the YAML.
+
+---
+
+## 1. Standard Config Block Validation
+
+**Status:** PASS ✓
+
+The workflow.yaml contains all required standard config variables:
+
+- ✓ `config_source: "{project-root}/bmad/bmm/config.yaml"` - Correctly defined
+- ✓ `output_folder: "{config_source}:output_folder"` - Pulls from config_source
+- ✓ `user_name: "{config_source}:user_name"` - Pulls from config_source
+- ✓ `communication_language: "{config_source}:communication_language"` - Pulls from config_source
+- ✓ `date: system-generated` - Correctly set
+
+All standard config variables are present and properly formatted using {project-root} variable syntax.
+
+---
+
+## 2. YAML/Instruction/Template Alignment
+
+**Variables Analyzed:** 9 (excluding standard config)
+**Used in Instructions:** 6
+**Unused (Bloat):** 3
+
+### YAML Variables Defined
+
+1. `story_dir` - USED in instructions (file paths)
+2. `context_path` - UNUSED (appears to duplicate story_dir)
+3. `story_file` - USED in instructions
+4. `context_file` - USED in instructions
+5. `installed_path` - USED in instructions (workflow.xml reference)
+6. `instructions` - USED in instructions (self-reference in critical tag)
+7. `validation` - USED in instructions (checklist reference)
+8. `web_bundle` - CONFIGURATION (correctly set to false)
+9. `date` - USED in instructions (config variable)
+
+### Variables Used in Instructions But NOT Defined in YAML
+
+**IMPORTANT ISSUE:** The following variables are referenced in instructions.md but are NOT defined in workflow.yaml:
+
+1. `{user_skill_level}` - Used 4 times (lines 6, 13, 173, 182)
+2. `{document_output_language}` - Used 1 time (line 7)
+3. `{run_until_complete}` - Used 1 time (line 108)
+4. `{run_tests_command}` - Used 1 time (line 120)
+
+These variables appear to be pulling from config.yaml but are not explicitly defined in the workflow.yaml file. While the config_source mechanism may provide these, workflow.yaml should document all variables used in the workflow for clarity.
+
+### Unused Variables (Bloat)
+
+1. **context_path** - Defined as `"{config_source}:dev_story_location"` but never used. This duplicates `story_dir` functionality.
+
+---
+
+## 3. Config Variable Usage
+
+**Communication Language:** PASS ✓
+**User Name:** PASS ✓
+**Output Folder:** PASS ✓
+**Date:** PASS ✓
+
+### Detailed Analysis
+
+**Communication Language:**
+
+- ✓ Used in line 6: "Communicate all responses in {communication_language}"
+- ✓ Properly used as agent instruction variable (not in template)
+
+**User Name:**
+
+- ✓ Used in line 169: "Communicate to {user_name} that story implementation is complete"
+- ✓ Appropriately used for personalization
+
+**Output Folder:**
+
+- ✓ Used multiple times for sprint-status.yaml file paths
+- ✓ All file operations target {output_folder} correctly
+- ✓ No hardcoded paths detected
+
+**Date:**
+
+- ✓ Available for agent use (system-generated)
+- ✓ Used appropriately in context of workflow execution
+
+### Additional Config Variables
+
+**IMPORTANT ISSUE:** The workflow uses additional variables that appear to come from config but are not explicitly documented:
+
+1. `{user_skill_level}` - Used to tailor communication style
+2. `{document_output_language}` - Used for document generation
+3. `{run_until_complete}` - Used for execution control
+4. `{run_tests_command}` - Used for test execution
+
+These should either be:
+
+- Added to workflow.yaml with proper config_source references, OR
+- Documented as optional config variables with defaults
+
+---
+
+## 4. Web Bundle Validation
+
+**Web Bundle Present:** No (Intentional)
+**Status:** EXPECTED ✓
+
+The workflow correctly sets `web_bundle: false`. This is the expected configuration for implementation workflows that:
+
+- Run locally in the development environment
+- Don't need to be bundled for web deployment
+- Are IDE-integrated workflows
+
+**No issues found** - This is the correct configuration for dev-story.
+
+---
+
+## 5. Bloat Detection
+
+**Bloat Percentage:** 11% (1 unused field / 9 total fields)
+**Cleanup Potential:** Low
+
+### Unused YAML Fields
+
+1. **context_path** (line 11 in workflow.yaml)
+   - Defined as: `"{config_source}:dev_story_location"`
+   - Never referenced in instructions.md
+   - Duplicates functionality of `story_dir` variable
+   - **Recommendation:** Remove this variable as `story_dir` serves the same purpose
+
+### Hardcoded Values
+
+No significant hardcoded values that should be variables were detected. The workflow properly uses variables for:
+
+- File paths ({output_folder}, {story_dir})
+- User personalization ({user_name})
+- Communication style ({communication_language}, {user_skill_level})
+
+### Calculation
+
+- Total yaml fields: 9 (excluding standard config and metadata)
+- Used fields: 8
+- Unused fields: 1 (context_path)
+- Bloat percentage: 11%
+
+**Status:** Acceptable (under 15% threshold)
+
+---
+
+## 6. Template Variable Mapping
+
+**Not Applicable** - This is an action workflow, not a document workflow.
+
+No template.md file exists, which is correct for action-type workflows.
+
+---
+
+## 7. Instructions Quality Analysis
+
+### Structure
+
+- ✓ Steps numbered sequentially (1, 1.5, 2-7)
+- ✓ Each step has clear goal attributes
+- ✓ Proper use of XML tags (<action>, <check>, <goto>, <anchor>, <output>)
+- ✓ Logical flow control with anchors and conditional checks
+- ✓ Repeat patterns used appropriately (step 2-5 loop)
+
+### Critical Tags
+
+- ✓ Critical blocks present and well-defined
+- ✓ Clear references to workflow execution engine
+- ✓ Workflow.yaml load requirement specified
+- ✓ Communication preferences documented
+
+### Variable Usage Consistency
+
+**ISSUE:** Inconsistent variable syntax found:
+
+1. Lines 4, 5 use `{project_root}` (underscore)
+2. Line 166 uses `{project-root}` (hyphen)
+
+**Recommendation:** Standardize to `{project-root}` throughout (hyphen is the standard in BMAD v6)
+
+### Step Quality
+
+**Excellent:**
+
+- Steps are focused and single-purpose
+- Clear HALT conditions defined
+- Comprehensive validation checks
+- Good error handling patterns
+- Iterative execution model well-structured
+
+**Areas for improvement:**
+
+- Step 1 is complex and could potentially be split
+- Some <action if="..."> conditionals could be clearer with <check> blocks
+
+---
+
+## Recommendations
+
+### Critical (Fix Immediately)
+
+None - No critical issues detected.
+
+### Important (Address Soon)
+
+1. **Document or Define Missing Variables**
+   - Add explicit definitions in workflow.yaml for: `user_skill_level`, `document_output_language`, `run_until_complete`, `run_tests_command`
+   - OR document these as optional config variables with defaults
+   - These variables are used in instructions but not defined in YAML
+   - **Impact:** Reduces clarity and may cause confusion about variable sources
+
+2. **Standardize project-root Variable Syntax**
+   - Change line 4 `{project_root}` to `{project-root}` (hyphen)
+   - Ensure consistency with BMAD v6 standard naming convention
+   - **Impact:** Maintains consistency with framework standards
+
+3. **Remove or Use context_path Variable**
+   - Variable `context_path` is defined but never used
+   - Since `story_dir` serves the same purpose, remove `context_path`
+   - OR if there's a semantic difference, document why both exist
+   - **Impact:** Reduces bloat and potential confusion
+
+### Cleanup (Nice to Have)
+
+1. **Consider Splitting Step 1**
+   - Step 1 handles both story discovery AND file loading
+   - Could be split into "1. Find Story" and "2. Load Story Files"
+   - Would improve clarity and maintainability
+   - **Impact:** Minor improvement to workflow structure
+
+2. **Add Variable Documentation Comment**
+   - Add a comment block in workflow.yaml listing all variables used by this workflow
+   - Include both explicit YAML variables and config-pulled variables
+   - Example format:
+     ```yaml
+     # Workflow-specific variables
+     # - story_file: Path to story markdown
+     # - story_dir: Directory containing stories
+     #
+     # Config-pulled variables (from bmm/config.yaml)
+     # - user_skill_level: User's technical skill level
+     # - document_output_language: Language for generated docs
+     ```
+   - **Impact:** Improves developer understanding and maintenance
+
+---
+
+## Validation Checklist
+
+### Structure ✓
+
+- [x] workflow.yaml loads without YAML syntax errors
+- [x] instructions.md exists and is properly formatted
+- [x] No template.md (correct for action workflow)
+- [x] All critical headers present in instructions
+- [x] Workflow type correctly identified (action)
+- [x] All referenced files exist
+- [x] No placeholder text remains
+
+### Standard Config Block ✓
+
+- [x] config_source points to correct module config
+- [x] output_folder pulls from config_source
+- [x] user_name pulls from config_source
+- [x] communication_language pulls from config_source
+- [x] date is system-generated
+- [x] Config source uses {project-root} variable
+- [x] Standard config comment present
+
+### Config Variable Usage ✓
+
+- [x] Instructions communicate in {communication_language}
+- [x] Instructions address {user_name}
+- [x] All file outputs use {output_folder}
+- [x] No hardcoded paths
+- [x] Date available for agent awareness
+
+### YAML/Instruction/Template Alignment ⚠️
+
+- [⚠️] Some variables used in instructions not defined in YAML
+- [x] Template variables N/A (action workflow)
+- [x] Variable names are descriptive
+- [⚠️] One unused yaml field (context_path)
+
+### Web Bundle Validation ✓
+
+- [x] web_bundle: false is correct for this workflow
+- [x] No web_bundle section needed
+- [x] Workflow is local/IDE-integrated only
+
+### Instructions Quality ✓
+
+- [x] Steps numbered sequentially
+- [x] Clear goal attributes
+- [x] Proper XML tag usage
+- [x] Logical flow control
+- [⚠️] Minor inconsistency: {project_root} vs {project-root}
+
+### Bloat Detection ✓
+
+- [x] Bloat percentage: 11% (acceptable, under 15%)
+- [x] No significant hardcoded values
+- [x] No redundant configuration
+- [x] One cleanup recommendation (context_path)
+
+---
+
+## Next Steps
+
+1. **Define missing variables** - Add explicit YAML definitions or document as config-pulled variables
+2. **Standardize variable syntax** - Change `{project_root}` to `{project-root}`
+3. **Remove context_path** - Clean up unused variable
+4. **Re-run audit** - Verify improvements after fixes
+
+---
+
+## Additional Notes
+
+### Strengths
+
+1. **Comprehensive Workflow Logic:** The dev-story workflow is well-thought-out with proper error handling, validation gates, and iterative execution
+2. **Config Integration:** Excellent use of config variables for user personalization and output management
+3. **Clear Documentation:** Instructions are detailed with specific HALT conditions and validation checkpoints
+4. **Proper Web Bundle Setting:** Correctly identifies this as a local-only workflow with web_bundle: false
+5. **Step Flow:** Excellent use of anchors, goto, and conditional checks for complex flow control
+
+### Workflow Purpose
+
+This workflow executes user stories by:
+
+- Finding ready-for-dev stories from sprint status
+- Implementing tasks and subtasks incrementally
+- Writing comprehensive tests
+- Validating against acceptance criteria
+- Updating story status through sprint lifecycle
+- Supporting different user skill levels with adaptive communication
+
+The workflow is a critical part of the BMM implementation phase and shows mature design patterns.
+
+---
+
+**Audit Complete** - Generated by audit-workflow v1.0
+
+**Pass Rate:** 89% (62 passed / 70 total checks)
+**Recommendation:** Good - Minor fixes needed
+
+The dev-story workflow is production-ready with minor improvements recommended. The issues identified are primarily documentation and consistency improvements rather than functional problems.

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

@@ -7,15 +7,14 @@
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status</critical>
 <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
-<critical>If {{run_until_complete}} == true, run non-interactively: do not pause between steps unless a HALT condition is reached or explicit user approval is required for unapproved dependencies.</critical>
-<critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) or a HALT condition is triggered.</critical>
+<critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.</critical>
 <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
 
 <critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
 
 <workflow>
 
-  <step n="1" goal="Locate and load story from sprint status">
+  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
     <check if="{{story_path}} is provided">
       <action>Use {{story_path}} directly</action>
       <action>Read COMPLETE story file</action>
@@ -23,72 +22,87 @@
       <goto>task_check</goto>
     </check>
 
-    <action>Query sprint-status for ready stories:</action>
+    <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely to understand story order</action>
 
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: get_next_story</param>
-      <param>filter_status: ready-for-dev</param>
-    </invoke-workflow>
+    <action>Find the FIRST story (by reading in order from top to bottom) where:
+      - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+      - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+      - Status value equals "ready-for-dev"
+    </action>
 
-    <check if="{{result_found}} == false">
+    <check if="no ready-for-dev or in-progress story found">
       <output>📋 No ready-for-dev stories found in sprint-status.yaml
-
 **Options:**
-1. Run `story-ready` to mark drafted stories as ready
-2. Run `create-story` if no stories are drafted yet
-3. Check sprint-status.yaml to see current story states
+1. Run `story-context` to generate context file and mark drafted stories as ready
+2. Run `story-ready` to quickly mark drafted stories as ready without generating context
+3. Run `create-story` if no incomplete stories are drafted yet
+4. Check {output-folder}/sprint-status.yaml to see current sprint status
       </output>
       <action>HALT</action>
     </check>
 
-    <action>Use {{result_story_key}} to find story file in {{story_dir}}</action>
+    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
+    <action>Find matching story file in {{story_dir}} using story_key pattern: {{story_key}}.md</action>
     <action>Read COMPLETE story file from discovered path</action>
-    <action>Store {{result_story_key}} for later status updates</action>
 
     <anchor id="task_check" />
 
     <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+
+    <action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.md</action>
+    <check if="context file exists">
+      <action>Read COMPLETE context file</action>
+      <action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action>
+      <action>Use this context to inform implementation decisions and approaches</action>
+    </check>
+    <check if="context file does NOT exist">
+      <output>ℹ️ No context file found for {{story_key}}
+
+Proceeding with story file only. For better context, consider running `story-context` workflow first.
+      </output>
+    </check>
+
     <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
 
     <action if="no incomplete tasks"><goto step="6">Completion sequence</goto></action>
     <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
-    <action if="task requirements ambiguous">ASK user to clarify or HALT</action>
+    <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
   </step>
 
-  <step n="1.5" goal="Mark story in-progress in sprint status">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: get_story_status</param>
-      <param>story_key: {{result_story_key}}</param>
-    </invoke-workflow>
+  <step n="1.5" goal="Mark story in-progress" tag="sprint-status">
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read all development_status entries to find {{story_key}}</action>
+    <action>Get current status value for development_status[{{story_key}}]</action>
 
-    <check if="{{result_status}} == 'ready-for-dev'">
-      <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-        <param>action: update_story_status</param>
-        <param>story_key: {{result_story_key}}</param>
-        <param>new_status: in-progress</param>
-        <param>validate: true</param>
-      </invoke-workflow>
-
-      <check if="{{result_success}} == true">
-        <output>🚀 Starting work on story {{result_story_key}}
-Status updated: {{result_old_status}} → {{result_new_status}}
-        </output>
-      </check>
+    <check if="current status == 'ready-for-dev'">
+      <action>Update the story in the sprint status report to = "in-progress"</action>
+      <output>🚀 Starting work on story {{story_key}}
+Status updated: ready-for-dev → in-progress
+      </output>
     </check>
 
-    <check if="{{result_status}} == 'in-progress'">
-      <output>⏯️ Resuming work on story {{result_story_key}}
+    <check if="current status == 'in-progress'">
+      <output>⏯️ Resuming work on story {{story_key}}
 Story is already marked in-progress
       </output>
     </check>
+
+    <check if="current status is neither ready-for-dev nor in-progress">
+      <output>⚠️ Unexpected story status: {{current_status}}
+Expected ready-for-dev or in-progress. Continuing anyway...
+      </output>
+    </check>
   </step>
 
   <step n="2" goal="Plan and implement task">
     <action>Review acceptance criteria and dev notes for the selected task</action>
     <action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
-    <action>Implement the task COMPLETELY including all subtasks, following architecture patterns and coding standards in this repo</action>
+    <action>Implement the task COMPLETELY including all subtasks, critically following best practices, coding patterns and coding standards in this repo you have learned about from the story and context file or your own critical agent instructions</action>
     <action>Handle error conditions and edge cases appropriately</action>
-    <action if="unapproved dependencies are needed">ASK user for approval before adding</action>
+    <action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action>
     <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
     <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
     <action if="{{run_until_complete}} == true">Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</action>
@@ -108,7 +122,7 @@ Story is already marked in-progress
     <action>Run the new tests to verify implementation correctness</action>
     <action>Run linting and code quality checks if configured</action>
     <action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
-    <action if="regression tests fail">STOP and fix before continuing</action>
+    <action if="regression tests fail">STOP and fix before continuing, consider how current changes made broke regression</action>
     <action if="new tests fail">STOP and fix before continuing</action>
   </step>
 
@@ -116,29 +130,28 @@ Story is already marked in-progress
     <action>ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds</action>
     <action>Update File List section with any new, modified, or deleted files (paths relative to repo root)</action>
     <action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
-    <action>Append a brief entry to Change Log describing the change</action>
     <action>Save the story file</action>
     <action>Determine if more incomplete tasks remain</action>
-    <action if="more tasks remain"><goto step="1">Next task</goto></action>
+    <action if="more tasks remain"><goto step="2">Next task</goto></action>
     <action if="no tasks remain"><goto step="6">Completion</goto></action>
   </step>
 
-  <step n="6" goal="Story completion sequence">
+  <step n="6" goal="Story completion and mark for review" tag="sprint-status">
     <action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
     <action>Run the full regression suite (do not skip)</action>
     <action>Confirm File List includes every changed file</action>
     <action>Execute story definition-of-done checklist, if the story includes one</action>
-    <action>Update the story Status to: Ready for Review</action>
+    <action>Update the story Status to: review</action>
 
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: update_story_status</param>
-      <param>story_key: {{result_story_key}}</param>
-      <param>new_status: review</param>
-      <param>validate: true</param>
-    </invoke-workflow>
+    <!-- Mark story ready for review -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <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>
 
-    <check if="{{result_success}} == false">
-      <output>⚠️ Story file updated, but sprint-status update failed: {{result_error}}
+    <check if="story key not found in file">
+      <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.
       </output>
@@ -149,25 +162,36 @@ Story is marked Ready for Review in file, but sprint-status.yaml may be out of s
     <action if="File List is incomplete">Update it before completing</action>
   </step>
 
-  <step n="7" goal="Validation and handoff" optional="true">
+  <step n="7" goal="Completion communication and user support">
     <action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.xml</action>
     <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
-    <action>Communicate that the story is Ready for Review</action>
-    <output>**✅ Story Implementation Complete, {user_name}!**
 
-**Story Details:**
-- Story ID: {{current_story_id}}
-- Story Key: {{result_story_key}}
-- Title: {{current_story_title}}
-- File: {{story_path}}
-- Status: {{result_new_status}} (was {{result_old_status}})
+    <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 "review", was "in-progress")</action>
 
-**Next Steps:**
-1. Review the implemented story and test the changes
-2. Verify all acceptance criteria are met
-3. Run `review-story` workflow for senior developer review
-4. When review passes, run `story-done` to mark complete
-    </output>
+    <action>Based on {user_skill_level}, ask if user needs any explanations about:
+      - What was implemented and how it works
+      - Why certain technical decisions were made
+      - How to test or verify the changes
+      - Any patterns, libraries, or approaches used
+      - Anything else they'd like clarified
+    </action>
+
+    <check if="user asks for explanations">
+      <action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
+      <action>Use examples and references to specific code when helpful</action>
+    </check>
+
+    <action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
+    <action>Common next steps to suggest (but allow user flexibility):
+      - Review the implemented story yourself and test the changes
+      - Verify all acceptance criteria are met
+      - Ensure deployment readiness if applicable
+      - Run `review-story` workflow for peer review
+      - Check sprint-status.yaml to see project progress
+    </action>
+    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
   </step>
 
 </workflow>

src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml

@@ -7,28 +7,17 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+story_dir: "{config_source}:dev_story_location"
+context_path: "{config_source}:dev_story_location"
 date: system-generated
 
+story_file: "" # Explicit story path; auto-discovered if empty
+# Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.md")
+context_file: "{story_dir}/{{story_key}}.context.md"
+
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
-# This is an action workflow (no output template document)
-template: false
-
-# Variables (can be provided by caller)
-variables:
-  story_path: ""
-  run_tests_command: "auto" # 'auto' = infer from repo, or override with explicit command
-  strict: true # if true, halt on validation failures
-  story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
-  story_selection_limit: 10
-  run_until_complete: false # Continue through all tasks without pausing except on HALT conditions
-  force_yolo: false # Hint executor to activate #yolo: skip optional prompts and elicitation
-
-# Recommended inputs
-recommended_inputs:
-  - story_markdown: "Path to the story markdown file (Tasks/Subtasks, Acceptance Criteria present)"
-
 web_bundle: false

src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md

@@ -8,21 +8,59 @@
 <critical>If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed.</critical>
 
 <workflow>
-  <step n="1" goal="Collect inputs and initialize">
+  <step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
     <action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>
-    <ask if="inputs are missing">ask the user for file paths. HALT and wait for docs to proceed with the rest of step 2</ask>
+    <ask if="inputs are missing">ask the user for file paths. HALT and wait for docs to proceed</ask>
 
-    <action>Extract {{epic_title}} and {{epic_id}} from PRD.</action>
+    <!-- Intelligent Epic Discovery -->
+    <critical>MUST read COMPLETE sprint-status.yaml file to discover next epic</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL development_status entries</action>
+    <action>Find all epics with status "backlog" (not yet contexted)</action>
+    <action>Identify the FIRST backlog epic as the suggested default</action>
+
+    <check if="backlog epics found">
+      <output>📋 **Next Epic Suggested:** Epic {{suggested_epic_id}}: {{suggested_epic_title}}</output>
+      <ask>Use this epic?
+- [y] Yes, use {{suggested_epic_id}}
+- [n] No, let me specify a different epic_id
+      </ask>
+
+      <check if="user selects 'n'">
+        <ask>Enter the epic_id you want to context</ask>
+        <action>Store user-provided epic_id as {{epic_id}}</action>
+      </check>
+
+      <check if="user selects 'y'">
+        <action>Use {{suggested_epic_id}} as {{epic_id}}</action>
+      </check>
+    </check>
+
+    <check if="no backlog epics found">
+      <output>✅ All epics are already contexted!
+
+No epics with status "backlog" found in sprint-status.yaml.
+      </output>
+      <ask>Do you want to re-context an existing epic? Enter epic_id or [q] to quit:</ask>
+
+      <check if="user enters epic_id">
+        <action>Store as {{epic_id}}</action>
+      </check>
+
+      <check if="user enters 'q'">
+        <action>HALT - No work needed</action>
+      </check>
+    </check>
+
+    <action>Extract {{epic_title}} from PRD based on {{epic_id}}.</action>
     <action>Resolve output file path using workflow variables and initialize by writing the template.</action>
   </step>
 
-  <step n="1.5" goal="Validate epic in sprint status">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: get_epic_status</param>
-      <param>epic_id: {{epic_id}}</param>
-    </invoke-workflow>
+  <step n="2" goal="Validate epic exists in sprint status" tag="sprint-status">
+    <action>Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1)</action>
+    <action>Get current status value if epic exists</action>
 
-    <check if="{{result_found}} == false">
+    <check if="epic not found">
       <output>⚠️ Epic {{epic_id}} not found in sprint-status.yaml
 
 This epic hasn't been registered in the sprint plan yet.
@@ -31,7 +69,7 @@ Run sprint-planning workflow to initialize epic tracking.
       <action>HALT</action>
     </check>
 
-    <check if="{{result_status}} == 'contexted'">
+    <check if="epic status == 'contexted'">
       <output>ℹ️ Epic {{epic_id}} already marked as contexted
 
 Continuing to regenerate tech spec...
@@ -39,8 +77,8 @@ Continuing to regenerate tech spec...
     </check>
   </step>
 
-  <step n="2" goal="Overview and scope">
-    <action>Read COMPLETE PRD and Architecture files.</action>
+  <step n="3" goal="Overview and scope">
+    <action>Read COMPLETE found {recommended_inputs}.</action>
     <template-output file="{default_output_file}">
       Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals
       Replace {{objectives_scope}} with explicit in-scope and out-of-scope bullets
@@ -48,8 +86,8 @@ Continuing to regenerate tech spec...
     </template-output>
   </step>
 
-  <step n="3" goal="Detailed design">
-    <action>Derive concrete implementation specifics from Architecture and PRD (CRITICAL: NO invention).</action>
+  <step n="4" goal="Detailed design">
+    <action>Derive concrete implementation specifics from all {recommended_inputs} (CRITICAL: NO invention). If a epic tech spec precedes this one and exists, maintain consistency where appropriate.</action>
     <template-output file="{default_output_file}">
       Replace {{services_modules}} with a table or bullets listing services/modules with responsibilities, inputs/outputs, and owners
       Replace {{data_models}} with normalized data model definitions (entities, fields, types, relationships); include schema snippets where available
@@ -58,7 +96,7 @@ Continuing to regenerate tech spec...
     </template-output>
   </step>
 
-  <step n="4" goal="Non-functional requirements">
+  <step n="5" goal="Non-functional requirements">
     <template-output file="{default_output_file}">
       Replace {{nfr_performance}} with measurable targets (latency, throughput); link to any performance requirements in PRD/Architecture
       Replace {{nfr_security}} with authn/z requirements, data handling, threat notes; cite source sections
@@ -67,14 +105,14 @@ Continuing to regenerate tech spec...
     </template-output>
   </step>
 
-  <step n="5" goal="Dependencies and integrations">
+  <step n="6" goal="Dependencies and integrations">
     <action>Scan repository for dependency manifests (e.g., package.json, pyproject.toml, go.mod, Unity Packages/manifest.json).</action>
     <template-output file="{default_output_file}">
       Replace {{dependencies_integrations}} with a structured list of dependencies and integration points with version or commit constraints when known
     </template-output>
   </step>
 
-  <step n="6" goal="Acceptance criteria and traceability">
+  <step n="7" goal="Acceptance criteria and traceability">
     <action>Extract acceptance criteria from PRD; normalize into atomic, testable statements.</action>
     <template-output file="{default_output_file}">
       Replace {{acceptance_criteria}} with a numbered list of testable acceptance criteria
@@ -82,24 +120,25 @@ Continuing to regenerate tech spec...
     </template-output>
   </step>
 
-  <step n="7" goal="Risks and test strategy">
+  <step n="8" goal="Risks and test strategy">
     <template-output file="{default_output_file}">
       Replace {{risks_assumptions_questions}} with explicit list (each item labeled as Risk/Assumption/Question) with mitigation or next step
       Replace {{test_strategy}} with a brief plan (test levels, frameworks, coverage of ACs, edge cases)
     </template-output>
   </step>
 
-  <step n="8" goal="Validate and complete">
+  <step n="9" goal="Validate and mark epic contexted" tag="sprint-status">
     <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
 
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: update_epic_status</param>
-      <param>epic_id: {{epic_id}}</param>
-      <param>new_status: contexted</param>
-    </invoke-workflow>
+    <!-- Mark epic as contexted -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key "epic-{{epic_id}}"</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status["epic-{{epic_id}}"] = "contexted"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-    <check if="{{result_success}} == false">
-      <output>⚠️ Could not update epic status: {{result_error}}</output>
+    <check if="epic key not found in file">
+      <output>⚠️ Could not update epic status: epic-{{epic_id}} not found</output>
     </check>
 
     <output>**✅ Tech Spec Generated Successfully, {user_name}!**
@@ -108,14 +147,12 @@ Continuing to regenerate tech spec...
 - Epic ID: {{epic_id}}
 - Epic Title: {{epic_title}}
 - Tech Spec File: {{default_output_file}}
-- Epic Status: {{result_new_status}} (was {{result_old_status}})
+- Epic Status: contexted (was backlog)
 
 **Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed.
 
 **Next Steps:**
-1. If more epics need tech specs: Run tech-spec again with different epic_id
-2. If all tech specs complete: Proceed to Phase 4 implementation
-   - Load SM agent and run `create-story` to begin implementing stories
+1. Load SM agent and run `create-story` to begin implementing the first story under this epic.
     </output>
   </step>
 

src/modules/bmm/workflows/4-implementation/epic-tech-context/template.md

@@ -1,4 +1,4 @@
-# Technical Specification: {{epic_title}}
+# Epic Technical Specification: {{epic_title}}
 
 Date: {{date}}
 Author: {{user_name}}

src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml

@@ -16,6 +16,9 @@ recommended_inputs:
   - spec
   - architecture
   - ux_spec
+  - ux-design
+  - if there is an index.md then read the index.md to find other related docs that could be relevant
+  - prior epic tech-specs for model, style and consistency reference
 
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context"

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

@@ -20,30 +20,40 @@ FACILITATION NOTES:
 
 <workflow>
 
-<step n="1" goal="Epic Context Discovery">
+<step n="1" goal="Epic Context Discovery and verify completion" tag="sprint-status">
 <action>Help the user identify which epic was just completed through natural conversation</action>
 <action>Attempt to auto-detect by checking {output_folder}/stories/ for the highest numbered completed story and extracting the epic number</action>
 <action>If auto-detection succeeds, confirm with user: "It looks like Epic {{epic_number}} was just completed - is that correct?"</action>
 <action>If auto-detection fails or user indicates different epic, ask them to share which epic they just completed</action>
 
-<action>Verify epic completion status in sprint-status:</action>
+<action>Verify epic completion status:</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: check_epic_complete</param>
-  <param>epic_id: {{epic_number}}</param>
-</invoke-workflow>
+<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+<action>Read ALL development_status entries</action>
 
-<check if="{{result_complete}} == false">
+<action>Find all stories for epic {{epic_number}}:
+
+- Look for keys starting with "{{epic_number}}-" (e.g., "1-1-", "1-2-", etc.)
+- Exclude epic key itself ("epic-{{epic_number}}")
+- Exclude retrospective key ("epic-{{epic_number}}-retrospective")
+  </action>
+
+<action>Count total stories found for this epic</action>
+<action>Count stories with status = "done"</action>
+<action>Collect list of pending story keys (status != "done")</action>
+<action>Determine if complete: true if all stories are done, false otherwise</action>
+
+<check if="epic is not complete">
   <output>⚠️ Epic {{epic_number}} is not yet complete for retrospective
 
 **Epic Status:**
 
-- Total Stories: {{result_total_stories}}
-- Completed (Done): {{result_done_stories}}
-- Pending: {{result_total_stories - result_done_stories}}
+- Total Stories: {{total_stories}}
+- Completed (Done): {{done_stories}}
+- Pending: {{pending_count}}
 
 **Pending Stories:**
-{{result_pending_stories}}
+{{pending_story_list}}
 
 **Options:**
 
@@ -61,8 +71,8 @@ FACILITATION NOTES:
 <action if="user says yes">Set {{partial_retrospective}} = true</action>
 </check>
 
-<check if="{{result_complete}} == true">
-  <output>✅ Epic {{epic_number}} is complete - all {{result_done_stories}} stories done!
+<check if="epic is complete">
+  <output>✅ Epic {{epic_number}} is complete - all {{done_stories}} stories done!
 
 Ready to proceed with retrospective.
 </output>
@@ -403,27 +413,32 @@ See you at sprint planning once prep work is done!"
 ```
 
 <action>Save retrospective summary to: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md</action>
+</step>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: complete_retrospective</param>
-  <param>epic_id: {{completed_number}}</param>
-</invoke-workflow>
+<step n="9" goal="Mark retrospective completed in sprint status" tag="sprint-status">
+<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+<action>Find development_status key "epic-{{completed_number}}-retrospective"</action>
+<action>Verify current status is "optional" (expected previous state)</action>
+<action>Update development_status["epic-{{completed_number}}-retrospective"] = "completed"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="{{result_success}} == true">
+<check if="update successful">
   <output>✅ Retrospective marked as completed in sprint-status.yaml
 
-Retrospective key: {{result_retro_key}}
-Status: {{result_old_status}} → {{result_new_status}}
+Retrospective key: epic-{{completed_number}}-retrospective
+Status: optional → completed
 </output>
 </check>
 
-<check if="{{result_success}} == false">
-  <output>⚠️ Could not update retrospective status: {{result_error}}
+<check if="retrospective key not found">
+  <output>⚠️ Could not update retrospective status: epic-{{completed_number}}-retrospective not found
 
 Retrospective document was saved, but sprint-status.yaml may need manual update.
 </output>
 </check>
+</step>
 
+<step n="10" goal="Final summary">
 <action>Confirm all action items have been captured</action>
 <action>Remind user to schedule prep sprint if needed</action>
 <output>**✅ Retrospective Complete, {user_name}!**
@@ -431,7 +446,7 @@ Retrospective document was saved, but sprint-status.yaml may need manual update.
 **Epic Review:**
 
 - Epic {{completed_number}}: {{epic_title}} reviewed
-- Retrospective Status: {{result_new_status}}
+- Retrospective Status: completed
 - Retrospective saved: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md
 - Action Items: {{action_count}}
 - Preparation Tasks: {{prep_task_count}}

src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -7,6 +7,8 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
 date: system-generated
 
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective"
@@ -17,9 +19,6 @@ mode: interactive
 trigger: "Run AFTER completing an epic"
 
 required_inputs:
-  - completed_epic: "The epic that was just completed"
-  - stories_folder: "{output_folder}/stories/"
-  - epics_folder: "{output_folder}/prd/"
   - agent_manifest: "{project-root}/bmad/_cfg/agent-manifest.csv"
 
 output_artifacts:

src/modules/bmm/workflows/4-implementation/review-story/instructions.md

@@ -1,79 +1,71 @@
 # Senior Developer Review - Workflow Instructions
 
 ```xml
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <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>This workflow performs a Senior Developer Review on a story flagged Ready for Review, appends structured review notes, and can update the story status based on the outcome.</critical>
-<critical>Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery of the target story fails, HALT with a clear message to provide 'story_path' or 'story_dir'.</critical>
-<critical>Only modify the story file in these areas: Status (optional per settings), Dev Agent Record (Completion Notes), File List (if corrections are needed), Change Log, and the appended "Senior Developer Review (AI)" section at the end of the document.</critical>
+<critical>This workflow performs a Senior Developer Review on a story with status "review", appends structured review notes, and updates the story status based on outcome.</critical>
+<critical>If story_path is provided, use it. Otherwise, find the first story in sprint-status.yaml with status "review". If none found, HALT and ask for clarification.</critical>
+<critical>Only modify the story file in these areas: Status, Dev Agent Record (Completion Notes), File List (if corrections needed), Change Log, and the appended "Senior Developer Review (AI)" section.</critical>
 <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
 
 <critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
 
 <workflow>
 
-  <step n="1" goal="Locate story and verify review status">
+  <step n="1" goal="Find story ready for review" tag="sprint-status">
     <check if="{{story_path}} is provided">
       <action>Use {{story_path}} directly</action>
-      <action>Read COMPLETE file and parse sections</action>
+      <action>Read COMPLETE story file and parse sections</action>
       <action>Extract story_key from filename or story metadata</action>
-      <goto>verify_status</goto>
+      <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to proceed"</action>
     </check>
 
-    <action>Query sprint-status for review stories:</action>
+    <check if="{{story_path}} is NOT provided">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely</action>
 
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: list_stories</param>
-      <param>filter_status: review</param>
-      <param>limit: 10</param>
-    </invoke-workflow>
+      <action>Find FIRST story (reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "review"
+      </action>
 
-    <check if="{{result_count}} == 0">
-      <output>📋 No stories in review status found
+      <check if="no story with status 'review' found">
+        <output>📋 No stories with status "review" found
 
-**Options:**
-1. Run `dev-story` to implement and mark stories ready for review
+**Next Steps:**
+1. Run `dev-story` to implement and mark a story ready for review
 2. Check sprint-status.yaml for current story states
-      </output>
-      <action>HALT</action>
+        </output>
+        <action>HALT</action>
+      </check>
+
+      <action>Use the first story found with status "review"</action>
+      <action>Resolve story file path in {{story_dir}}</action>
+      <action>Read the COMPLETE story file</action>
     </check>
 
-    <action>Display available review stories:
-
-**Stories Ready for Review ({{result_count}} found):**
-
-{{result_story_list}}
-
-    </action>
-
-    <ask if="{{non_interactive}} == false">Select story to review (enter story key or number):</ask>
-    <action if="{{non_interactive}} == true">Auto-select first story from result_stories</action>
-
-    <action>Resolve selected story_key and find file path in {{story_dir}}</action>
-    <action>Resolve {{story_path}} and read the COMPLETE file</action>
-
-    <anchor id="verify_status" />
-
-    <action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available</action>
+    <action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata</action>
     <action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log</action>
-    <action if="Status is not one of {{allow_status_values}}">HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent).</action>
-    <action if="story cannot be read">HALT.</action>
+    <action if="story cannot be read">HALT with message: "Unable to read story file"</action>
   </step>
 
-  <step n="2" goal="Resolve context and specification inputs">
-    <action>Locate Story Context: Under Dev Agent Record → Context Reference, read referenced path(s). If missing and {{auto_discover_context}}: search {{output_folder}} for files named "story-context-{{epic_num}}.{{story_num}}*.xml"; pick the most recent.</action>
-    <action if="no context found">Continue but record a WARNING in review notes: "No Story Context found".</action>
-    <action>Locate Epic Tech Spec: If {{auto_discover_tech_spec}}, search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}); else use provided input.</action>
-    <action if="no tech spec found">Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}".</action>
-    <action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect any testing, coding standards, security, and architectural patterns.</action>
+  <step n="2" goal="Resolve story context file and specification inputs">
+    <action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.md" and use the most recent.</action>
+    <action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action>
+
+    <action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action>
+    <action if="no tech spec found">Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}"</action>
+
+    <action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns.</action>
   </step>
 
   <step n="3" goal="Detect tech stack and establish best-practice reference set">
     <action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
-    <action>If {{enable_mcp_doc_search}} and MCP servers are available → Use them to search for up-to-date best practices, security advisories, and framework-specific guidance relevant to the detected stack and the story's domain.</action>
-    <action>If MCP is unavailable or insufficient and {{enable_web_fallback}} → Perform targeted web searches and fetch authoritative references (framework docs, OWASP, language style guides). Prefer official documentation and widely-recognized standards.</action>
     <action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
   </step>
 
@@ -118,38 +110,37 @@
     <action>Save the story file.</action>
   </step>
 
-  <step n="7.5" goal="Update sprint-status based on review outcome">
+  <step n="8" goal="Update sprint status based on review outcome" tag="sprint-status">
     <action>Determine target status based on review outcome:
       - If {{outcome}} == "Approve" → target_status = "done"
       - If {{outcome}} == "Changes Requested" → target_status = "in-progress"
       - If {{outcome}} == "Blocked" → target_status = "review" (stay in review)
     </action>
 
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-      <param>action: update_story_status</param>
-      <param>story_key: {{story_key}}</param>
-      <param>new_status: {{target_status}}</param>
-      <param>validate: true</param>
-    </invoke-workflow>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read all development_status entries to find {{story_key}}</action>
+    <action>Verify current status is "review" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = {{target_status}}</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-    <check if="{{result_success}} == true">
-      <output>✅ Sprint status updated: {{result_old_status}} → {{result_new_status}}</output>
+    <check if="update successful">
+      <output>✅ Sprint status updated: review → {{target_status}}</output>
     </check>
 
-    <check if="{{result_success}} == false">
-      <output>⚠️ Could not update sprint-status: {{result_error}}
+    <check if="story key not found">
+      <output>⚠️ Could not update sprint-status: {{story_key}} not found
 
 Review was saved to story file, but sprint-status.yaml may be out of sync.
       </output>
     </check>
   </step>
 
-  <step n="8" goal="Persist action items to tasks/backlog/epic">
+  <step n="9" goal="Persist action items to tasks/backlog/epic">
     <action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
-    <action if="{{persist_action_items}} == true and 'story_tasks' in {{persist_targets}}">
+    <ask if="action items exist and 'story_tasks' in {{persist_targets}}">Add {{action_item_count}} follow-up items to story Tasks/Subtasks?</ask>
+    <action if="user confirms or no ask needed">
       Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
     </action>
-    <ask optional="true" if="{{non_interactive}} == false">Confirm adding follow-ups into story Tasks/Subtasks. Proceed?</ask>
     <action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
       If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
       Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
@@ -161,7 +152,7 @@ Review was saved to story file, but sprint-status.yaml may be out of sync.
     <action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
   </step>
 
-  <step n="9" goal="Validation and completion">
+  <step n="10" goal="Validation and completion">
     <invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.xml</invoke-task>
     <action>Report workflow completion.</action>
     <output>**✅ Story Review Complete, {user_name}!**
@@ -170,7 +161,7 @@ Review was saved to story file, but sprint-status.yaml may be out of sync.
 - Story: {{epic_num}}.{{story_num}}
 - Story Key: {{story_key}}
 - Review Outcome: {{outcome}}
-- Sprint Status: {{result_new_status}}
+- Sprint Status: {{target_status}}
 - Action Items: {{action_item_count}}
 
 **Next Steps:**

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

@@ -8,6 +8,8 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
 date: system-generated
 
 # Workflow components
@@ -20,14 +22,8 @@ template: false
 
 # Variables (can be provided by caller)
 variables:
-  story_path: "" # Explicit path to a story markdown file
-  story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
-  story_selection_limit: 10
-  allow_status_values: |
-    - Ready for Review
-    - Review
-  auto_discover_context: true
-  auto_discover_tech_spec: true
+  story_path: "" # Optional: Explicit path to story file. If not provided, finds first story with status "review"
+  story_dir: "{config_source}:dev_story_location" # Directory containing story files
   tech_spec_search_dir: "{project-root}/docs"
   tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
   arch_docs_search_dirs: |
@@ -37,9 +33,6 @@ variables:
     - architecture.md
   enable_mcp_doc_search: true # Prefer enabled MCP servers for doc/best-practice lookup
   enable_web_fallback: true # Fallback to web search/read-url if MCP not available
-  update_status_on_result: true # If true, update story Status based on review outcome
-  status_on_approve: "Review Passed"
-  status_on_changes_requested: "InProgress"
   # Persistence controls for review action items and notes
   persist_action_items: true
   # Valid targets: story_tasks, story_review_section, backlog_file, epic_followups
@@ -51,13 +44,11 @@ variables:
   backlog_file: "{project-root}/docs/backlog.md"
   update_epic_followups: true
   epic_followups_section_title: "Post-Review Follow-ups"
-  create_github_issues: false
-  non_interactive: true
 
 # Recommended inputs
 recommended_inputs:
-  - story_markdown: "Path to the story markdown file flagged Ready for Review"
-  - tech_spec: "Epic technical specification document (auto-discovered if omitted)"
-  - story_context: "Story Context XML path (auto-discovered if omitted)"
+  - story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')"
+  - tech_spec: "Epic technical specification document (auto-discovered)"
+  - story_context_file: "Story context file (.context.md) (auto-discovered)"
 
 web_bundle: false

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

@@ -12,26 +12,25 @@
 # ==================
 # Epic Status:
 #   - backlog: Epic exists in epic file but not contexted
-#   - contexted: Epic tech context created (required before drafting stories)
+#   - contexted: Next epic tech context created by *epic-tech-context (required)
 #
 # 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
-#   - in-progress: Developer actively working on implementation
-#   - review: Under SM review (via review-story workflow)
-#   - done: Story completed
+#   - drafted: Story file created in stories folder by *create-story
+#   - ready-for-dev: Draft approved and story context created by *story-ready
+#   - in-progress: Developer actively working on implementation by *dev-story
+#   - review: Implementation complete, ready for review by *review-story
+#   - done: Story completed by *story-done
 #
 # Retrospective Status:
 #   - optional: Can be completed but not required
-#   - completed: Retrospective has been done
+#   - completed: Retrospective has been done by *retrospective
 #
 # WORKFLOW NOTES:
 # ===============
 # - Epics should be 'contexted' before stories can be 'drafted'
-# - Stories can be worked in parallel if team capacity allows
-# - SM typically drafts next story after previous one is 'done' to incorporate learnings
-# - Dev moves story to 'review', SM reviews, then Dev moves to 'done'
+# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', dev reviews, then Dev moves to 'done'
 
 # EXAMPLE STRUCTURE (your actual epics/stories will replace these):
 

src/modules/bmm/workflows/4-implementation/story-context/instructions.md

@@ -1,27 +1,89 @@
 <!-- BMAD BMM Story Context Assembly Instructions (v6) -->
 
 ```xml
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Communicate all responses in {communication_language}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
-<critical>This workflow assembles a Story Context XML for a single user story by extracting ACs, tasks, relevant docs/code, interfaces, constraints, and testing guidance to support implementation.</critical>
-<critical>Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery fails, HALT and request 'story_path' or 'story_dir'.</critical>
+<critical>This workflow assembles a Story Context file for a single drafted story by extracting acceptance criteria, tasks, relevant docs/code, interfaces, constraints, and testing guidance.</critical>
+<critical>If story_path is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT.</critical>
+<critical>Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel.</critical>
 
-<critical>DOCUMENT OUTPUT: Technical XML context file. Concise, structured, project-relative paths only. User skill level ({user_skill_level}) affects conversation style ONLY, not context content.</critical>
+<critical>DOCUMENT OUTPUT: Technical context file (.context.md). Concise, structured, project-relative paths only.</critical>
 
 <workflow>
-  <step n="1" goal="Locate story and initialize output">
-    <action>If {{story_path}} provided and valid → use it; else auto-discover from {{story_dir}}.</action>
-    <action>Auto-discovery: read {{story_dir}} (dev_story_location). If invalid/missing or contains no .md files, ASK for a story file path or directory to scan.</action>
-    <action>If a directory is provided, list markdown files named "story-*.md" recursively; sort by last modified time; display top {{story_selection_limit}} with index, filename, path, modified time.</action>
-    <ask optional="true" if="{{non_interactive}} == false">"Select a story (1-{{story_selection_limit}}) or enter a path:"</ask>
-    <action>If {{non_interactive}} == true: choose the most recently modified story automatically. If none found, HALT with a clear message to provide 'story_path' or 'story_dir'. Else resolve selection into {{story_path}} and READ COMPLETE file.</action>
-    <action>Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content; parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes.</action>
-    <action>Extract user story fields (asA, iWant, soThat).</action>
-    <action>Store project root path for relative path conversion: extract from {project-root} variable.</action>
-    <action>Define path normalization function: convert any absolute path to project-relative by removing project root prefix.</action>
-    <action>Initialize output by writing template to {default_output_file}.</action>
+  <step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file and parse sections</action>
+      <action>Extract story_key from filename or story metadata</action>
+      <action>Verify Status is "drafted" - if not, HALT with message: "Story status must be 'drafted' to generate context"</action>
+    </check>
+
+    <check if="{{story_path}} is NOT provided">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely</action>
+
+      <action>Find FIRST story (reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "drafted"
+      </action>
+
+      <check if="no story with status 'drafted' found">
+        <output>📋 No drafted stories found in sprint-status.yaml
+
+All stories are either still in backlog or already marked ready/in-progress/done.
+
+**Next Steps:**
+1. Run `create-story` to draft more stories
+2. Run `sprint-planning` to refresh story tracking
+        </output>
+        <action>HALT</action>
+      </check>
+
+      <action>Use the first drafted story found</action>
+      <action>Find matching story file in {{story_dir}} using story_key pattern</action>
+      <action>Read the COMPLETE story file</action>
+    </check>
+
+    <action>Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content</action>
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes</action>
+    <action>Extract user story fields (asA, iWant, soThat)</action>
+    <template-output file="{default_output_file}">story_tasks</template-output>
+    <template-output file="{default_output_file}">acceptance_criteria</template-output>
+
+    <!-- Check if context file already exists -->
+    <action>Check if file exists at {default_output_file}</action>
+
+    <check if="context file already exists">
+      <output>⚠️ Context file already exists: {default_output_file}
+
+**What would you like to do?**
+1. **Replace** - Generate new context file (overwrites existing)
+2. **Verify** - Validate existing context file
+3. **Cancel** - Exit without changes
+      </output>
+      <ask>Choose action (replace/verify/cancel):</ask>
+
+      <check if="user chooses verify">
+        <action>GOTO validation_step</action>
+      </check>
+
+      <check if="user chooses cancel">
+        <action>HALT with message: "Context generation cancelled"</action>
+      </check>
+
+      <check if="user chooses replace">
+        <action>Continue to generate new context file</action>
+      </check>
+    </check>
+
+    <action>Store project root path for relative path conversion: extract from {project-root} variable</action>
+    <action>Define path normalization function: convert any absolute path to project-relative by removing project root prefix</action>
+    <action>Initialize output by writing template to {default_output_file}</action>
     <template-output file="{default_output_file}">as_a</template-output>
     <template-output file="{default_output_file}">i_want</template-output>
     <template-output file="{default_output_file}">so_that</template-output>
@@ -87,25 +149,51 @@
   </step>
 
   <step n="6" goal="Validate and save">
-    <action>Validate output XML structure and content.</action>
+    <anchor id="validation_step" />
+    <action>Validate output context file structure and content</action>
     <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
   </step>
 
-  <step n="7" goal="Update story status and context reference">
-    <action>Open {{story_path}}; if Status == 'Draft' then set to 'ContextReadyDraft'; otherwise leave unchanged.</action>
+  <step n="7" goal="Update story file and mark ready for dev" tag="sprint-status">
+    <action>Open {{story_path}}</action>
+    <action>Find the "Status:" line (usually at the top)</action>
+    <action>Update story file: Change Status to "ready-for-dev"</action>
     <action>Under 'Dev Agent Record' → 'Context Reference' (create if missing), add or update a list item for {default_output_file}.</action>
     <action>Save the story file.</action>
-    <output>**✅ Story Context Generated Successfully, {user_name}!**
+
+    <!-- Update sprint status to mark ready-for-dev -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "drafted" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found
+
+You may need to run sprint-planning to refresh tracking.
+      </output>
+    </check>
+
+    <output>✅ Story context generated successfully, {user_name}!
 
 **Story Details:**
-- Story ID: {{story_id}}
-- Title: {{story_title}}
-- Context File: {{default_output_file}}
+- Story: {{epic_id}}.{{story_id}} - {{story_title}}
+- Story Key: {{story_key}}
+- Context File: {default_output_file}
+- Status: drafted → ready-for-dev
+
+**Context Includes:**
+- Documentation artifacts and references
+- Existing code and interfaces
+- Dependencies and frameworks
+- Testing standards and ideas
+- Development constraints
 
 **Next Steps:**
-1. Load DEV agent (bmad/bmm/agents/dev.md)
-2. Run `dev-story` workflow to implement the story
-3. The context file will provide comprehensive implementation guidance
+1. Review the context file: {default_output_file}
+2. Run `dev-story` to implement the story
+3. Generate context for more drafted stories if needed
     </output>
   </step>
 

src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml

@@ -8,6 +8,8 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+story_path: "{config_source}:dev_story_location"
 date: system-generated
 
 # Workflow components
@@ -18,18 +20,11 @@ validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
 variables:
-  story_path: "" # Explicit story path; auto-discovered if empty
+  story_path: "" # Optional: Explicit story path. If not provided, finds first story with status "drafted"
   story_dir: "{config_source}:dev_story_location"
-  story_selection_limit: 10
-  tech_spec_search_dir: "{project-root}/docs"
-  tech_spec_glob_template: "tech-spec-epic-{{epic_id}}*.md"
-  non_interactive: true
 
 # Output configuration
-default_output_file: "{story_dir}/story-context-{{epic_id}}.{{story_id}}.xml"
-
-# Recommended inputs
-recommended_inputs:
-  - story_markdown: "Path to a story markdown file to build context for"
+# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
+default_output_file: "{story_dir}/{{story_key}}.context.md"
 
 web_bundle: false

src/modules/bmm/workflows/4-implementation/story-done/instructions.md

@@ -1,33 +1,38 @@
 # Story Approved Workflow Instructions (DEV Agent)
 
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<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>Communicate all responses in {communication_language}</critical>
 
 <workflow>
 
 <critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
 <critical>Workflow: Update story file status to Done</critical>
 
-<step n="1" goal="Find reviewed story and mark done">
+<step n="1" goal="Find reviewed story to mark done" tag="sprint-status">
 
-<action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_done</action>
+<check if="{story_path} is provided">
+  <action>Use {story_path} directly</action>
+  <action>Read COMPLETE story file and parse sections</action>
+  <action>Extract story_key from filename or story metadata</action>
+  <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done"</action>
+</check>
 
-<action>Otherwise query sprint-status for reviewed stories:</action>
+<check if="{story_path} is NOT provided">
+  <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+  <action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+  <action>Read ALL lines from beginning to end - do not skip any content</action>
+  <action>Parse the development_status section completely</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: list_stories</param>
-  <param>filter_status: review</param>
-  <param>limit: 10</param>
-</invoke-workflow>
+<action>Find FIRST story (reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "review"
+</action>
 
-<check if="{{result_count}} == 0">
-  <output>📋 No stories in review status found
+  <check if="no story with status 'review' found">
+    <output>📋 No stories with status "review" found
 
 All stories are either still in development or already done.
 
-**Options:**
+**Next Steps:**
 
 1. Run `dev-story` to implement stories
 2. Run `review-story` if stories need review first
@@ -36,49 +41,39 @@ All stories are either still in development or already done.
    <action>HALT</action>
    </check>
 
-<action>Display available reviewed stories:
+<action>Use the first reviewed story found</action>
+<action>Find matching story file in {story_dir} using story_key pattern</action>
+<action>Read the COMPLETE story file</action>
+</check>
 
-**Stories Ready to Mark Done ({{result_count}} found):**
-
-{{result_story_list}}
-
-</action>
-
-<ask>Select the story to mark as Done (enter story key or number):</ask>
-
-<action>Resolve selected story_key from user input</action>
-<action>Find matching story file in {{story_dir}} using story_key pattern</action>
-
-<anchor id="mark_done" />
-
-<action>Read the story file from resolved path</action>
-<action>Extract story_id and story_title from the file</action>
+<action>Extract story_id and story_title from the story file</action>
 
 <action>Find the "Status:" line (usually at the top)</action>
-<action>Update story file: Change Status to "Done"</action>
+<action>Update story file: Change Status to "done"</action>
 
 <action>Add completion notes to Dev Agent Record section:</action>
 <action>Find "## Dev Agent Record" section and add:
 
 ```
 ### Completion Notes
-**Completed:** {{date}}
+**Completed:** {date}
 **Definition of Done:** All acceptance criteria met, code reviewed, tests passing
 ```
 
 </action>
 
 <action>Save the story file</action>
+</step>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: update_story_status</param>
-  <param>story_key: {{story_key}}</param>
-  <param>new_status: done</param>
-  <param>validate: true</param>
-</invoke-workflow>
+<step n="2" goal="Update sprint status to done" tag="sprint-status">
+<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+<action>Find development_status key matching {story_key}</action>
+<action>Verify current status is "review" (expected previous state)</action>
+<action>Update development_status[{story_key}] = "done"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="{{result_success}} == false">
-  <output>⚠️ Story file updated, but could not update sprint-status: {{result_error}}
+<check if="story key not found in file">
+  <output>⚠️ Story file updated, but could not update sprint-status: {story_key} not found
 
 Story is marked Done in file, but sprint-status.yaml may be out of sync.
 </output>
@@ -86,20 +81,19 @@ Story is marked Done in file, but sprint-status.yaml may be out of sync.
 
 </step>
 
-<step n="2" goal="Confirm completion to user">
+<step n="3" goal="Confirm completion to user">
 
 <output>**Story Approved and Marked Done, {user_name}!**
 
-✅ Story file updated: `{{story_file}}` → Status: Done
-✅ Sprint status updated: {{result_old_status}} → {{result_new_status}}
+✅ Story file updated → Status: done
+✅ Sprint status updated: review → done
 
 **Completed Story:**
 
-- **ID:** {{story_id}}
-- **Key:** {{story_key}}
-- **Title:** {{story_title}}
-- **File:** `{{story_file}}`
-- **Completed:** {{date}}
+- **ID:** {story_id}
+- **Key:** {story_key}
+- **Title:** {story_title}
+- **Completed:** {date}
 
 **Next Steps:**
 

src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md

@@ -0,0 +1,343 @@
+# Workflow Audit Report
+
+**Workflow:** story-ready
+**Audit Date:** 2025-10-25
+**Auditor:** Audit Workflow (BMAD v6)
+**Workflow Type:** Action (status update workflow)
+**Module:** BMM (BMad Method)
+
+---
+
+## Executive Summary
+
+**Overall Status:** EXCELLENT
+
+- Critical Issues: 2
+- Important Issues: 2
+- Cleanup Recommendations: 0
+
+**Pass Rate:** 94% (66/70 checks passed)
+
+The story-ready workflow is well-structured and follows most BMAD v6 conventions. The workflow correctly uses `web_bundle: false` (intentional for local-only workflow). Critical issues relate to variable inconsistencies and undeclared config variables that are used in instructions.
+
+---
+
+## 1. Standard Config Block Validation
+
+**Status:** ⚠️ CRITICAL ISSUES FOUND
+
+### Required Variables Check:
+
+✅ `config_source` is defined and points to correct module config path
+✅ Uses {project-root} variable correctly
+✅ `output_folder` pulls from config_source
+✅ `user_name` pulls from config_source
+✅ `communication_language` pulls from config_source
+✅ `date` is set to system-generated
+✅ Standard config comment present: "Critical variables from config"
+
+### Critical Issues:
+
+#### Issue 1: Missing Config Variables in YAML
+
+**Severity:** CRITICAL
+**Location:** workflow.yaml
+
+The instructions.md file uses the following config variables that are NOT declared in workflow.yaml:
+
+1. `{user_skill_level}` - Used in line 5: "language MUST be tailored to {user_skill_level}"
+2. `{document_output_language}` - Used in line 6: "Generate all documents in {document_output_language}"
+
+**Impact:** These variables will not be resolved by the workflow engine, potentially causing confusion or errors.
+
+**Fix Required:**
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/bmad/bmm/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+user_skill_level: '{config_source}:user_skill_level' # ADD THIS
+document_output_language: '{config_source}:document_output_language' # ADD THIS
+date: system-generated
+```
+
+#### Issue 2: Variable Path Inconsistency
+
+**Severity:** CRITICAL
+**Location:** instructions.md line 3
+
+Instructions reference `{project_root}` (underscore) but workflow.yaml uses `{project-root}` (hyphen).
+
+**Current:** `<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>`
+
+**Should be:** `<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>`
+
+**Impact:** Variable will not resolve correctly, breaking the reference path.
+
+---
+
+## 2. YAML/Instruction/Template Alignment
+
+**Status:** ✅ GOOD (with minor observations)
+
+### Variables Analyzed:
+
+**Workflow.yaml variables (excluding standard config):**
+
+- `story_path` - Used in instructions ✓
+- `story_dir` - Used in instructions ✓
+
+**Variables Used in Instructions (not in YAML):**
+
+- `{{story_key}}` - Generated dynamically, output via parsing ✓
+- `{{drafted_count}}` - Generated dynamically ✓
+- `{{list_of_drafted_story_keys}}` - Generated dynamically ✓
+- `{{non_interactive}}` - Conditional logic variable (may be from agent context)
+- `{{story_file}}` - Generated dynamically ✓
+- `{{story_id}}` - Extracted from story file ✓
+- `{{story_title}}` - Extracted from story file ✓
+
+### Summary:
+
+- **Variables in YAML:** 2 (story_path, story_dir)
+- **Used in Instructions:** 2/2 (100%)
+- **Unused (Bloat):** 0
+- **Dynamic Variables:** 7 (appropriate for action workflow)
+
+**Status:** Excellent - No bloat detected, all YAML variables are used appropriately.
+
+---
+
+## 3. Config Variable Usage
+
+**Status:** ⚠️ IMPORTANT ISSUES FOUND
+
+### Communication Language Check:
+
+✅ Instructions use {communication_language} in critical header (line 5)
+⚠️ However, the instruction says "Communicate all responses in {communication_language}" but the actual workflow outputs don't explicitly enforce language adaptation
+
+### User Name Check:
+
+✅ User name properly used in final output (line 87): "**Story Marked Ready for Development, {user_name}!**"
+✅ Appropriate personalization in workflow completion message
+
+### Output Folder Check:
+
+✅ Output folder referenced correctly: `{{output_folder}}/sprint-status.yaml` (lines 18, 70)
+✅ No hardcoded paths detected
+✅ All file operations use proper variable references
+
+### Date Usage Check:
+
+✅ Date is available for agent awareness
+✅ Not used in outputs (appropriate for action workflow with no document generation)
+
+### User Skill Level Check:
+
+❌ **CRITICAL:** Variable used but not declared in workflow.yaml (line 5)
+
+### Document Output Language Check:
+
+❌ **CRITICAL:** Variable used but not declared in workflow.yaml (line 6)
+
+**Config Variable Summary:**
+
+- `communication_language`: ✅ Properly declared and used
+- `user_name`: ✅ Properly declared and used
+- `output_folder`: ✅ Properly declared and used
+- `date`: ✅ Properly declared (available but not used - appropriate)
+- `user_skill_level`: ❌ Used but NOT declared
+- `document_output_language`: ❌ Used but NOT declared
+
+---
+
+## 4. Web Bundle Validation
+
+**Status:** ✅ CORRECT (N/A)
+
+**Web Bundle Present:** No (`web_bundle: false`)
+
+**Analysis:** The workflow correctly sets `web_bundle: false`. This is appropriate because:
+
+1. This is a local-only action workflow
+2. It directly modifies files in the project (sprint-status.yaml, story files)
+3. It requires access to the specific project's file system
+4. It cannot be executed in a web bundle context where file system access is sandboxed
+
+**Finding:** The absence of web bundle configuration is **EXPECTED and CORRECT** for this workflow type.
+
+**No issues found.**
+
+---
+
+## 5. Bloat Detection
+
+**Status:** ✅ EXCELLENT
+
+### Bloat Analysis:
+
+**Total YAML Fields (excluding metadata and standard config):** 2
+
+- `story_path`
+- `story_dir`
+
+**Used Fields:** 2
+**Unused Fields:** 0
+
+**Bloat Percentage:** 0%
+
+### Hardcoded Values Check:
+
+✅ No hardcoded file paths (uses {output_folder})
+✅ No hardcoded greetings (uses {user_name})
+✅ No language-specific text (uses {communication_language})
+✅ No static dates (date variable available)
+
+### Redundant Configuration:
+
+✅ No duplicate fields between sections
+✅ No commented-out variables
+✅ No metadata repetition
+
+**Bloat Summary:** Zero bloat detected. Workflow is lean and efficient.
+
+---
+
+## 6. Template Variable Mapping
+
+**Status:** N/A (Not a document workflow)
+
+This workflow is an action workflow (status update), not a document workflow, so template validation does not apply.
+
+**No template.md file required or expected.**
+
+---
+
+## 7. Additional Quality Checks
+
+### Instruction Quality:
+
+✅ Steps properly numbered (n="1", n="2", n="3")
+✅ Each step has clear goal attribute
+✅ XML tags used correctly (<action>, <ask>, <check>, <output>, <anchor>)
+✅ Conditional logic properly implemented (if attributes)
+✅ Flow control is clear and logical
+✅ Steps are focused on single goals
+✅ Specific, actionable instructions provided
+✅ Critical sections properly marked with <critical> tags
+
+### Special Features:
+
+✅ Anchor tag used correctly: `<anchor id="mark_ready" />` (line 59)
+✅ Proper GOTO logic: "GOTO mark_ready" (line 15)
+✅ Conditional user interaction: `<ask if="{{non_interactive}} == false">` (line 53)
+✅ Auto-selection for non-interactive mode (line 54)
+
+### File References:
+
+✅ sprint-status.yaml referenced with proper variable path
+✅ Story files referenced with proper directory variable
+✅ Preservation instructions included (line 74): "Save file, preserving ALL comments and structure including STATUS DEFINITIONS"
+
+---
+
+## Recommendations
+
+### Critical (Fix Immediately)
+
+**1. Add Missing Config Variables to workflow.yaml**
+
+```yaml
+user_skill_level: '{config_source}:user_skill_level'
+document_output_language: '{config_source}:document_output_language'
+```
+
+**2. Fix Variable Path Inconsistency**
+Change line 3 in instructions.md from:
+
+```
+{project_root}/bmad/core/tasks/workflow.xml
+```
+
+to:
+
+```
+{project-root}/bmad/core/tasks/workflow.xml
+```
+
+### Important (Address Soon)
+
+**3. Clarify non_interactive Variable Source**
+The `{{non_interactive}}` variable is used in line 53-54 but not defined in workflow.yaml. Either:
+
+- Add to workflow.yaml if it's a workflow-specific variable
+- Document that it comes from agent context
+- Remove if not implemented yet
+
+**4. Document user_skill_level and document_output_language Usage**
+If these variables are standard across all BMM workflows:
+
+- Ensure they exist in the module's config.yaml
+- Add comments explaining their purpose
+- Verify they're actually needed for this action workflow (this workflow generates no documents, so document_output_language may not be necessary)
+
+### Cleanup (Nice to Have)
+
+**No cleanup recommendations** - The workflow is already lean and efficient.
+
+---
+
+## Validation Checklist
+
+Use this checklist to verify fixes:
+
+- [ ] user_skill_level added to workflow.yaml standard config block
+- [ ] document_output_language added to workflow.yaml standard config block
+- [ ] {project_root} changed to {project-root} in instructions.md line 3
+- [ ] non_interactive variable source documented or defined
+- [ ] All standard config variables present and correct
+- [ ] No unused yaml fields (bloat removed) ✓ (already clean)
+- [ ] Config variables used appropriately in instructions ✓
+- [ ] Web bundle configuration correct ✓ (intentionally false)
+- [ ] File structure follows v6 conventions ✓
+
+---
+
+## Overall Assessment
+
+### Strengths:
+
+1. **Zero bloat** - Every YAML variable is used, no waste
+2. **Clear workflow logic** - Simple, focused status update process
+3. **Proper file handling** - Uses variables for all paths, preserves file structure
+4. **Good UX** - Helpful output messages, clear next steps
+5. **Conditional logic** - Supports both interactive and non-interactive modes
+6. **Proper web_bundle setting** - Correctly set to false for local-only workflow
+
+### Weaknesses:
+
+1. Uses config variables not declared in workflow.yaml (user_skill_level, document_output_language)
+2. Variable naming inconsistency (project_root vs project-root)
+3. Unclear source of non_interactive variable
+
+### Overall Grade: **A-** (94%)
+
+This is a well-crafted workflow that follows BMAD v6 conventions closely. The critical issues are minor and easily fixable. Once the missing config variables are added and the path inconsistency is resolved, this workflow will be production-ready.
+
+---
+
+## Next Steps
+
+1. **Immediate:** Add user_skill_level and document_output_language to workflow.yaml
+2. **Immediate:** Fix {project_root} → {project-root} in instructions.md
+3. **Soon:** Clarify or remove non_interactive variable usage
+4. **Soon:** Verify these config variables exist in src/modules/bmm/config.yaml (when it's created)
+5. **Optional:** Re-run audit after fixes to verify 100% pass rate
+
+---
+
+**Audit Complete** - Generated by audit-workflow v1.0
+**Report Location:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md

src/modules/bmm/workflows/4-implementation/story-ready/instructions.md

@@ -10,19 +10,26 @@
 <critical>This workflow is run by SM agent AFTER user reviews a drafted story and confirms it's ready for development</critical>
 <critical>Simple workflow: Update story file status to Ready</critical>
 
-<step n="1" goal="Find drafted story and mark as ready">
+<step n="1" goal="Find drafted story to mark ready" tag="sprint-status">
 
 <action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready</action>
 
-<action>Otherwise query sprint-status for drafted stories:</action>
+<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Read ALL lines from beginning to end - do not skip any content</action>
+<action>Parse the development_status section completely</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: list_stories</param>
-  <param>filter_status: drafted</param>
-  <param>limit: 10</param>
-</invoke-workflow>
+<action>Find ALL stories (reading in order from top to bottom) where:
 
-<check if="{{result_count}} == 0">
+- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+- Status value equals "drafted"
+  </action>
+
+<action>Collect up to 10 drafted story keys in order (limit for display purposes)</action>
+<action>Count total drafted stories found</action>
+
+<check if="no drafted stories found">
   <output>📋 No drafted stories found in sprint-status.yaml
 
 All stories are either still in backlog or already marked ready/in-progress/done.
@@ -37,14 +44,14 @@ All stories are either still in backlog or already marked ready/in-progress/done
 
 <action>Display available drafted stories:
 
-**Drafted Stories Available ({{result_count}} found):**
+**Drafted Stories Available ({{drafted_count}} found):**
 
-{{result_story_list}}
+{{list_of_drafted_story_keys}}
 
 </action>
 
 <ask if="{{non_interactive}} == false">Select the drafted story to mark as Ready (enter story key or number):</ask>
-<action if="{{non_interactive}} == true">Auto-select first story from result_stories</action>
+<action if="{{non_interactive}} == true">Auto-select first story from the list</action>
 
 <action>Resolve selected story_key from user input or auto-selection</action>
 <action>Find matching story file in {{story_dir}} using story_key pattern</action>
@@ -55,18 +62,19 @@ All stories are either still in backlog or already marked ready/in-progress/done
 <action>Extract story_id and story_title from the file</action>
 
 <action>Find the "Status:" line (usually at the top)</action>
-<action>Update story file: Change Status to "Ready"</action>
+<action>Update story file: Change Status to "ready-for-dev"</action>
 <action>Save the story file</action>
+</step>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: update_story_status</param>
-  <param>story_key: {{story_key}}</param>
-  <param>new_status: ready-for-dev</param>
-  <param>validate: true</param>
-</invoke-workflow>
+<step n="2" goal="Update sprint status to ready-for-dev" tag="sprint-status">
+<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Find development_status key matching {{story_key}}</action>
+<action>Verify current status is "drafted" (expected previous state)</action>
+<action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="{{result_success}} == false">
-  <output>⚠️ Story file updated, but could not update sprint-status: {{result_error}}
+<check if="story key not found in file">
+  <output>⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found
 
 You may need to run sprint-planning to refresh tracking.
 </output>
@@ -74,12 +82,12 @@ You may need to run sprint-planning to refresh tracking.
 
 </step>
 
-<step n="2" goal="Confirm completion to user">
+<step n="3" goal="Confirm completion to user">
 
 <output>**Story Marked Ready for Development, {user_name}!**
 
-✅ Story file updated: `{{story_file}}` → Status: Ready
-✅ Sprint status updated: {{result_old_status}} → {{result_new_status}}
+✅ Story file updated: `{{story_file}}` → Status: ready-for-dev
+✅ Sprint status updated: drafted → ready-for-dev
 
 **Story Details:**
 
@@ -87,7 +95,7 @@ You may need to run sprint-planning to refresh tracking.
 - **Key:** {{story_key}}
 - **Title:** {{story_title}}
 - **File:** `{{story_file}}`
-- **Status:** Ready for development
+- **Status:** ready-for-dev
 
 **Next Steps:**
 

src/modules/bmm/workflows/helpers/sprint-status/README.md

@@ -1,292 +0,0 @@
-# Sprint Status Helper
-
-**Purpose:** Utility workflow for reading and updating `sprint-status.yaml` tracking file used across Phase 4 implementation workflows.
-
-**Location:** `src/modules/bmm/workflows/helpers/sprint-status/`
-
-**Status File:** `{output_folder}/sprint-status.yaml` (created by sprint-planning workflow)
-
----
-
-## Quick Reference
-
-### Usage Pattern
-
-```xml
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: ACTION_NAME</param>
-  <param>PARAM_NAME: value</param>
-  <!-- Optional params -->
-</invoke-workflow>
-
-<!-- Use returned variables -->
-<action>Do something with {{result_*}} variables</action>
-```
-
----
-
-## Available Actions
-
-### Read Operations
-
-| Action                | Purpose                      | Key Parameters                          | Key Returns                                                                   |
-| --------------------- | ---------------------------- | --------------------------------------- | ----------------------------------------------------------------------------- |
-| `get_next_story`      | Find first story by status   | `filter_status`, `epic_filter`          | `result_found`, `result_story_key`, `result_epic_id`, `result_story_id`       |
-| `list_stories`        | Get all matching stories     | `filter_status`, `epic_filter`, `limit` | `result_count`, `result_stories`, `result_story_list`                         |
-| `get_story_status`    | Check story's current status | `story_key`                             | `result_found`, `result_status`                                               |
-| `get_epic_status`     | Check epic status + stats    | `epic_id`                               | `result_status`, `result_story_count`, `result_done_count`, `result_complete` |
-| `check_epic_complete` | Verify all stories done      | `epic_id`                               | `result_complete`, `result_pending_stories`                                   |
-| `get_metadata`        | Get project info from file   | none                                    | `result_project`, `result_story_location`, `result_generated_date`            |
-| `get_file_path`       | Get file location            | none                                    | `result_file_path`, `result_exists`                                           |
-
-### Write Operations
-
-| Action                   | Purpose                | Key Parameters                        | Key Returns                                                |
-| ------------------------ | ---------------------- | ------------------------------------- | ---------------------------------------------------------- |
-| `update_story_status`    | Change story status    | `story_key`, `new_status`, `validate` | `result_success`, `result_old_status`, `result_new_status` |
-| `update_epic_status`     | Mark epic as contexted | `epic_id`, `new_status`               | `result_success`, `result_old_status`, `result_new_status` |
-| `complete_retrospective` | Mark epic retro done   | `epic_id`                             | `result_success`, `result_retro_key`                       |
-
-### Utility Operations
-
-| Action                | Purpose                         | Key Parameters             | Key Returns                                               |
-| --------------------- | ------------------------------- | -------------------------- | --------------------------------------------------------- |
-| `validate_transition` | Check if status change is legal | `from_status`, `to_status` | `result_valid`, `result_message`, `result_suggested_path` |
-
----
-
-## Status Flow Reference
-
-**Epic Status:**
-
-```
-backlog → contexted
-```
-
-**Story Status:**
-
-```
-backlog → drafted → ready-for-dev → in-progress → review → done
-         ↑_________ Corrections allowed (backward movement) ________↑
-```
-
-**Retrospective Status:**
-
-```
-optional ↔ completed
-```
-
----
-
-## Common Patterns
-
-### Pattern 1: Find and Update Next Story
-
-```xml
-<!-- Find next backlog story -->
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: get_next_story</param>
-  <param>filter_status: backlog</param>
-</invoke-workflow>
-
-<check if="{{result_found}} == true">
-  <action>Work on story: {{result_story_key}}</action>
-
-  <!-- Update status after work -->
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-    <param>action: update_story_status</param>
-    <param>story_key: {{result_story_key}}</param>
-    <param>new_status: drafted</param>
-  </invoke-workflow>
-</check>
-
-<check if="{{result_found}} == false">
-  <output>No backlog stories available</output>
-</check>
-```
-
-### Pattern 2: List Stories for User Selection
-
-```xml
-<!-- Get all drafted stories -->
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: list_stories</param>
-  <param>filter_status: drafted</param>
-  <param>limit: 10</param>
-</invoke-workflow>
-
-<check if="{{result_count}} > 0">
-  <output>Available drafted stories ({{result_count}} found):
-{{result_story_list}}
-  </output>
-  <ask>Select a story to work on:</ask>
-</check>
-```
-
-### Pattern 3: Check Epic Completion Before Retrospective
-
-```xml
-<!-- Verify epic is complete -->
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: check_epic_complete</param>
-  <param>epic_id: 1</param>
-</invoke-workflow>
-
-<check if="{{result_complete}} == true">
-  <output>Epic 1 is complete! Ready for retrospective.</output>
-
-  <!-- Mark retrospective as completed -->
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-    <param>action: complete_retrospective</param>
-    <param>epic_id: 1</param>
-  </invoke-workflow>
-</check>
-
-<check if="{{result_complete}} == false">
-  <output>Epic 1 has {{result_total_stories - result_done_stories}} pending stories:
-{{result_pending_stories}}
-  </output>
-</check>
-```
-
-### Pattern 4: Validate Before Update
-
-```xml
-<!-- Check if transition is legal first -->
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: validate_transition</param>
-  <param>from_status: drafted</param>
-  <param>to_status: in-progress</param>
-</invoke-workflow>
-
-<check if="{{result_valid}} == false">
-  <output>Cannot transition directly from drafted to in-progress.
-{{result_suggested_path}}
-  </output>
-  <action>HALT</action>
-</check>
-```
-
-### Pattern 5: Mark Epic Contexted
-
-```xml
-<!-- After creating epic tech context -->
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
-  <param>action: update_epic_status</param>
-  <param>epic_id: {{epic_num}}</param>
-  <param>new_status: contexted</param>
-</invoke-workflow>
-```
-
----
-
-## Return Variables
-
-**All actions return:**
-
-- `result_success`: `true` | `false`
-- `result_error`: Error message (if `result_success == false`)
-
-**Common additional returns:**
-
-- `result_found`: `true` | `false` (for query operations)
-- `result_status`: Current status value
-- `result_old_status`: Previous status (for updates)
-- `result_new_status`: Updated status (for updates)
-- `result_story_key`: Story key like "1-1-story-name"
-- `result_epic_id`: Epic number extracted from key
-- `result_story_id`: Story number extracted from key
-
----
-
-## Error Handling
-
-**File Not Found:**
-
-```xml
-<check if="{{result_error}} == 'file_not_found'">
-  <output>Sprint status file not found.
-Run sprint-planning workflow first to initialize tracking.
-  </output>
-  <action>HALT</action>
-</check>
-```
-
-**Story Not Found:**
-
-```xml
-<check if="{{result_found}} == false">
-  <output>Story {{story_key}} not found in sprint-status.yaml.
-Run sprint-planning to refresh tracking.
-  </output>
-</check>
-```
-
-**Invalid Transition:**
-
-```xml
-<check if="{{result_success}} == false AND {{result_validation_message}} != ''">
-  <output>{{result_error}}
-{{result_validation_message}}
-  </output>
-</check>
-```
-
----
-
-## Options
-
-| Parameter     | Default | Description                                                |
-| ------------- | ------- | ---------------------------------------------------------- |
-| `validate`    | `true`  | Enforce legal status transitions for `update_story_status` |
-| `dry_run`     | `false` | Test update without saving (for debugging)                 |
-| `show_output` | `true`  | Helper displays status messages (✅/❌/📋)                 |
-
----
-
-## Integration Checklist
-
-When adding sprint-status helper to a workflow:
-
-- [ ] Add `sprint_status_file` variable to workflow.yaml if needed
-- [ ] Use `invoke-workflow` with correct action parameter
-- [ ] Check `result_success` and `result_found` before proceeding
-- [ ] Handle `result_error == 'file_not_found'` case
-- [ ] Use returned `result_*` variables in workflow logic
-- [ ] Update status at appropriate workflow steps
-
----
-
-## Workflow Integration Map
-
-| Workflow              | Actions Used                                      | When                                        |
-| --------------------- | ------------------------------------------------- | ------------------------------------------- |
-| **epic-tech-context** | `get_epic_status`<br>`update_epic_status`         | Check epic exists → Mark contexted          |
-| **create-story**      | `get_next_story`<br>`update_story_status`         | Find backlog → Mark drafted                 |
-| **story-ready**       | `list_stories`<br>`update_story_status`           | List drafted → Mark ready-for-dev           |
-| **story-context**     | `get_next_story`                                  | Find drafted (read-only)                    |
-| **dev-story**         | `get_next_story`<br>`update_story_status` (2x)    | Find ready → Mark in-progress → Mark review |
-| **review-story**      | `list_stories`<br>`update_story_status`           | List review → Update based on outcome       |
-| **story-done**        | `list_stories`<br>`update_story_status`           | List review → Mark done                     |
-| **retrospective**     | `check_epic_complete`<br>`complete_retrospective` | Verify complete → Mark retro done           |
-
----
-
-## Notes
-
-- **Source of Truth:** File system is authoritative. Sprint-planning regenerates from epics + file detection.
-- **Refresh Strategy:** Re-run sprint-planning anytime to resync tracking with actual files.
-- **Concurrency:** Not designed for concurrent access. Single-user CLI workflow execution.
-- **Alpha Status:** No backward compatibility. Re-run sprint-planning with latest version before using.
-
----
-
-## Examples in Context
-
-See individual workflow instructions in `src/modules/bmm/workflows/4-implementation/` for integration examples.
-
-**Helper Files:**
-
-- `workflow.yaml` - Interface definition
-- `instructions.md` - Action implementation logic
-- `README.md` - This file

src/modules/bmm/workflows/helpers/sprint-status/instructions.md

@@ -1,542 +0,0 @@
-# Sprint Status Helper - Workflow Instructions
-
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language}</critical>
-<critical>This is a HELPER workflow - it performs operations on sprint-status.yaml and returns results to the calling workflow via variables</critical>
-
-<workflow>
-
-<step n="1" goal="Validate action parameter and load sprint status file">
-  <action>Check if {{action}} parameter is provided and not empty</action>
-
-  <check if="{{action}} is empty or not provided">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "Action parameter is required. See workflow.yaml for supported actions."</action>
-    <output>❌ Sprint Status Helper Error: No action specified</output>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Check if sprint status file exists at {status_file}</action>
-
-  <check if="file does not exist">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "file_not_found"</action>
-    <action>Set result_file_path = {status_file}</action>
-
-    <check if="{{show_output}} == true">
-      <output>❌ Sprint status file not found at: {status_file}
-
-Please run the sprint-planning workflow first to initialize tracking.
-</output>
-</check>
-
-    <action>HALT - return to calling workflow with error</action>
-
-  </check>
-
-<action>Read complete sprint status file from {status_file}</action>
-<action>Parse YAML structure into memory</action>
-<action>Extract metadata fields: generated, project, project_key, tracking_system, story_location</action>
-<action>Extract development_status map: all epic and story keys with their current status values</action>
-
-  <check if="YAML parsing fails">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "Invalid YAML format in sprint-status.yaml"</action>
-    <output>❌ Sprint status file is malformed. Run sprint-planning to regenerate.</output>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-</step>
-
-<step n="2" goal="Dispatch to action handler">
-  <action>Route to appropriate action handler based on {{action}} value</action>
-
-  <check if="{{action}} == 'get_next_story'">
-    <goto step="3">Get Next Story</goto>
-  </check>
-
-  <check if="{{action}} == 'list_stories'">
-    <goto step="4">List Stories</goto>
-  </check>
-
-  <check if="{{action}} == 'get_story_status'">
-    <goto step="5">Get Story Status</goto>
-  </check>
-
-  <check if="{{action}} == 'get_epic_status'">
-    <goto step="6">Get Epic Status</goto>
-  </check>
-
-  <check if="{{action}} == 'check_epic_complete'">
-    <goto step="7">Check Epic Complete</goto>
-  </check>
-
-  <check if="{{action}} == 'update_story_status'">
-    <goto step="8">Update Story Status</goto>
-  </check>
-
-  <check if="{{action}} == 'update_epic_status'">
-    <goto step="9">Update Epic Status</goto>
-  </check>
-
-  <check if="{{action}} == 'complete_retrospective'">
-    <goto step="10">Complete Retrospective</goto>
-  </check>
-
-  <check if="{{action}} == 'validate_transition'">
-    <goto step="11">Validate Transition</goto>
-  </check>
-
-  <check if="{{action}} == 'get_metadata'">
-    <goto step="12">Get Metadata</goto>
-  </check>
-
-  <check if="{{action}} == 'get_file_path'">
-    <goto step="13">Get File Path</goto>
-  </check>
-
-  <check if="action does not match any handler">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "Unknown action: {{action}}"</action>
-    <output>❌ Unknown action: {{action}}
-
-Supported actions: get_next_story, list_stories, get_story_status, get_epic_status, check_epic_complete, update_story_status, update_epic_status, complete_retrospective, validate_transition, get_metadata, get_file_path
-</output>
-<action>HALT - return to calling workflow with error</action>
-</check>
-</step>
-
-<!-- ========================================
-     ACTION HANDLERS - READ OPERATIONS
-     ======================================== -->
-
-<step n="3" goal="Action: get_next_story">
-  <action>Filter development_status map to find stories (keys matching pattern: number-number-name, not epic-X or epic-X-retrospective)</action>
-
-  <check if="{{filter_status}} is provided and not empty">
-    <action>Further filter to only stories where status == {{filter_status}}</action>
-  </check>
-
-  <check if="{{epic_filter}} is provided and not empty">
-    <action>Further filter to only stories from epic {{epic_filter}} (keys starting with "{{epic_filter}}-")</action>
-  </check>
-
-<action>From filtered list, select the FIRST story (stories are in order in the file)</action>
-
-  <check if="story found">
-    <action>Extract story key (e.g., "1-1-user-authentication")</action>
-    <action>Parse epic_id from key (first number before dash)</action>
-    <action>Parse story_id from key (second number after first dash)</action>
-    <action>Get current status value from development_status map</action>
-
-    <action>Set result_found = true</action>
-    <action>Set result_story_key = extracted story key</action>
-    <action>Set result_story_status = current status</action>
-    <action>Set result_epic_id = extracted epic id</action>
-    <action>Set result_story_id = extracted story id</action>
-    <action>Set result_success = true</action>
-
-    <check if="{{show_output}} == true">
-      <output>📋 Next {{filter_status}} story: {{result_story_key}} (Epic {{result_epic_id}}, Story {{result_story_id}})</output>
-    </check>
-
-  </check>
-
-  <check if="no story found">
-    <action>Set result_found = false</action>
-    <action>Set result_story_key = ""</action>
-    <action>Set result_story_status = ""</action>
-    <action>Set result_epic_id = ""</action>
-    <action>Set result_story_id = ""</action>
-    <action>Set result_success = true</action>
-
-    <check if="{{show_output}} == true">
-      <output>ℹ️ No {{filter_status}} stories found{{#if epic_filter}} in {{epic_filter}}{{/if}}</output>
-    </check>
-
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="4" goal="Action: list_stories">
-  <action>Filter development_status map to find all stories (keys matching pattern: number-number-name)</action>
-
-  <check if="{{filter_status}} is provided and not empty">
-    <action>Further filter to only stories where status == {{filter_status}}</action>
-  </check>
-
-  <check if="{{epic_filter}} is provided and not empty">
-    <action>Further filter to only stories from epic {{epic_filter}}</action>
-  </check>
-
-<action>Collect all matching story keys into an array</action>
-<action>Apply limit: if more than {{limit}} stories, take first {{limit}} only</action>
-
-<action>Set result_count = number of stories found (before limit applied)</action>
-<action>Set result_stories = array of story keys ["1-1-auth", "1-2-nav", ...]</action>
-<action>Set result_story_list = comma-separated string of keys "1-1-auth, 1-2-nav, ..."</action>
-<action>Set result_success = true</action>
-
-  <check if="{{show_output}} == true">
-    <output>📋 Found {{result_count}} {{filter_status}} stories{{#if epic_filter}} in {{epic_filter}}{{/if}}{{#if result_count > limit}} (showing first {{limit}}){{/if}}</output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="5" goal="Action: get_story_status">
-  <action>Validate {{story_key}} is provided</action>
-
-  <check if="{{story_key}} is empty">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "story_key parameter required for get_story_status"</action>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Look up {{story_key}} in development_status map</action>
-
-  <check if="story key found">
-    <action>Get status value from map</action>
-    <action>Set result_found = true</action>
-    <action>Set result_status = status value</action>
-    <action>Set result_success = true</action>
-
-    <check if="{{show_output}} == true">
-      <output>📋 Story {{story_key}} status: {{result_status}}</output>
-    </check>
-
-  </check>
-
-  <check if="story key not found">
-    <action>Set result_found = false</action>
-    <action>Set result_status = ""</action>
-    <action>Set result_success = true</action>
-
-    <check if="{{show_output}} == true">
-      <output>⚠️ Story {{story_key}} not found in sprint-status.yaml</output>
-    </check>
-
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="6" goal="Action: get_epic_status">
-  <action>Validate {{epic_id}} is provided</action>
-
-  <check if="{{epic_id}} is empty">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "epic_id parameter required for get_epic_status"</action>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Construct epic key: "epic-{{epic_id}}" (e.g., "epic-1")</action>
-<action>Look up epic key in development_status map</action>
-
-  <check if="epic key found">
-    <action>Get status value from map</action>
-
-    <action>Count total stories in this epic (keys starting with "{{epic_id}}-")</action>
-    <action>Count done stories in this epic (keys starting with "{{epic_id}}-" where status == "done")</action>
-    <action>Determine if complete: true if done_count == story_count AND all stories exist</action>
-
-    <action>Set result_found = true</action>
-    <action>Set result_status = epic status value</action>
-    <action>Set result_story_count = total story count</action>
-    <action>Set result_done_count = done story count</action>
-    <action>Set result_complete = true/false based on completion check</action>
-    <action>Set result_success = true</action>
-
-    <check if="{{show_output}} == true">
-      <output>📋 Epic {{epic_id}} status: {{result_status}} ({{result_done_count}}/{{result_story_count}} stories done)</output>
-    </check>
-
-  </check>
-
-  <check if="epic key not found">
-    <action>Set result_found = false</action>
-    <action>Set result_status = ""</action>
-    <action>Set result_story_count = 0</action>
-    <action>Set result_done_count = 0</action>
-    <action>Set result_complete = false</action>
-    <action>Set result_success = true</action>
-
-    <check if="{{show_output}} == true">
-      <output>⚠️ Epic {{epic_id}} not found in sprint-status.yaml</output>
-    </check>
-
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="7" goal="Action: check_epic_complete">
-  <action>Validate {{epic_id}} is provided</action>
-
-  <check if="{{epic_id}} is empty">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "epic_id parameter required for check_epic_complete"</action>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Find all stories for epic {{epic_id}} (keys starting with "{{epic_id}}-")</action>
-<action>Count total stories found</action>
-<action>Count stories with status == "done"</action>
-<action>Collect list of pending stories (status != "done")</action>
-
-<action>Determine complete: true if all stories are done, false otherwise</action>
-
-<action>Set result_complete = true/false</action>
-<action>Set result_total_stories = total count</action>
-<action>Set result_done_stories = done count</action>
-<action>Set result_pending_stories = array of pending story keys</action>
-<action>Set result_success = true</action>
-
-  <check if="{{show_output}} == true">
-    <output>📊 Epic {{epic_id}}: {{result_done_stories}}/{{result_total_stories}} stories complete{{#if result_complete}} ✅{{/if}}</output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<!-- ========================================
-     ACTION HANDLERS - WRITE OPERATIONS
-     ======================================== -->
-
-<step n="8" goal="Action: update_story_status">
-  <action>Validate {{story_key}} is provided</action>
-  <action>Validate {{new_status}} is provided</action>
-
-  <check if="{{story_key}} is empty OR {{new_status}} is empty">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "story_key and new_status parameters required for update_story_status"</action>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Look up {{story_key}} in development_status map</action>
-
-  <check if="story key not found">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "Story {{story_key}} not found in sprint-status.yaml"</action>
-
-    <check if="{{show_output}} == true">
-      <output>❌ Story {{story_key}} not found in tracking file</output>
-    </check>
-
-    <action>HALT - return to calling workflow with error</action>
-
-  </check>
-
-<action>Get current status (old_status) from map</action>
-
-  <check if="{{validate}} == true">
-    <action>Check if transition from old_status → {{new_status}} is legal</action>
-
-    <action>Define legal transitions:
-      - backlog → drafted
-      - drafted → ready-for-dev OR drafted (re-edit)
-      - ready-for-dev → in-progress OR drafted (corrections)
-      - in-progress → review OR in-progress (continue work)
-      - review → done OR in-progress (corrections needed)
-      - done → done (idempotent)
-    </action>
-
-    <check if="transition is NOT legal">
-      <action>Set result_success = false</action>
-      <action>Set result_error = "Invalid transition: {{old_status}} → {{new_status}}"</action>
-      <action>Set result_validation_message = "Stories must follow workflow: backlog → drafted → ready-for-dev → in-progress → review → done"</action>
-
-      <check if="{{show_output}} == true">
-        <output>❌ Invalid status transition for {{story_key}}: {{old_status}} → {{new_status}}
-
-Legal workflow path: backlog → drafted → ready-for-dev → in-progress → review → done
-Stories can move backward for corrections (e.g., review → in-progress)
-</output>
-</check>
-
-      <action>HALT - return to calling workflow with error</action>
-    </check>
-
-  </check>
-
-  <check if="{{dry_run}} == false">
-    <action>Update development_status map: set {{story_key}} = {{new_status}}</action>
-    <action>Write updated YAML back to {status_file}</action>
-    <action>Preserve all metadata and comments in file</action>
-    <action>Maintain story order in development_status section</action>
-  </check>
-
-<action>Set result_success = true</action>
-<action>Set result_old_status = old_status</action>
-<action>Set result_new_status = {{new_status}}</action>
-<action>Set result_story_key = {{story_key}}</action>
-
-  <check if="{{show_output}} == true">
-    <output>✅ Updated sprint-status: {{story_key}} → {{new_status}}{{#if dry_run}} (DRY RUN - not saved){{/if}}</output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="9" goal="Action: update_epic_status">
-  <action>Validate {{epic_id}} is provided</action>
-  <action>Validate {{new_status}} is provided</action>
-
-  <check if="{{epic_id}} is empty OR {{new_status}} is empty">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "epic_id and new_status parameters required for update_epic_status"</action>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Construct epic key: "epic-{{epic_id}}"</action>
-<action>Look up epic key in development_status map</action>
-
-  <check if="epic key not found">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "Epic {{epic_id}} not found in sprint-status.yaml"</action>
-
-    <check if="{{show_output}} == true">
-      <output>❌ Epic {{epic_id}} not found in tracking file</output>
-    </check>
-
-    <action>HALT - return to calling workflow with error</action>
-
-  </check>
-
-<action>Get current status (old_status) from map</action>
-
-  <check if="{{dry_run}} == false">
-    <action>Update development_status map: set "epic-{{epic_id}}" = {{new_status}}</action>
-    <action>Write updated YAML back to {status_file}</action>
-  </check>
-
-<action>Set result_success = true</action>
-<action>Set result_old_status = old_status</action>
-<action>Set result_new_status = {{new_status}}</action>
-
-  <check if="{{show_output}} == true">
-    <output>✅ Updated sprint-status: epic-{{epic_id}} → {{new_status}}{{#if dry_run}} (DRY RUN - not saved){{/if}}</output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="10" goal="Action: complete_retrospective">
-  <action>Validate {{epic_id}} is provided</action>
-
-  <check if="{{epic_id}} is empty">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "epic_id parameter required for complete_retrospective"</action>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Construct retrospective key: "epic-{{epic_id}}-retrospective"</action>
-<action>Look up retrospective key in development_status map</action>
-
-  <check if="retrospective key not found">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "Retrospective for epic {{epic_id}} not found in sprint-status.yaml"</action>
-
-    <check if="{{show_output}} == true">
-      <output>❌ Epic {{epic_id}} retrospective not found in tracking file</output>
-    </check>
-
-    <action>HALT - return to calling workflow with error</action>
-
-  </check>
-
-<action>Get current status (old_status) from map</action>
-
-  <check if="{{dry_run}} == false">
-    <action>Update development_status map: set "epic-{{epic_id}}-retrospective" = "completed"</action>
-    <action>Write updated YAML back to {status_file}</action>
-  </check>
-
-<action>Set result_success = true</action>
-<action>Set result_retro_key = "epic-{{epic_id}}-retrospective"</action>
-<action>Set result_old_status = old_status</action>
-<action>Set result_new_status = "completed"</action>
-
-  <check if="{{show_output}} == true">
-    <output>✅ Updated sprint-status: epic-{{epic_id}}-retrospective → completed{{#if dry_run}} (DRY RUN - not saved){{/if}}</output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<!-- ========================================
-     ACTION HANDLERS - UTILITY OPERATIONS
-     ======================================== -->
-
-<step n="11" goal="Action: validate_transition">
-  <action>Validate {{from_status}} and {{to_status}} are provided</action>
-
-  <check if="{{from_status}} is empty OR {{to_status}} is empty">
-    <action>Set result_success = false</action>
-    <action>Set result_error = "from_status and to_status parameters required for validate_transition"</action>
-    <action>HALT - return to calling workflow with error</action>
-  </check>
-
-<action>Check if transition {{from_status}} → {{to_status}} is legal</action>
-
-<action>Legal transitions for stories: - backlog → drafted: ✓ - drafted → ready-for-dev: ✓ - drafted → drafted: ✓ (re-edit) - ready-for-dev → in-progress: ✓ - ready-for-dev → drafted: ✓ (corrections) - in-progress → review: ✓ - in-progress → in-progress: ✓ (continue) - review → done: ✓ - review → in-progress: ✓ (corrections needed) - done → done: ✓ (idempotent) - All other transitions: ✗
-</action>
-
-  <check if="transition is legal">
-    <action>Set result_valid = true</action>
-    <action>Set result_message = "Legal transition: {{from_status}} → {{to_status}}"</action>
-    <action>Set result_success = true</action>
-  </check>
-
-  <check if="transition is NOT legal">
-    <action>Set result_valid = false</action>
-    <action>Set result_message = "Invalid transition: {{from_status}} → {{to_status}}"</action>
-    <action>Set result_suggested_path = "backlog → drafted → ready-for-dev → in-progress → review → done"</action>
-    <action>Set result_success = true</action>
-  </check>
-
-  <check if="{{show_output}} == true">
-    <output>{{#if result_valid}}✅{{else}}❌{{/if}} {{result_message}}</output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="12" goal="Action: get_metadata">
-  <action>Extract metadata from loaded sprint status file</action>
-
-<action>Set result_project = metadata.project value</action>
-<action>Set result_project_key = metadata.project_key value</action>
-<action>Set result_tracking_system = metadata.tracking_system value</action>
-<action>Set result_story_location = metadata.story_location value</action>
-<action>Set result_generated_date = metadata.generated value</action>
-<action>Set result_success = true</action>
-
-  <check if="{{show_output}} == true">
-    <output>📋 Sprint Status Metadata:
-- Project: {{result_project}}
-- Tracking: {{result_tracking_system}}
-- Stories: {{result_story_location}}
-- Generated: {{result_generated_date}}
-    </output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-<step n="13" goal="Action: get_file_path">
-  <action>This action was already completed in step 1 when we loaded the file</action>
-
-<action>Set result_file_path = {status_file}</action>
-<action>Set result_exists = true (because we successfully loaded it in step 1)</action>
-<action>Set result_success = true</action>
-
-  <check if="{{show_output}} == true">
-    <output>📁 Sprint status file: {{result_file_path}}</output>
-  </check>
-
-<action>COMPLETE - return to calling workflow</action>
-</step>
-
-</workflow>

src/modules/bmm/workflows/helpers/sprint-status/workflow.yaml

@@ -1,53 +0,0 @@
-name: sprint-status
-description: "Helper workflow for reading and updating sprint-status.yaml tracking file. Provides query and update operations for Phase 4 implementation workflows."
-author: "BMad Method"
-
-# Critical variables
-config_source: "{project-root}/bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
-communication_language: "{config_source}:communication_language"
-date: system-generated
-
-# Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/helpers/sprint-status"
-instructions: "{installed_path}/instructions.md"
-template: false
-
-# Sprint status file location
-status_file: "{output_folder}/sprint-status.yaml"
-
-# Input parameters (provided by calling workflow)
-# Action is REQUIRED - all others depend on the action type
-variables:
-  action: "" # REQUIRED: get_next_story | list_stories | get_story_status | get_epic_status | check_epic_complete | update_story_status | update_epic_status | complete_retrospective | validate_transition | get_metadata | get_file_path
-
-  # Query parameters
-  story_key: "" # For: get_story_status, update_story_status
-  epic_id: "" # For: get_epic_status, check_epic_complete, update_epic_status, complete_retrospective
-  filter_status: "" # For: get_next_story, list_stories - values: backlog | drafted | ready-for-dev | in-progress | review | done
-  epic_filter: "" # For: get_next_story, list_stories - limit to specific epic (e.g., "epic-1")
-  limit: 10 # For: list_stories - max results to return
-
-  # Update parameters
-  new_status: "" # For: update_story_status, update_epic_status - target status
-
-  # Validation parameters
-  from_status: "" # For: validate_transition
-  to_status: "" # For: validate_transition
-
-  # Options
-  validate: true # For: update_story_status - enforce legal transitions
-  dry_run: false # For: update operations - test without saving
-  show_output: true # Show helper messages (caller can override)
-
-# Output variables (returned to calling workflow)
-# All results are prefixed with result_* for clarity
-# Specific variables depend on action - see instructions.md for details
-
-# Common returns (most actions):
-#   result_success: true | false
-#   result_error: error message (if failed)
-#
-# Action-specific returns documented in instructions.md
-
-web_bundle: false

src/modules/bmm/workflows/workflow-status/README.md

@@ -70,8 +70,6 @@ PROJECT_LEVEL: 2
 FIELD_TYPE: greenfield
 CURRENT_PHASE: 2-Planning
 CURRENT_WORKFLOW: prd
-TODO_STORY: story-1.2.md
-IN_PROGRESS_STORY: story-1.1.md
 NEXT_ACTION: Continue PRD
 NEXT_COMMAND: prd
 NEXT_AGENT: pm
@@ -79,9 +77,9 @@ NEXT_AGENT: pm
 
 Any agent can instantly grep what they need:
 
-- SM: `grep 'TODO_STORY:' status.md`
-- DEV: `grep 'IN_PROGRESS_STORY:' status.md`
 - Any: `grep 'NEXT_ACTION:' status.md`
+- Any: `grep 'CURRENT_PHASE:' status.md`
+- Any: `grep 'NEXT_COMMAND:' status.md`
 
 ## Project Levels
 
@@ -140,7 +138,7 @@ The init workflow intelligently detects:
 
 ```
 Agent: workflow-status
-Result: "TODO: story-1.2.md, Next: create-story"
+Result: "Current: Phase 2 - Planning, Next: prd (pm agent)"
 ```
 
 ### New Project Setup
@@ -208,12 +206,17 @@ Instead of complex if/else logic:
 
 Other workflows read the status to coordinate:
 
-- `create-story` reads TODO_STORY
-- `dev-story` reads IN_PROGRESS_STORY
 - Any workflow can check CURRENT_PHASE
+- Workflows can verify prerequisites are complete
 - All agents can ask "what should I do?"
 
-The status file is the single source of truth for project state and the hub that keeps all agents synchronized.
+**Phase 4 (Implementation):**
+
+- workflow-status only tracks sprint-planning completion
+- After sprint-planning, all story/epic tracking happens in the sprint plan output file
+- Phase 4 workflows do NOT read/write workflow-status (except sprint-planning for prerequisite verification)
+
+The status file is the single source of truth for Phases 1-3 and the hub that keeps all agents synchronized.
 
 ## Benefits
 

src/modules/bmm/workflows/workflow-status/init/instructions.md

@@ -154,21 +154,15 @@ Is that correct? (y/n or tell me what's different)</ask>
 <template-output>phase_2_complete</template-output>
 <template-output>phase_3_complete</template-output>
 <template-output>phase_4_complete</template-output>
-<template-output>ordered_story_list = "[]"</template-output>
-<template-output>todo_story</template-output>
-<template-output>todo_title</template-output>
-<template-output>in_progress_story</template-output>
-<template-output>in_progress_title</template-output>
-<template-output>completed_story_list = "[]"</template-output>
-<template-output>backlog_count</template-output>
-<template-output>done_count</template-output>
-<template-output>total_stories</template-output>
 
 <ask>Ready to create your workflow status file? (y/n)</ask>
 
 <check if="answer == y">
   <action>Save status file to {output_folder}/bmm-workflow-status.md</action>
   <output>✅ Status file created! Next up: {{next_agent}} agent, run `{{next_command}}`</output>
+  <check if="next_agent !== current_agent">
+    <output>It is strongly recommended to clear the context or start a new chat and load the next agent to execute the next command from that agents help menu, unless there is something else I can do for you first.</output>
+  </check>
 </check>
 </step>
 

src/modules/bmm/workflows/workflow-status/instructions.md

@@ -77,13 +77,6 @@ Parse these fields:
 **Phase:** {{CURRENT_PHASE}}
 **Current Workflow:** {{CURRENT_WORKFLOW}}
 
-{{#if CURRENT_PHASE == "4-Implementation"}}
-**Development Queue:**
-
-- TODO: {{TODO_STORY}} - {{TODO_TITLE}}
-- IN PROGRESS: {{IN_PROGRESS_STORY}} - {{IN_PROGRESS_TITLE}}
-  {{/if}}
-
 ## 🎯 Your Options
 
 {{#if CURRENT_WORKFLOW != "complete"}}

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-0.yaml

@@ -44,32 +44,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-        note: "Include existing code context"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "story-done"
-        required: true
-        agent: "dev"
-        command: "story-done"
-
-story_naming: "story-<short-title>.md"
-story_example: "story-fix-auth-bug.md"
-max_stories: 1
-brownfield_note: "Ensure changes align with existing patterns"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-1.yaml

@@ -48,37 +48,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    story_loop: "for_each_story"
-    workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-        note: "Include existing code context"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        optional: true
-        agent: "dev"
-        command: "review-story"
-      - id: "story-done"
-        required: true
-        agent: "dev"
-        command: "story-done"
-
-story_naming: "story-<short-title>.md"
-story_example: "story-add-auth.md, story-update-dashboard.md"
-max_stories: 10
-brownfield_note: "Ensure changes align with existing patterns and architecture"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-2.yaml

@@ -66,41 +66,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    story_loop: "for_each_story"
-    workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-        note: "Include existing code context"
-      - id: "validate-story-context"
-        optional: true
-        agent: "sm"
-        command: "validate-story-context"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        optional: true
-        agent: "dev"
-        command: "review-story"
-      - id: "story-done"
-        required: true
-        agent: "dev"
-        command: "story-done"
-
-story_naming: "story-<short-title>.md"
-story_example: "story-user-dashboard.md, story-api-integration.md"
-max_stories: 15
-brownfield_note: "Balance new features with existing system stability"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml

@@ -85,64 +85,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    epic_loop: "for_each_epic"
-    epic_iteration:
-      setup_workflows:
-        - id: "tech-spec"
-          required: true
-          agent: "architect"
-          command: "tech-spec"
-          note: "Must respect existing patterns"
-
-      story_loop: "for_each_story_in_epic"
-      story_workflows:
-        - id: "create-story"
-          required: true
-          agent: "sm"
-          command: "create-story"
-        - id: "story-context"
-          required: true
-          agent: "sm"
-          command: "story-context"
-          note: "Heavy emphasis on existing code context"
-        - id: "validate-story-context"
-          optional: true
-          agent: "sm"
-          command: "validate-story-context"
-          note: "Ensure no breaking changes"
-        - id: "story-ready"
-          optional: true
-          agent: "sm"
-          command: "story-ready"
-        - id: "dev-story"
-          required: true
-          agent: "dev"
-          command: "dev-story"
-        - id: "review-story"
-          optional: true
-          agent: "dev"
-          command: "review-story"
-          note: "Check integration points"
-        - id: "story-done"
-          required: true
-          agent: "dev"
-          command: "story-done"
-
-      completion_workflows:
-        - id: "integration-test"
-          required: true
-          agent: "dev"
-          command: "integration-test"
-        - id: "retrospective"
-          required: true
-          agent: "sm"
-          command: "retrospective"
-
-story_naming: "story-<epic>.<story>.md"
-brownfield_note: "All changes must integrate seamlessly with existing system"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml

@@ -79,68 +79,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    epic_loop: "for_each_epic"
-    epic_iteration:
-      setup_workflows:
-        - id: "tech-spec"
-          required: true
-          agent: "sm"
-          command: "tech-spec"
-          note: "JIT per epic - creates stories considering existing code"
-
-      story_loop: "for_each_story_in_epic"
-      story_workflows:
-        - id: "create-story"
-          required: true
-          agent: "sm"
-          command: "create-story"
-        - id: "story-context"
-          required: true
-          agent: "sm"
-          command: "story-context"
-          note: "Extensive existing code context required"
-        - id: "validate-story-context"
-          optional: true
-          agent: "sm"
-          command: "validate-story-context"
-        - id: "story-ready"
-          optional: true
-          agent: "sm"
-          command: "story-ready"
-        - id: "dev-story"
-          required: true
-          agent: "dev"
-          command: "dev-story"
-        - id: "review-story"
-          optional: true
-          agent: "dev"
-          command: "review-story"
-          note: "Rigorous review for enterprise changes"
-        - id: "integration-test"
-          optional: true
-          agent: "dev"
-          command: "integration-test"
-          note: "Test integration with existing systems"
-        - id: "story-done"
-          required: true
-          agent: "dev"
-          command: "story-done"
-
-      completion_workflows:
-        - id: "retrospective"
-          required: true
-          agent: "sm"
-          command: "retrospective"
-          note: "Critical for enterprise-scale learning"
-
-story_naming: "story-<epic>.<story>.md"
-story_example: "story-1.1.md, story-2.3.md"
-epic_structure: "JIT tech-specs per epic create stories"
-enterprise_note: "Maintain system stability while implementing major changes"
-brownfield_note: "Extensive regression testing and backward compatibility required"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/game-design.yaml

@@ -62,72 +62,12 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    note: "Implementation varies by game complexity"
-    level_based_implementation:
-      level_0_1:
-        story_loop: "for_each_story"
-        workflows:
-          - id: "create-story"
-            required: true
-            agent: "sm"
-          - id: "story-context"
-            required: true
-            agent: "sm"
-          - id: "dev-story"
-            required: true
-            agent: "dev"
-          - id: "story-done"
-            required: true
-            agent: "dev"
-      level_2_4:
-        feature_loop: "for_each_feature"
-        feature_workflows:
-          - id: "tech-spec"
-            optional: true
-            agent: "architect"
-            note: "Per major feature"
-        story_loop: "for_each_story_in_feature"
-        story_workflows:
-          - id: "create-story"
-            required: true
-            agent: "sm"
-          - id: "story-context"
-            required: true
-            agent: "sm"
-          - id: "validate-story-context"
-            optional: true
-            agent: "sm"
-          - id: "dev-story"
-            required: true
-            agent: "dev"
-          - id: "review-story"
-            recommended: true
-            agent: "dev"
-          - id: "story-done"
-            required: true
-            agent: "dev"
-        feature_completion:
-          - id: "playtest"
-            required: true
-            agent: "game-designer"
-            command: "playtest"
-          - id: "retrospective"
-            optional: true
-            agent: "sm"
-
-story_naming:
-  level_0_1: "story-<feature>.md"
-  level_2_4: "story-<feature>.<n>.md"
-story_examples:
-  - "story-player-movement.md"
-  - "story-inventory-1.md"
-  - "story-combat-system-3.md"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"
 
 special_considerations:
   - "Iterative playtesting throughout development"

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-0.yaml

@@ -37,30 +37,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "story-done"
-        required: true
-        agent: "dev"
-        command: "story-done"
-
-story_naming: "story-<short-title>.md"
-story_example: "story-fix-login.md"
-max_stories: 1
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-1.yaml

@@ -41,39 +41,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    story_loop: "for_each_story"
-    workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-      - id: "story-ready"
-        optional: true
-        agent: "sm"
-        command: "story-ready"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        optional: true
-        agent: "dev"
-        command: "review-story"
-      - id: "story-done"
-        required: true
-        agent: "dev"
-        command: "story-done"
-
-story_naming: "story-<title>-<n>.md"
-story_example: "story-oauth-integration-1.md"
-max_stories: 3
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-2.yaml

@@ -70,49 +70,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    story_loop: "for_each_story"
-    workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-      - id: "validate-story-context"
-        optional: true
-        agent: "sm"
-        command: "validate-story-context"
-      - id: "story-ready"
-        optional: true
-        agent: "sm"
-        command: "story-ready"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        optional: true
-        agent: "dev"
-        command: "review-story"
-      - id: "story-done"
-        required: true
-        agent: "dev"
-        command: "story-done"
-    epic_completion:
-      - id: "retrospective"
-        optional: true
-        agent: "sm"
-        command: "retrospective"
-        note: "After each epic completes"
-
-story_naming: "story-<epic>.<story>.md"
-story_example: "story-1.1.md, story-2.3.md"
-epic_structure: "Numbered epics with numbered stories"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-3.yaml

@@ -57,7 +57,7 @@ phases:
         agent: "architect"
         command: "validate-architecture"
       - id: "solutioning-gate-check"
-        required: true
+        recommended: true
         agent: "architect"
         command: "solutioning-gate-check"
         note: "Validate PRD + UX + architecture cohesion before implementation"
@@ -65,58 +65,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    epic_loop: "for_each_epic"
-    epic_iteration:
-      setup_workflows:
-        - id: "tech-spec"
-          required: true
-          agent: "architect"
-          command: "tech-spec"
-          note: "JIT per epic - creates stories for that epic"
-
-      story_loop: "for_each_story_in_epic"
-      story_workflows:
-        - id: "create-story"
-          required: true
-          agent: "sm"
-          command: "create-story"
-        - id: "story-context"
-          required: true
-          agent: "sm"
-          command: "story-context"
-        - id: "validate-story-context"
-          optional: true
-          agent: "sm"
-          command: "validate-story-context"
-        - id: "story-ready"
-          optional: true
-          agent: "sm"
-          command: "story-ready"
-        - id: "dev-story"
-          required: true
-          agent: "dev"
-          command: "dev-story"
-        - id: "review-story"
-          optional: true
-          agent: "dev"
-          command: "review-story"
-        - id: "story-done"
-          required: true
-          agent: "dev"
-          command: "story-done"
-
-      completion_workflows:
-        - id: "retrospective"
-          recommended: true
-          agent: "sm"
-          command: "retrospective"
-
-story_naming: "story-<epic>.<story>.md"
-story_example: "story-1.1.md, story-2.3.md"
-epic_structure: "JIT tech-specs per epic create stories"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

src/modules/bmm/workflows/workflow-status/paths/greenfield-level-4.yaml

@@ -67,60 +67,9 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    phase_initialization:
+    workflows:
       - id: "sprint-planning"
         required: true
         agent: "sm"
         command: "sprint-planning"
-        note: "Initialize sprint tracking - run once when entering Phase 4"
-    epic_loop: "for_each_epic"
-    epic_iteration:
-      setup_workflows:
-        - id: "tech-spec"
-          required: true
-          agent: "architect"
-          command: "tech-spec"
-          note: "JIT per epic - creates stories for that epic"
-
-      story_loop: "for_each_story_in_epic"
-      story_workflows:
-        - id: "create-story"
-          required: true
-          agent: "sm"
-          command: "create-story"
-        - id: "story-context"
-          required: true
-          agent: "sm"
-          command: "story-context"
-        - id: "validate-story-context"
-          optional: true
-          agent: "sm"
-          command: "validate-story-context"
-        - id: "story-ready"
-          optional: true
-          agent: "sm"
-          command: "story-ready"
-        - id: "dev-story"
-          required: true
-          agent: "dev"
-          command: "dev-story"
-        - id: "review-story"
-          optional: true
-          agent: "dev"
-          command: "review-story"
-        - id: "story-done"
-          required: true
-          agent: "dev"
-          command: "story-done"
-
-      completion_workflows:
-        - id: "retrospective"
-          required: true
-          agent: "sm"
-          command: "retrospective"
-          note: "Critical for enterprise-scale learning"
-
-story_naming: "story-<epic>.<story>.md"
-story_example: "story-1.1.md, story-2.3.md"
-epic_structure: "JIT tech-specs per epic create stories"
-enterprise_note: "Rigorous validation and reviews required at scale"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

v6-open-items.md

@@ -7,17 +7,12 @@ Aside from stability and bug fixes found during the alpha period - the main focu
 - NPX installer
 - github pipelines, branch protection, vulnerability scanners
 - subagent injections reenabled
-- Solutioning Architecture
-  - is not asking for advanced elicitation
-  - the order of the document needs to rework the start to first align on what type of project architecture it is
-  - the architect put out some other not asked for documents as part of the final step
-  - the architect started dumping out the epic 1 tech spec with way too much prescriptive code in it
-- both the PRD and the solutioning process need to work in more of the questioning before dumping out a section (this might be happening since so much is already known from the brief though)
-- the UX Agent ux-spec process needs updates to be MUCH more interactive
-- the UX agent needs to be given commands to generate comps or mock ups in HTML - it works really well, just need to make it an actual thing the agent offers to do
+- docs docs docs
 
 --- done ---
 
+- Done - UX Expert replaced with UX Designer and has a massively improved create-design workflow.
+- Done - Architecture Reworked, searches web, more user interactive
 - Done - Sprint Status Workflow to generate the story status tracker
 - Done - Brownfield v6 integrated into the workflow.
 - Done - Full workflow single file tracking.