sprint status helpers, remove workflow integration from phase 4 items in prep of using sprint-planning status

2025-10-21 22:25:26 -05:00 · 2025-10-21 22:25:26 -05:00 · abaa24513a
parent 71330b6aac
commit abaa24513a
28 changed files with 1555 additions and 893 deletions
--- a/docs/audit-report-tech-spec-2025-10-21.md
+++ b/docs/audit-report-tech-spec-2025-10-21.md
@ -0,0 +1,431 @@
 # Workflow Audit Report
 **Workflow:** tech-spec
 **Audit Date:** 2025-10-21
 **Auditor:** Audit Workflow (BMAD v6)
 **Workflow Type:** Document (template-based)
 **Workflow Path:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/4-implementation/epic-tech-context
 ---
 ## Executive Summary
 **Overall Status:** ⚠️ ISSUES FOUND - Requires fixes before production use
 **Issue Breakdown:**
 - Critical Issues: **2**
 - Important Issues: **1**
 - Cleanup Recommendations: **4**
 **Primary Concerns:**
 1. Web bundle missing critical workflow dependencies
 2. Output path hardcoded instead of using config variable
 3. Configuration bloat (40% unused variables)
 ---
 ## 1. Standard Config Block Validation
 ### ✅ Status: PASS
 All required standard config variables are present and correctly formatted:
 **Required Variables:**
 - ✅ `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"`
 - ✅ `date: system-generated`
 **Additional Config Variables Found:**
 - ⚠️ `document_output_language` (non-standard, potentially unused)
 - ⚠️ `user_skill_level` (non-standard, potentially unused)
 **Recommendation:** Verify usage of additional config variables or remove if unused.
 ---
 ## 2. YAML/Instruction/Template Alignment
 ### ❌ Issues Found: Configuration Bloat
 **Variables Analyzed:** 5 custom fields
 **Used in Instructions:** 3
 **Used in Template:** N/A (config variables)
 **Unused (Bloat):** 2
 ### Unused Variables (BLOAT):
 1. **`document_output_language`**
   - Location: workflow.yaml line 10
   - Status: Defined but never referenced in instructions.md or template.md
   - Impact: Configuration bloat
   - **Action Required:** Remove from yaml
 2. **`user_skill_level`**
   - Location: workflow.yaml line 11
   - Status: Defined but never referenced in instructions.md or template.md
   - Impact: Configuration bloat
   - **Action Required:** Remove from yaml
 ### Properly Used Variables:
 - ✅ `output_folder` → Used in instructions.md (lines 12, 129)
 - ✅ `user_name` → Used in instructions.md (lines 143, 166) and template.md (line 4)
 - ✅ `communication_language` → Used in instructions.md (line 6)
 - ✅ `date` → Used in template.md (line 3) and output file naming
 - ✅ `non_interactive` → Used in instructions.md (lines 8, 66, 68)
 **Bloat Metrics:**
 - Total custom yaml fields: 5
 - Used fields: 3
 - Unused fields: 2
 - **Bloat Percentage: 40%**
 ---
 ## 3. Config Variable Usage
 ### Overall Status: ⚠️ IMPORTANT ISSUE FOUND
 **Communication Language:**
 - ✅ Properly used on line 6: `Communicate all responses in {communication_language}`
 - ✅ No inappropriate usage in template headers
 - Status: **CORRECT**
 **User Name:**
 - ✅ Used for personalization on lines 143, 166
 - ✅ Optional metadata usage in template (line 4)
 - Status: **CORRECT**
 **Output Folder:**
 - ✅ Properly used for file searches (lines 12, 129)
 - ❌ **ISSUE:** `default_output_file` hardcodes path instead of using variable
  - Current: `"{project-root}/docs/tech-spec-epic-{{epic_id}}.md"`
  - Should be: `"{output_folder}/tech-spec-epic-{{epic_id}}.md"`
  - Impact: Ignores user's configured output folder preference
  - Severity: **IMPORTANT**
 **Date:**
 - ✅ System-generated and available
 - ✅ Used in template metadata (line 3)
 - ✅ Used in output file naming
 - Status: **CORRECT**
 ### Action Required:
 **Fix default_output_file in workflow.yaml:**
 ```yaml
 # Current (line 29):
 default_output_file: "{project-root}/docs/tech-spec-epic-{{epic_id}}.md"
 # Should be:
 default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
 ```
 ---
 ## 4. Web Bundle Validation
 ### 🚨 Status: CRITICAL ISSUES FOUND
 **Current Web Bundle Configuration:**
 ```yaml
 web_bundle:
  name: 'tech-spec'
  description: '...'
  author: 'BMAD BMM'
  web_bundle_files:
    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md'
    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md'
    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md'
 ```
 ### Path Validation:
 - ✅ All paths use bmad/-relative format (NOT {project-root})
 - ✅ No {config_source} variables in web_bundle section
 - ✅ Paths match actual file locations
 ### Completeness Check:
 - ✅ instructions.md listed
 - ✅ template.md listed (document workflow)
 - ✅ checklist.md listed
 ### 🚨 Critical Issues:
 **Issue 1: Missing Workflow Dependency**
 - Severity: **CRITICAL**
 - Location: instructions.md line 133
 - Problem: Workflow invokes `workflow-status` but dependency not in web_bundle_files
 - Invocation: `<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">`
 - Missing files:
  - `bmad/bmm/workflows/workflow-status/workflow.yaml`
  - `bmad/bmm/workflows/workflow-status/instructions.md` (if exists)
 **Issue 2: Missing existing_workflows Field**
 - Severity: **CRITICAL**
 - Problem: When `<invoke-workflow>` calls exist, web_bundle MUST include `existing_workflows` field
 - Current: Field not present
 - Required: Mapping of workflow variables to paths
 ### Required Fix:
 ```yaml
 web_bundle:
  name: 'tech-spec'
  description: 'Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping'
  author: 'BMAD BMM'
  existing_workflows:
    - workflow_status: 'bmad/bmm/workflows/workflow-status/workflow.yaml'
  web_bundle_files:
    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md'
    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md'
    - 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md'
    - 'bmad/bmm/workflows/workflow-status/workflow.yaml'
    - 'bmad/bmm/workflows/workflow-status/instructions.md'
 ```
 **Web Bundle Status:**
 - Web Bundle Present: ✅ Yes
 - Files Listed: 3
 - Missing Files: 2+
 - Completeness: ❌ **INCOMPLETE**
 ---
 ## 5. Bloat Detection
 ### Bloat Summary
 **Unused YAML Fields: 2**
 1. `document_output_language`
   - Type: Config variable
   - Usage: Not referenced anywhere
   - Recommendation: **Remove**
 2. `user_skill_level`
   - Type: Config variable
   - Usage: Not referenced anywhere
   - Recommendation: **Remove**
 **Hardcoded Values: 1**
 3. `default_output_file` path
   - Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md`
   - Should use: `{output_folder}`
   - Impact: Ignores user configuration
   - Recommendation: **Fix to use {output_folder}**
 **Redundant Configuration: 3 fields**
 4. Metadata duplication between top-level and web_bundle:
   - `name` appears on yaml line 1 AND web_bundle line 36
   - `description` appears on yaml line 2 AND web_bundle line 37
   - `author` appears on yaml line 3 AND web_bundle line 38
   - Recommendation: **Remove duplication** (keep in one location)
 ### Bloat Metrics:
 - Total custom yaml fields analyzed: 5
 - Used fields: 3
 - Unused fields: 2
 - **Bloat Percentage: 40%**
 - Redundant metadata fields: 3
 - **Cleanup Potential: HIGH** (~30% configuration reduction possible)
 ---
 ## 6. Template Variable Mapping
 ### ✅ Status: EXCELLENT - No Issues
 **Template Variables:** 20
 **Mapped via template-output:** 15
 **Config Variables:** 2
 **Runtime Variables:** 3
 **Missing Mappings:** 0
 **Orphaned Outputs:** 0
 ### All Template Variables Accounted For:
 **Generated via template-output (15):**
 - overview, objectives_scope, system_arch_alignment
 - services_modules, data_models, apis_interfaces, workflows_sequencing
 - nfr_performance, nfr_security, nfr_reliability, nfr_observability
 - dependencies_integrations
 - acceptance_criteria, traceability_mapping
 - risks_assumptions_questions, test_strategy
 **Standard Config Variables (2):**
 - date (system-generated)
 - user_name (from config)
 **Runtime/Extracted Variables (3):**
 - epic_title (extracted from PRD)
 - epic_id (extracted from PRD)
 ### Validation:
 - ✅ All variables use snake_case naming
 - ✅ Variable names are descriptive and clear
 - ✅ Logical grouping in template-output sections
 - ✅ No orphaned template-output tags
 - ✅ Complete 1:1 mapping coverage
 **No action required** - Template variable mapping is exemplary.
 ---
 ## Recommendations
 ### 🚨 Critical (Fix Immediately)
 **Priority 1: Fix Web Bundle Dependencies**
 - Add `existing_workflows` field to web_bundle section
 - Include workflow-status workflow files in web_bundle_files
 - Impact: Without this, workflow cannot be bundled for web use
 - File: `workflow.yaml` lines 35-43
 **Priority 2: Add Missing Workflow Files**
 - Include: `bmad/bmm/workflows/workflow-status/workflow.yaml`
 - Include: `bmad/bmm/workflows/workflow-status/instructions.md` (if exists)
 - Impact: Web bundle incomplete, workflow invocations will fail
 - File: `workflow.yaml` web_bundle_files section
 ---
 ### ⚠️ Important (Address Soon)
 **Priority 3: Fix Output Path Configuration**
 - Change `default_output_file` to use `{output_folder}` variable
 - Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md`
 - Fixed: `{output_folder}/tech-spec-epic-{{epic_id}}.md`
 - Impact: Respects user's configured output preferences
 - File: `workflow.yaml` line 29
 ---
 ### 🧹 Cleanup (Nice to Have)
 **Priority 4: Remove Unused Config Variables**
 - Remove: `document_output_language` (line 10)
 - Remove: `user_skill_level` (line 11)
 - Impact: Reduces configuration bloat by 40%
 - File: `workflow.yaml` config section
 **Priority 5: Eliminate Metadata Duplication**
 - Remove duplicate `name`, `description`, `author` from either top-level or web_bundle
 - Keep metadata in one location only
 - Impact: Cleaner configuration, easier maintenance
 - File: `workflow.yaml` lines 1-3 or 36-38
 ---
 ## Validation Checklist
 Use this checklist to verify fixes:
 - [ ] **Web Bundle:** existing_workflows field added with workflow_status mapping
 - [ ] **Web Bundle:** workflow-status/workflow.yaml added to web_bundle_files
 - [ ] **Config:** default_output_file uses {output_folder} instead of hardcoded path
 - [ ] **Bloat:** document_output_language removed from yaml
 - [ ] **Bloat:** user_skill_level removed from yaml
 - [ ] **Redundancy:** Metadata duplication eliminated
 - [ ] **Re-test:** Workflow executes successfully after fixes
 - [ ] **Re-audit:** Run audit-workflow again to verify all issues resolved
 ---
 ## Workflow Structure Assessment
 ### Strengths:
 - ✅ Excellent template variable mapping (20 variables, 0 orphans)
 - ✅ Proper use of standard config variables
 - ✅ Clear step-by-step instructions with proper XML structure
 - ✅ Good integration with workflow-status for progress tracking
 - ✅ Comprehensive validation checklist
 - ✅ Non-interactive mode support (#yolo mode)
 ### Areas for Improvement:
 - ❌ Web bundle configuration incomplete (missing dependencies)
 - ❌ Output path doesn't respect user configuration
 - ⚠️ Configuration bloat (40% unused variables)
 - ⚠️ Metadata duplication
 ---
 ## Next Steps
 ### Immediate Actions:
 1. **Fix Critical Issues** (Est. 15 minutes)
   - Add existing_workflows field to web_bundle
   - Add workflow-status files to web_bundle_files
   - Verify workflow-status workflow exists at specified path
 2. **Fix Important Issues** (Est. 5 minutes)
   - Update default_output_file to use {output_folder}
   - Test output file creation with different config values
 3. **Cleanup Configuration** (Est. 10 minutes)
   - Remove document_output_language from yaml
   - Remove user_skill_level from yaml
   - Eliminate metadata duplication
 4. **Verify Fixes** (Est. 10 minutes)
   - Re-run audit-workflow to confirm all issues resolved
   - Test workflow execution end-to-end
   - Verify web bundle generation works
 ### Recommended Testing:
 ```bash
 # After fixes, test the workflow
 /bmad:bmm:workflows:tech-spec
 # Re-audit to verify
 /bmad:bmb:agents:bmad-builder -> *audit-workflow
 ```
 ---
 ## Conclusion
 The **tech-spec** workflow has a solid foundation with excellent template variable mapping and proper instruction structure. However, **critical web bundle issues** must be resolved before production use, and the hardcoded output path should be fixed to respect user configuration.
 **Estimated Fix Time:** 30-40 minutes
 **Recommended Priority:** HIGH - Address critical issues before next release
 ---
 **Audit Complete** ✅
 Generated by: audit-workflow v1.0
 Powered by: BMAD Core v6-alpha
--- a/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md
@ -9,15 +9,6 @@
 <workflow>
 <step n="0" goal="Check project status" optional="true">
 <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
  <param>mode: init-check</param>
 </invoke-workflow>
 <output>Running correct-course workflow for sprint change management.
 {{#if status_exists}}Status tracking enabled.{{else}}Note: No status file - running standalone.{{/if}}</output>
 </step>
 <step n="1" goal="Initialize Change Navigation">
  <action>Confirm change trigger and gather user description of the issue</action>
  <action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
--- a/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml
@ -7,8 +7,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
--- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md
@ -28,29 +28,6 @@
    <action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
  </step>
  <step n="2.5" goal="Get story to draft from status file">
    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
      <param>mode: data</param>
      <param>data_request: next_story</param>
    </invoke-workflow>
    <check if="status_exists == true AND todo_story_id != ''">
      <action>Use extracted story information:</action>
      - {{todo_story_id}}: The story ID to draft
      - {{todo_story_title}}: The story title
      - {{todo_story_file}}: The exact story file path to create
      <critical>This is the PRIMARY source - DO NOT search or guess</critical>
      <action>Set {{story_path}} = {story_dir}/{{todo_story_file}}</action>
      <action>Skip legacy discovery in Step 3</action>
    </check>
    <check if="status_exists == false OR todo_story_id == ''">
      <action>Fall back to legacy story discovery in Step 3</action>
    </check>
  </step>
  <step n="3" goal="Determine target story (do not prompt in #yolo)">
    <action>List existing story markdown files in {{story_dir}} matching pattern: "story-<epic>.<story>.md"</action>
    <check>If none found → Set {{epic_num}}=1 and {{story_num}}=1</check>
@ -99,56 +76,18 @@
    <action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
    <check>If {{auto_run_context}} == true → <invoke-workflow path="{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml">Pass {{story_path}} = {default_output_file}</invoke-workflow></check>
    <action>Report created/updated story path</action>
-  </step>
+    <output>**✅ Story Created Successfully, {user_name}!**
  <step n="9" goal="Update status file on completion">
    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
    <action>Find the most recent file (by date in filename)</action>
    <check if="status file exists">
      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
        <param>mode: update</param>
        <param>action: set_current_workflow</param>
        <param>workflow_name: create-story</param>
      </invoke-workflow>
      <check if="success == true">
        <output>✅ Status updated: Story {{story_id}} drafted</output>
      </check>
      <output>**✅ Story Created Successfully, {user_name}!**
 **Story Details:**
 - Story ID: {{story_id}}
 - File: {{story_file}}
 - Status: Draft (needs review)
 **Status file updated:**
 - Current step: create-story (Story {{story_id}}) ✓
 - Progress: {{new_progress_percentage}}%
 **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
-
+    </output>
 Check status anytime with: `workflow-status`
      </output>
    </check>
    <check if="status file not found">
      <output>**✅ Story Created Successfully, {user_name}!**
 **Story Details:**
 - Story ID: {{story_id}}
 - File: {{story_file}}
 - Status: Draft
 Note: Running in standalone mode (no status file).
 To track progress across workflows, run `workflow-status` first.
      </output>
    </check>
  </step>
 </workflow>
--- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
@ -7,8 +7,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 # Workflow components
--- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md
@ -15,30 +15,11 @@
 <workflow>
-  <step n="1" goal="Load story from status file IN PROGRESS section">
+  <step n="1" goal="Locate and load story">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <action>If {{story_path}} explicitly provided → use it</action>
-      <param>mode: data</param>
+    <action>Otherwise list story-*.md files from {{story_dir}}, sort by modified time</action>
-      <param>data_request: next_story</param>
+    <ask optional="true" if="{{non_interactive}} == false">Select story or enter path</ask>
-    </invoke-workflow>
+    <action if="{{non_interactive}} == true">Auto-select most recent</action>
    <check if="status_exists == true AND in_progress_story != ''">
      <action>Use IN PROGRESS story from status:</action>
      - {{in_progress_story}}: Current story ID
      - Story file path derived from ID format
      <critical>DO NOT SEARCH - status file provides exact story</critical>
      <action>Determine story file path from in_progress_story ID</action>
      <action>Set {{story_path}} = {story_dir}/{{derived_story_file}}</action>
    </check>
    <check if="status_exists == false OR in_progress_story == ''">
      <action>Fall back to legacy auto-discovery:</action>
      <action>If {{story_path}} explicitly provided → use it</action>
      <action>Otherwise list story-*.md files from {{story_dir}}, sort by modified time</action>
      <ask optional="true" if="{{non_interactive}} == false">Select story or enter path</ask>
      <action if="{{non_interactive}} == true">Auto-select most recent</action>
    </check>
    <action>Read COMPLETE story file from {{story_path}}</action>
    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
@ -104,24 +85,7 @@
    <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>
-  </step>
+    <output>**✅ Story Implementation Complete, {user_name}!**
  <step n="8" goal="Update status file on completion">
    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
    <action>Find the most recent file (by date in filename)</action>
    <check if="status file exists">
      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
        <param>mode: update</param>
        <param>action: set_current_workflow</param>
        <param>workflow_name: dev-story</param>
      </invoke-workflow>
      <check if="success == true">
        <output>✅ Status updated: Story {{current_story_id}} ready for review</output>
      </check>
      <output>**✅ Story Implementation Complete, {user_name}!**
 **Story Details:**
 - Story ID: {{current_story_id}}
@ -129,33 +93,11 @@
 - File: {{story_path}}
 - Status: Ready for Review
 **Status file updated:**
 - Current step: dev-story (Story {{current_story_id}}) ✓
 - Progress: {{new_progress_percentage}}%
 **Next Steps:**
 1. Review the implemented story and test the changes
 2. Verify all acceptance criteria are met
-3. When satisfied, run `story-done` to mark story complete and advance the queue
+3. When satisfied, mark story complete and continue with next story
-
+    </output>
 Or check status anytime with: `workflow-status`
      </output>
    </check>
    <check if="status file not found">
      <output>**✅ Story Implementation Complete, {user_name}!**
 **Story Details:**
 - Story ID: {{current_story_id}}
 - Title: {{current_story_title}}
 - File: {{story_path}}
 - Status: Ready for Review
 Note: Running in standalone mode (no status file).
 To track progress across workflows, run `workflow-status` first.
      </output>
    </check>
  </step>
 </workflow>
--- a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
@ -7,8 +7,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 # Workflow components
--- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md
@ -5,73 +5,18 @@
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>Communicate all responses in {communication_language}</critical>
 <critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
-<critical>Default execution mode: #yolo (non-interactive). If required inputs cannot be auto-discovered and {{non_interactive}} == true, HALT with a clear message listing missing documents; do not prompt.</critical>
+<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="Check and load workflow status file">
+  <step n="1" goal="Collect inputs and initialize">
    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
    <action>Find the most recent file (by date in filename: bmm-workflow-status.md)</action>
    <check if="exists">
      <action>Load the status file</action>
      <action>Extract key information:</action>
      - current_step: What workflow was last run
      - next_step: What workflow should run next
      - planned_workflow: The complete workflow journey table
      - progress_percentage: Current progress
      - project_level: Project complexity level (0-4)
      <action>Set status_file_found = true</action>
      <action>Store status_file_path for later updates</action>
      <check if="project_level < 3">
        <ask>**⚠️ Project Level Notice**
 Status file shows project_level = {{project_level}}.
 Tech-spec workflow is typically only needed for Level 3-4 projects.
 For Level 0-2, architecture usually generates tech specs automatically.
 Options:
 1. Continue anyway (manual tech spec generation)
 2. Exit (check if architecture already generated tech specs)
 3. Run workflow-status to verify project configuration
 What would you like to do?</ask>
        <action>If user chooses exit → HALT with message: "Check docs/ folder for existing tech-spec files"</action>
      </check>
    </check>
    <check if="not exists">
      <ask>**No workflow status file found.**
 The status file tracks progress across all workflows and stores project configuration.
 Note: This workflow is typically invoked automatically by architecture, or manually for JIT epic tech specs.
 Options:
 1. Run workflow-status first to create the status file (recommended)
 2. Continue in standalone mode (no progress tracking)
 3. Exit
 What would you like to do?</ask>
      <action>If user chooses option 1 → HALT with message: "Please run workflow-status first, then return to tech-spec"</action>
      <action>If user chooses option 2 → Set standalone_mode = true and continue</action>
      <action>If user chooses option 3 → HALT</action>
    </check>
  </step>
  <step n="2" goal="Collect inputs and initialize">
    <action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>
-    <ask optional="true" if="{{non_interactive}} == false">If inputs are missing, ask the user for file paths.</ask>
+    <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>
-    <check if="inputs are missing and {{non_interactive}} == true">HALT with a clear message listing missing documents and do not proceed until user provides sufficient documents to proceed.</check>
+    <action>Extract {{epic_title}} and {{epic_id}} from PRD.</action>
    <action>Extract {{epic_title}} and {{epic_id}} from PRD (or ASK if not present).</action>
    <action>Resolve output file path using workflow variables and initialize by writing the template.</action>
  </step>
-  <step n="3" goal="Overview and scope">
+  <step n="2" goal="Overview and scope">
    <action>Read COMPLETE PRD and Architecture files.</action>
    <template-output file="{default_output_file}">
      Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals
@ -80,8 +25,8 @@ What would you like to do?</ask>
    </template-output>
  </step>
-  <step n="4" goal="Detailed design">
+  <step n="3" goal="Detailed design">
-    <action>Derive concrete implementation specifics from Architecture and PRD (NO invention).</action>
+    <action>Derive concrete implementation specifics from Architecture and PRD (CRITICAL: NO invention).</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
@ -90,7 +35,7 @@ What would you like to do?</ask>
    </template-output>
  </step>
-  <step n="5" goal="Non-functional requirements">
+  <step n="4" 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
@ -99,14 +44,14 @@ What would you like to do?</ask>
    </template-output>
  </step>
-  <step n="6" goal="Dependencies and integrations">
+  <step n="5" 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="7" goal="Acceptance criteria and traceability">
+  <step n="6" 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
@ -114,69 +59,28 @@ What would you like to do?</ask>
    </template-output>
  </step>
-  <step n="8" goal="Risks and test strategy">
+  <step n="7" 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="9" goal="Validate">
+  <step n="8" goal="Validate and complete">
    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
-  </step>
+    <output>**✅ Tech Spec Generated Successfully, {user_name}!**
  <step n="10" goal="Update status file on completion">
    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
    <action>Find the most recent file (by date in filename)</action>
    <check if="status file exists">
      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
        <param>mode: update</param>
        <param>action: complete_workflow</param>
        <param>workflow_name: tech-spec</param>
      </invoke-workflow>
      <check if="success == true">
        <output>✅ Status updated for Epic {{epic_id}} tech-spec</output>
      </check>
      <output>**✅ Tech Spec Generated Successfully, {user_name}!**
 **Epic Details:**
 - Epic ID: {{epic_id}}
 - Epic Title: {{epic_title}}
 - Tech Spec File: {{default_output_file}}
-**Status file updated:**
+**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed.
 - Current step: tech-spec (Epic {{epic_id}}) ✓
 - Progress: {{new_progress_percentage}}%
 **Note:** This is a JIT (Just-In-Time) workflow.
 - Run again for other epics that need detailed tech specs
 - Or proceed to Phase 4 (Implementation) if all tech specs are complete
 **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
-3. Check status anytime with: `workflow-status`
+    </output>
      </output>
    </check>
    <check if="status file not found">
      <output>**✅ Tech Spec Generated Successfully, {user_name}!**
 **Epic Details:**
 - Epic ID: {{epic_id}}
 - Epic Title: {{epic_title}}
 - Tech Spec File: {{default_output_file}}
 Note: Running in standalone mode (no status file).
 To track progress across workflows, run `workflow-status` first.
 **Note:** This is a JIT workflow - run again for other epics as needed.
      </output>
    </check>
  </step>
 </workflow>
--- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
@ -7,8 +7,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 # Inputs expected ( check output_folder or ask user if missing)
@ -26,17 +24,6 @@ instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 # Output configuration
-default_output_file: "{project-root}/docs/tech-spec-epic-{{epic_id}}.md"
+default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
-# Variables
+web_bundle: false
 variables:
  non_interactive: true
 web_bundle:
  name: "tech-spec"
  description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
  author: "BMAD BMM"
  web_bundle_files:
    - "bmad/bmm/workflows/4-implementation/epic-tech-context/template.md"
    - "bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md"
    - "bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md"
--- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md
@ -20,22 +20,7 @@ FACILITATION NOTES:
 <workflow>
-<step n="1" goal="Check workflow status">
+<step n="1" goal="Epic Context Discovery">
 <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
  <param>mode: init-check</param>
 </invoke-workflow>
 <check if="status_exists == false">
  <output>⚠️ {{suggestion}}
 Running in standalone mode - no progress tracking.</output>
 <action>Set standalone_mode = true</action>
 </check>
 <action>Store {{status_file_path}} for later updates (if exists)</action>
 </step>
 <step n="2" goal="Epic Context Discovery">
 <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>
@ -378,65 +363,23 @@ 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>
 <action>Confirm all action items have been captured</action>
 <action>Remind user to schedule prep sprint if needed</action>
-</step>
+<output>**✅ Retrospective Complete, {user_name}!**
 <step n="9" goal="Update status file on completion">
 <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
 <action>Find the most recent file (by date in filename)</action>
 <check if="status file exists">
  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
    <param>mode: update</param>
    <param>action: complete_workflow</param>
    <param>workflow_name: retrospective</param>
  </invoke-workflow>
  <check if="success == true">
    <output>✅ Status updated: Retrospective complete for Epic {{completed_number}}</output>
  </check>
 </check>
 <output>**✅ Retrospective Complete**
 **Epic Review:**
 - Epic {{completed_number}}: {{epic_title}} reviewed
 - Retrospective saved: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md
 - Action Items: {{action_count}}
 - Preparation Tasks: {{prep_task_count}}
 - Critical Path Items: {{critical_count}}
 **Status file updated:**
 - Current step: retrospective (Epic {{completed_number}}) ✓
 - Progress: {{new_progress_percentage}}%
 **Next Steps:**
 1. Review retrospective summary: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md
 2. Execute preparation sprint (Est: {{prep_days}} days)
 3. Complete critical path items before Epic {{next_number}}
 4. Begin Epic {{next_number}} planning when preparation complete
 Check status anytime with: `workflow-status`
 </output>
 </check>
 <check if="status file not found">
  <output>**✅ Retrospective Complete, {user_name}!**
 **Epic Review:**
 - Epic {{completed_number}}: {{epic_title}} reviewed
 - Retrospective saved: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md
 Note: Running in standalone mode (no status file).
 **Next Steps:**
 1. Execute preparation sprint
 2. Begin Epic {{next_number}} planning
   </output>
   </check>
   </step>
 </workflow>
--- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml
@ -7,8 +7,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective"
--- a/src/modules/bmm/workflows/4-implementation/review-story/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/review-story/instructions.md
@ -14,22 +14,7 @@
 <workflow>
-  <step n="1" goal="Check workflow status">
+  <step n="1" goal="Locate story and verify review status">
    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
      <param>mode: init-check</param>
    </invoke-workflow>
    <check if="status_exists == false">
      <output>⚠️ {{suggestion}}
 Running in standalone mode - no progress tracking.</output>
      <action>Set standalone_mode = true</action>
    </check>
    <action>Store {{status_file_path}} for later updates (if exists)</action>
  </step>
  <step n="2" goal="Locate story and verify review status">
    <action>If {{story_path}} was provided → use it. Else auto-discover from {{story_dir}} by listing files matching pattern: "story-*.md" (recursive), sort by last modified (newest first), present top {{story_selection_limit}}.</action>
    <ask optional="true" if="{{non_interactive}} == false">Select a story (1-{{story_selection_limit}}) or enter a path:</ask>
    <action>Resolve {{story_path}} and read the COMPLETE file.</action>
@ -115,131 +100,18 @@ Running in standalone mode - no progress tracking.</output>
  <step n="9" 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>
-  </step>  <step n="1" goal="Locate story and verify review status">
+    <output>**✅ Story Review Complete, {user_name}!**
    <action>If {{story_path}} was provided → use it. Else auto-discover from {{story_dir}} by listing files matching pattern: "story-*.md" (recursive), sort by last modified (newest first), present top {{story_selection_limit}}.</action>
    <ask optional="true" if="{{non_interactive}} == false">Select a story (1-{{story_selection_limit}}) or enter a path:</ask>
    <action>Resolve {{story_path}} and read the COMPLETE file.</action>
    <action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available.</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>
  </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>
  <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>
  <step n="4" goal="Assess implementation against acceptance criteria and specs">
    <action>From the story, read Acceptance Criteria and Tasks/Subtasks with their completion state.</action>
    <action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
    <action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
    <action>For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly.</action>
    <action if="critical architecture constraints are violated (e.g., layering, dependency rules)">flag as High severity finding.</action>
  </step>
  <step n="5" goal="Perform code quality and risk review">
    <action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
    <action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, unvalidated redirects, CORS misconfig, dependency vulnerabilities (based on manifests).</action>
    <action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
    <action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
  </step>
  <step n="6" goal="Decide review outcome and prepare notes">
    <action>Determine outcome: Approve, Changes Requested, or Blocked.</action>
    <action>Prepare a structured review report with sections: Summary, Outcome, Key Findings (by severity), Acceptance Criteria Coverage, Test Coverage and Gaps, Architectural Alignment, Security Notes, Best-Practices and References, Action Items.</action>
    <action>For Action Items, use imperative phrasing and map each to related ACs or files. Include suggested owners if clear.</action>
  </step>
  <step n="7" goal="Append review to story and update metadata">
    <action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
    <action>Insert subsections:
      - Reviewer: {{user_name}}
      - Date: {{date}}
      - Outcome: (Approve | Changes Requested | Blocked)
      - Summary
      - Key Findings
      - Acceptance Criteria Coverage
      - Test Coverage and Gaps
      - Architectural Alignment
      - Security Notes
      - Best-Practices and References (with links)
      - Action Items
    </action>
    <action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
    <action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
    <action>Save the story file.</action>
  </step>
  <step n="8" goal="Follow-up options" optional="true">
    <action>If action items are straightforward and within safety bounds, ASK whether to create corresponding unchecked items under "Tasks / Subtasks" so the `dev-story` workflow can implement them next. If approved, append them under an Action Items subsection.</action>
    <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">
    <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>
  </step>
  <step n="10" goal="Update status file on completion">
    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
    <action>Find the most recent file (by date in filename)</action>
    <check if="status file exists">
      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
        <param>mode: update</param>
        <param>action: set_current_workflow</param>
        <param>workflow_name: review-story</param>
      </invoke-workflow>
      <check if="success == true">
        <output>✅ Status updated: Story {{epic_num}}.{{story_num}} reviewed</output>
      </check>
      <output>**✅ Story Review Complete, {user_name}!**
 **Story Details:**
 - Story: {{epic_num}}.{{story_num}}
 - Review Outcome: {{outcome}}
 - Action Items: {{action_item_count}}
 **Status file updated:**
 - Current step: review-story (Story {{epic_num}}.{{story_num}}) ✓
 - Progress: {{new_progress_percentage}}%
 **Next Steps:**
 1. Review the Senior Developer Review notes appended to story
 2. Address any action items or changes requested
-3. When ready, run `story-done` to mark story complete
+3. When ready, continue with implementation or mark story complete
-
+    </output>
 Check status anytime with: `workflow-status`
      </output>
    </check>
    <check if="status file not found">
      <output>**✅ Story Review Complete, {user_name}!**
 **Story Details:**
 - Story: {{epic_num}}.{{story_num}}
 - Review Outcome: {{outcome}}
 Note: Running in standalone mode (no status file).
 **Next Steps:**
 1. Review the Senior Developer Review notes
 2. Address any action items
      </output>
    </check>
  </step>
 </workflow>
--- a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml
@ -8,8 +8,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 # Workflow components
--- a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml
@ -7,7 +7,6 @@ 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"
 date: system-generated
 # Workflow components
--- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md
@ -11,25 +11,7 @@
 <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>
 <workflow>
-  <step n="1" goal="Validate workflow sequence">
+  <step n="1" goal="Locate story and initialize output">
    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
      <param>mode: validate</param>
      <param>calling_workflow: story-context</param>
    </invoke-workflow>
    <check if="warning != ''">
      <output>{{warning}}</output>
      <ask>Continue with story-context anyway? (y/n)</ask>
      <check if="n">
        <output>{{suggestion}}</output>
        <action>Exit workflow</action>
      </check>
    </check>
    <action>Store {{status_file_path}} for later updates</action>
  </step>
  <step n="2" 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>
@ -45,7 +27,7 @@
    <template-output file="{default_output_file}">so_that</template-output>
  </step>
-  <step n="3" goal="Collect relevant documentation">
+  <step n="2" goal="Collect relevant documentation">
    <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks.</action>
    <action>Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
    <action>For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md").</action>
@ -58,7 +40,7 @@
    </template-output>
  </step>
-  <step n="4" goal="Analyze existing code, interfaces, and constraints">
+  <step n="3" goal="Analyze existing code, interfaces, and constraints">
    <action>Search source tree for modules, files, and symbols matching story intent and AC keywords (controllers, services, components, tests).</action>
    <action>Identify existing interfaces/APIs the story should reuse rather than recreate.</action>
    <action>Extract development constraints from Dev Notes and architecture (patterns, layers, testing requirements).</action>
@ -83,7 +65,7 @@
    </template-output>
  </step>
-  <step n="5" goal="Gather dependencies and frameworks">
+  <step n="4" goal="Gather dependencies and frameworks">
    <action>Detect dependency manifests and frameworks in the repo:
      - Node: package.json (dependencies/devDependencies)
      - Python: pyproject.toml/requirements.txt
@ -95,7 +77,7 @@
    </template-output>
  </step>
-  <step n="6" goal="Testing standards and ideas">
+  <step n="5" goal="Testing standards and ideas">
    <action>From Dev Notes, architecture docs, testing docs, and existing tests, extract testing standards (frameworks, patterns, locations).</action>
    <template-output file="{default_output_file}">
      Populate tests.standards with a concise paragraph
@ -104,68 +86,27 @@
    </template-output>
  </step>
-  <step n="7" goal="Validate and save">
+  <step n="6" goal="Validate and save">
    <action>Validate output XML 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="8" goal="Update story status and context reference">
+  <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>
    <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>
-  </step>
+    <output>**✅ Story Context Generated Successfully, {user_name}!**
  <step n="9" goal="Update status file on completion">
    <action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
    <action>Find the most recent file (by date in filename)</action>
    <check if="status file exists">
      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
        <param>mode: update</param>
        <param>action: set_current_workflow</param>
        <param>workflow_name: story-context</param>
      </invoke-workflow>
      <check if="success == true">
        <output>✅ Status updated: Context generated for Story {{story_id}}</output>
      </check>
      <output>**✅ Story Context Generated Successfully, {user_name}!**
 **Story Details:**
 - Story ID: {{story_id}}
 - Title: {{story_title}}
 - Context File: {{default_output_file}}
 **Status file updated:**
 - Current step: story-context (Story {{story_id}}) ✓
 - Progress: {{new_progress_percentage}}%
 **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
-
+    </output>
 Check status anytime with: `workflow-status`
      </output>
    </check>
    <check if="status file not found">
      <output>**✅ Story Context Generated Successfully, {user_name}!**
 **Story Details:**
 - Story ID: {{story_id}}
 - Title: {{story_title}}
 - Context File: {{default_output_file}}
 Note: Running in standalone mode (no status file).
 To track progress across workflows, run `workflow-status` first.
 **Next Steps:**
 1. Load DEV agent and run `dev-story` to implement
      </output>
    </check>
  </step>
 </workflow>
--- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
@ -8,8 +8,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 # Workflow components
@ -21,7 +19,6 @@ validation: "{installed_path}/checklist.md"
 # Variables and inputs
 variables:
  story_path: "" # Explicit story path; auto-discovered if empty
  auto_update_status: false
  story_dir: "{config_source}:dev_story_location"
  story_selection_limit: 10
  tech_spec_search_dir: "{project-root}/docs"
--- a/src/modules/bmm/workflows/4-implementation/story-done/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/story-done/instructions.md
@ -8,44 +8,22 @@
 <workflow>
 <critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
-<critical>NO SEARCHING - DEV agent reads status file IN PROGRESS section to know which story was being worked on</critical>
+<critical>Workflow: Update story file status to Done</critical>
 <critical>Workflow: Update story file status, move story IN PROGRESS → DONE, move TODO → IN PROGRESS, move BACKLOG → TODO</critical>
-<step n="1" goal="Get story queue from status file">
+<step n="1" goal="Locate story and update to Done status">
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>If {{story_path}} explicitly provided → use it</action>
-  <param>mode: data</param>
+<action>Otherwise list story-\*.md files from {{story_dir}}, sort by modified time</action>
-  <param>data_request: all</param>
+<ask>Select the story to mark as Done, or enter path:</ask>
 </invoke-workflow>
-<check if="status_exists == false OR in_progress_story == ''">
+<action>Read the story file: {{story_path}}</action>
-  <output>❌ No status file or no IN PROGRESS story found.
+<action>Extract story ID and title from the file</action>
 This workflow requires an active status file with an IN PROGRESS story.
 Run `workflow-status` to check your project state.</output>
 <action>Exit workflow</action>
 </check>
 <action>Use extracted story queue:</action>
 - {{in_progress_story}}: Current story to mark done
 - {{todo_story_id}}: Next story (move to IN PROGRESS)
 - {{stories_sequence}}: All stories
 - {{stories_done}}: Completed stories
 - {{status_file_path}}: Status file to update
 </step>
 <step n="2" goal="Update the current story file status to Done">
 <action>Read the story file: {story_dir}/{current_story_file}</action>
 <action>Find the "Status:" line (usually at the top)</action>
 <action>Update story file:</action>
- Change: `Status: Ready` or `Status: In Review`
+- Change: `Status: Ready for Review` or `Status: In Review` or similar
 - To: `Status: Done`
 <action>Add completion notes if Dev Agent Record section exists:</action>
@ -55,105 +33,31 @@ Find "## Dev Agent Record" section and add:
 ```
 ### Completion Notes
 **Completed:** {{date}}
-**Definition of Done:** All acceptance criteria met, code reviewed, tests passing, deployed
+**Definition of Done:** All acceptance criteria met, code reviewed, tests passing
 ```
 <action>Save the story file</action>
 </step>
-<step n="3" goal="Update status file - advance story queue">
+<step n="2" goal="Confirm completion to user">
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<output>**Story Approved and Marked Done, {user_name}!**
  <param>mode: update</param>
  <param>action: complete_story</param>
 </invoke-workflow>
-<check if="success == false">
+✅ Story file updated: `{{story_file}}` → Status: Done
  <output>⚠️ Failed to update status: {{error}}</output>
  <output>Story file was updated, but status file update failed.</output>
 </check>
 <check if="success == true">
  <output>Status updated: Story {{completed_story}} marked done.</output>
  <check if="all_complete == true">
    <output>🎉 All stories complete! Phase 4 done!</output>
  </check>
  <check if="all_complete == false">
    <output>{{stories_remaining}} stories remaining.</output>
  </check>
 </check>
 </step>
 <step n="4" goal="Confirm completion to user">
 <action>Display summary</action>
 **Story Approved and Marked Done, {user_name}!**
 ✅ Story file updated: `{{current_story_file}}` → Status: Done
 ✅ Status file updated: Story moved IN PROGRESS → DONE
 {{#if todo_story}}✅ Next story moved: TODO → IN PROGRESS ({{todo_story_id}}: {{todo_story_title}}){{/if}}
 {{#if next_backlog_story}}✅ Next story moved: BACKLOG → TODO ({{next_backlog_story_id}}: {{next_backlog_story_title}}){{/if}}
 **Completed Story:**
- **ID:** {{current_story_id}}
+- **ID:** {{story_id}}
- **Title:** {{current_story_title}}
+- **Title:** {{story_title}}
- **File:** `{{current_story_file}}`
+- **File:** `{{story_file}}`
 - **Points:** {{current_story_points}}
 - **Completed:** {{date}}
 **Progress Summary:**
 - **Stories Completed:** {{done_count}} / {{total_stories}}
 - **Points Completed:** {{done_points}} / {{total_points}}
 - **Progress:** {{progress_percentage}}%
 {{#if all_stories_complete}}
 **🎉 ALL STORIES COMPLETE!**
 Congratulations! You have completed all stories for this project.
 **Next Steps:**
-1. Run `retrospective` workflow with SM agent to review the project
+1. Continue with next story in your backlog
-2. Close out the project
+2. Or run `retrospective` workflow if all stories are complete
-3. Celebrate! 🎊
+   </output>
   {{/if}}
 {{#if todo_story}}
 **Next Story (IN PROGRESS):**
 - **ID:** {{todo_story_id}}
 - **Title:** {{todo_story_title}}
 - **File:** `{{todo_story_file}}`
 - **Status:** {{todo_story_status}}
 **Next Steps:**
 {{#if todo_story_status == 'Draft'}}
 1. Review the drafted story {{todo_story_file}}
 2. Load SM agent and run `story-ready` workflow to approve it
 3. Then return to DEV agent to implement
   {{else}}
 4. Stay with DEV agent and run `dev-story` workflow
 5. Implement story {{todo_story_id}}
   {{/if}}
   {{/if}}
 {{#if backlog_not_empty AND todo_empty}}
 **Next Story (TODO):**
 - **ID:** {{next_backlog_story_id}}
 - **Title:** {{next_backlog_story_title}}
 **Next Steps:**
 1. Load SM agent
 2. Run `create-story` workflow to draft story {{next_backlog_story_id}}
   {{/if}}
 </step>
--- a/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml
@ -8,8 +8,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 # Workflow components
@ -18,9 +16,8 @@ instructions: "{installed_path}/instructions.md"
 # Variables and inputs
 variables:
  story_path: "" # Explicit path to story file
  story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
  status_file: "{output_folder}/bmm-workflow-status.md" # Status file to update
  auto_update_status: true # Always update status file
 # Output configuration - no output file, just status updates
 default_output_file: ""
--- a/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md
@ -8,86 +8,39 @@
 <workflow>
 <critical>This workflow is run by SM agent AFTER user reviews a drafted story and confirms it's ready for development</critical>
-<critical>NO SEARCHING - SM agent reads status file TODO section to know which story was drafted</critical>
+<critical>Simple workflow: Update story file status to Ready</critical>
 <critical>Simple workflow: Update story file status, move story TODO → IN PROGRESS, move next story BACKLOG → TODO</critical>
-<step n="1" goal="Get TODO story from status file">
+<step n="1" goal="Locate story and update status">
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>If {{story_path}} explicitly provided → use it</action>
-  <param>mode: data</param>
+<action>Otherwise list story-\*.md files from {{story_dir}}, sort by modified time</action>
-  <param>data_request: next_story</param>
+<ask>Select the drafted story to mark as Ready, or enter path:</ask>
 </invoke-workflow>
-<check if="status_exists == false OR todo_story_id == ''">
+<action>Read the story file: {{story_path}}</action>
-  <output>❌ No status file or no TODO story found.
+<action>Extract story ID and title from the file</action>
 This workflow requires an active status file with a TODO story.
 Run `workflow-status` to check your project state.</output>
 <action>Exit workflow</action>
 </check>
 <action>Use extracted story information:</action>
 - {{todo_story_id}}: Story to mark ready
 - {{todo_story_title}}: Story title
 - {{todo_story_file}}: Story file path
 - {{status_file_path}}: Status file to update
 </step>
 <step n="2" goal="Update the story file status">
 <action>Read the story file: {story_dir}/{todo_story_file}</action>
 <action>Find the "Status:" line (usually at the top)</action>
 <action>Update story file:</action>
- Change: `Status: Draft`
+- Change: `Status: Draft` or similar
 - To: `Status: Ready`
 <action>Save the story file</action>
 </step>
-<step n="3" goal="Update status file - move story TODO → IN PROGRESS">
+<step n="2" goal="Confirm completion to user">
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<output>**Story Marked Ready for Development, {user_name}!**
  <param>mode: update</param>
  <param>action: start_story</param>
 </invoke-workflow>
-<check if="success == false">
+✅ Story file updated: `{{story_file}}` → Status: Ready
  <output>⚠️ Failed to update status: {{error}}</output>
  <output>Story file was updated, but status file update failed.</output>
 </check>
-<check if="success == true">
+**Story Details:**
  <output>Status updated: Story {{in_progress_story}} ready for development.</output>
  <check if="next_todo != ''">
    <output>Next TODO: {{next_todo}}</output>
  </check>
 </check>
-</step>
+- **ID:** {{story_id}}
-
+- **Title:** {{story_title}}
-<step n="4" goal="Confirm completion to user">
+- **File:** `{{story_file}}`
 <action>Display summary</action>
 **Story Marked Ready for Development, {user_name}!**
 ✅ Story file updated: `{{todo_story_file}}` → Status: Ready
 ✅ Status file updated: Story moved TODO → IN PROGRESS
 {{#if next_story}}✅ Next story moved: BACKLOG → TODO ({{next_story_id}}: {{next_story_title}}){{/if}}
 {{#if no_more_stories}}✅ All stories have been drafted - backlog is empty{{/if}}
 **Current Story (IN PROGRESS):**
 - **ID:** {{todo_story_id}}
 - **Title:** {{todo_story_title}}
 - **File:** `{{todo_story_file}}`
 - **Status:** Ready for development
 **Next Steps:**
--- a/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml
@ -8,8 +8,6 @@ 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"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 # Workflow components
@ -18,9 +16,8 @@ instructions: "{installed_path}/instructions.md"
 # Variables and inputs
 variables:
  story_path: "" # Explicit path to story file
  story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
  status_file: "{output_folder}/bmm-workflow-status.md" # Status file to update
  auto_update_status: true # Always update status file
 # Output configuration - no output file, just status updates
 default_output_file: ""
--- a/src/modules/bmm/workflows/4-implementation/temp-testing-files/sample-epics-file.md
+++ b/src/modules/bmm/workflows/4-implementation/temp-testing-files/sample-epics-file.md
--- a/src/modules/bmm/workflows/4-implementation/temp-testing-files/sample-sprint-status-file.yaml
+++ b/src/modules/bmm/workflows/4-implementation/temp-testing-files/sample-sprint-status-file.yaml
@ -0,0 +1,93 @@
 # generated: 2025-10-21
 # project: todo1
 # project_key: todo1
 # tracking_system: file-system
 # story_location: {project-root}/docs/stories
 # STATUS DEFINITIONS:
 # ==================
 # Epic Status:
 #   - backlog: Epic exists in epic file but not contexted
 #   - contexted: Epic tech context created (required before drafting stories)
 #
 # 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
 #
 # Retrospective Status:
 #   - optional: Can be completed but not required
 #   - completed: Retrospective has been done
 #
 # 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'
 generated: 2025-10-21
 project: todo1
 project_key: todo1
 tracking_system: file-system
 story_location: "{project-root}/docs/stories"
 development_status:
  epic-1: backlog
  1-1-project-foundation-development-environment: backlog
  1-2-app-shell-navigation-framework: backlog
  1-3-user-authentication-account-management: backlog
  1-4-plant-data-model-species-database: backlog
  1-5-add-plant-manual-species-selection: backlog
  1-6-plant-photo-identification-integration: backlog
  1-7-plant-naming-profile-creation: backlog
  1-8-plant-collection-home-screen: backlog
  1-9-plant-detail-view: backlog
  1-10-cloud-photo-storage-display: backlog
  epic-1-retrospective: optional
  epic-2: backlog
  2-1-personality-system-data-model: backlog
  2-2-personality-prototype-testing: backlog
  2-3-llm-integration-api-setup: backlog
  2-4-chat-interface-ui: backlog
  2-5-conversational-ai-system: backlog
  2-6-graceful-degradation-library: backlog
  2-7-response-caching-cost-optimization: backlog
  2-8-personality-driven-care-reminders: backlog
  2-9-push-notification-system: backlog
  2-10-reminder-intelligence-adaptation: backlog
  2-11-mood-system-visual-indicators: backlog
  2-12-mood-calculation-logic-time-based: backlog
  2-13-personality-introduction-onboarding: backlog
  2-14-personality-tone-testing-calibration: backlog
  2-15-emergency-tone-adjustment-system: backlog
  2-16-api-reliability-monitoring-alerts: backlog
  epic-2-retrospective: optional
  epic-3: backlog
  3-1-care-schedule-data-model: backlog
  3-2-auto-generated-care-schedules: backlog
  3-3-manual-care-logging: backlog
  3-4-care-history-view: backlog
  3-5-customizable-care-schedules: backlog
  3-6-photo-timeline-tracking: backlog
  3-7-health-status-visualization: backlog
  3-8-enhanced-mood-calculation-care-data: backlog
  epic-3-retrospective: optional
  epic-4: backlog
  4-1-shareable-content-card-design-system: backlog
  4-2-share-plant-profile: backlog
  4-3-share-conversation-snippets: backlog
  4-4-share-growth-progress: backlog
  4-5-share-care-achievements: backlog
  4-6-freemium-tier-definition-enforcement: backlog
  4-7-premium-upgrade-flow-paywall: backlog
  4-8-payment-processing-subscription-management: backlog
  4-9-premium-analytics-dashboard: backlog
  4-10-trial-conversion-optimization: backlog
  epic-4-retrospective: optional
--- a/src/modules/bmm/workflows/4-implementation/temp-testing-files/sample-workflow-status.md
+++ b/src/modules/bmm/workflows/4-implementation/temp-testing-files/sample-workflow-status.md
@ -0,0 +1,65 @@
 # BMM Workflow Status
 ## Project Configuration
 PROJECT_NAME: todo1
 PROJECT_TYPE: software
 PROJECT_LEVEL: 3
 FIELD_TYPE: greenfield
 START_DATE: 2025-10-18
 WORKFLOW_PATH: greenfield-level-3.yaml
 ## Current State
 CURRENT_PHASE: 4-implementation
 CURRENT_WORKFLOW: tech-spec
 CURRENT_AGENT: architect
 PHASE_1_COMPLETE: true
 PHASE_2_COMPLETE: true
 PHASE_3_COMPLETE: true
 PHASE_4_COMPLETE: false
 ## Next Action
 NEXT_ACTION: Create technical specification for Epic 1 (Foundation & Core Plant Management)
 NEXT_COMMAND: /bmad:bmm:agents:architect then run \*tech-spec for Epic 1
 NEXT_AGENT: architect
 ## Story Backlog
 **Epic 1:** 10 stories - Foundation & Core Plant Management
 **Epic 2:** 16 stories - AI Personality System & Engagement Loop
 **Epic 3:** 8 stories - Care Scheduling, Photos & Growth Tracking
 **Epic 4:** 10 stories - Social Sharing & Premium Monetization
 **Total: 44 stories** (see epics.md for detailed breakdown)
 ## Workflow Progress
 **Phase 1 - Analysis:**
 - ✅ Brainstorm Project (2025-10-18)
 - ⬜ Research (optional - skipped)
 - ✅ Product Brief (2025-10-18)
 **Phase 2 - Planning:**
 - ✅ PRD (2025-10-19) - 44 stories across 4 epics defined
 - ✅ UX Spec (2025-10-19) - Comprehensive design system, user flows, components
 **Phase 3 - Architecture (Required for Level 3):**
 - ✅ Architecture (2025-10-19)
 - ✅ Assess Project Ready (2025-10-19)
 **Phase 4 - Implementation:**
 - 🎯 Tech Spec for Epic 1 (next up)
 - Per Epic: Tech Spec (JIT) → Stories
 - Per Story: Create → Context → Validate → Ready → Develop → Review → Approved
 - Epic Retrospectives after each epic
 ---
 _Last Updated: 2025-10-19 (Phase 3 Complete - Starting Implementation Phase)_
 _Status Version: 6.0_
--- a/src/modules/bmm/workflows/helpers/sprint-status/README.md
+++ b/src/modules/bmm/workflows/helpers/sprint-status/README.md
@ -0,0 +1,292 @@
 # 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
--- a/src/modules/bmm/workflows/helpers/sprint-status/instructions.md
+++ b/src/modules/bmm/workflows/helpers/sprint-status/instructions.md
@ -0,0 +1,542 @@
 # 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>
--- a/src/modules/bmm/workflows/helpers/sprint-status/workflow.yaml
+++ b/src/modules/bmm/workflows/helpers/sprint-status/workflow.yaml
@ -0,0 +1,53 @@
 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
--- a/src/modules/bmm/workflows/workflow-status/instructions.md
+++ b/src/modules/bmm/workflows/workflow-status/instructions.md
@ -61,8 +61,6 @@ Parse these fields:
 - FIELD_TYPE
 - CURRENT_PHASE
 - CURRENT_WORKFLOW
 - TODO_STORY
 - IN_PROGRESS_STORY
 - NEXT_ACTION
 - NEXT_COMMAND
 - NEXT_AGENT
@ -204,27 +202,6 @@ Your choice:</ask>
  <action>Parse status file completely</action>
  <template-output>status_exists = true</template-output>
  <check if="data_request == next_story">
    <action>Extract from Development Queue section</action>
    <template-output>todo_story_id = {{TODO_STORY}}</template-output>
    <template-output>todo_story_title = {{TODO_TITLE}}</template-output>
    <template-output>in_progress_story = {{IN_PROGRESS_STORY}}</template-output>
    <template-output>stories_sequence = {{STORIES_SEQUENCE}}</template-output>
    <template-output>stories_done = {{STORIES_DONE}}</template-output>
    <action>Determine story file path based on ID format</action>
    <check if='todo_story_id matches "N.M" format'>
      <template-output>todo_story_file = "story-{{N}}.{{M}}.md"</template-output>
    </check>
    <check if='todo_story_id matches "slug-N" format'>
      <template-output>todo_story_file = "story-{{slug}}-{{N}}.md"</template-output>
    </check>
    <check if='todo_story_id matches "slug" format'>
      <template-output>todo_story_file = "story-{{slug}}.md"</template-output>
    </check>
  </check>
  <check if="data_request == project_config">
    <template-output>project_name = {{PROJECT_NAME}}</template-output>
    <template-output>project_type = {{PROJECT_TYPE}}</template-output>
@ -305,10 +282,6 @@ Your choice:</ask>
    - Update PHASE_X_COMPLETE to true
    - Update CURRENT_PHASE to next phase (if applicable)
    <check if="populate_stories_from parameter provided">
      <action>Trigger story population (see populate_stories action below)</action>
    </check>
    <action>Update LAST_UPDATED to {{date}}</action>
    <action>Save status file</action>
@ -319,140 +292,6 @@ Your choice:</ask>
  </check>
  <!-- ============================================= -->
  <!-- ACTION: populate_stories -->
  <!-- ============================================= -->
  <check if="action == populate_stories">
    <action>Get {{epics_file}} parameter (required - path to epics.md)</action>
    <action>Read {{epics_file}} completely</action>
    <action>Parse all story definitions from epic sections</action>
    <action>Extract story IDs in sequential order (e.g., story-1.1, story-1.2, story-2.1...)</action>
    <action>Extract story titles for each ID</action>
    <action>Build ordered story list:</action>
    - Format: JSON array or comma-separated
    - Example: ["story-1.1", "story-1.2", "story-1.3", "story-2.1"]
    <action>Update status file:</action>
    - STORIES_SEQUENCE: {{ordered_story_list}}
    - TODO_STORY: {{first_story_id}}
    - TODO_TITLE: {{first_story_title}}
    - IN_PROGRESS_STORY: (empty)
    - IN_PROGRESS_TITLE: (empty)
    - STORIES_DONE: []
    <action>Update LAST_UPDATED to {{date}}</action>
    <action>Save status file</action>
    <template-output>success = true</template-output>
    <template-output>total_stories = {{count}}</template-output>
    <template-output>first_story = {{first_story_id}}</template-output>
  </check>
  <!-- ============================================= -->
  <!-- ACTION: start_story (TODO → IN PROGRESS) -->
  <!-- ============================================= -->
  <check if="action == start_story">
    <action>Get current TODO_STORY from status file</action>
    <check if="TODO_STORY is empty">
      <template-output>success = false</template-output>
      <template-output>error = "No TODO story to start"</template-output>
      <action>Return to calling workflow</action>
    </check>
    <action>Move TODO → IN PROGRESS:</action>
    - IN_PROGRESS_STORY: {{current TODO_STORY}}
    - IN_PROGRESS_TITLE: {{current TODO_TITLE}}
    <action>Find next story in STORIES_SEQUENCE after current TODO_STORY</action>
    <check if="next story found">
      <action>Move next story to TODO:</action>
      - TODO_STORY: {{next_story_id}}
      - TODO_TITLE: {{next_story_title}}
    </check>
    <check if="no next story">
      <action>Clear TODO:</action>
      - TODO_STORY: (empty)
      - TODO_TITLE: (empty)
    </check>
    <action>Update NEXT_ACTION and NEXT_COMMAND:</action>
    - NEXT_ACTION: "Implement story {{IN_PROGRESS_STORY}}"
    - NEXT_COMMAND: "dev-story"
    - NEXT_AGENT: "dev"
    <action>Update LAST_UPDATED to {{date}}</action>
    <action>Save status file</action>
    <template-output>success = true</template-output>
    <template-output>in_progress_story = {{IN_PROGRESS_STORY}}</template-output>
    <template-output>next_todo = {{TODO_STORY or empty}}</template-output>
  </check>
  <!-- ============================================= -->
  <!-- ACTION: complete_story (IN PROGRESS → DONE) -->
  <!-- ============================================= -->
  <check if="action == complete_story">
    <action>Get current IN_PROGRESS_STORY from status file</action>
    <check if="IN_PROGRESS_STORY is empty">
      <template-output>success = false</template-output>
      <template-output>error = "No IN PROGRESS story to complete"</template-output>
      <action>Return to calling workflow</action>
    </check>
    <action>Move IN PROGRESS → DONE:</action>
    - Add {{IN_PROGRESS_STORY}} to STORIES_DONE list
    <action>Move TODO → IN PROGRESS:</action>
    - IN_PROGRESS_STORY: {{current TODO_STORY}}
    - IN_PROGRESS_TITLE: {{current TODO_TITLE}}
    <action>Find next story in STORIES_SEQUENCE after current TODO_STORY</action>
    <check if="next story found">
      <action>Move next story to TODO:</action>
      - TODO_STORY: {{next_story_id}}
      - TODO_TITLE: {{next_story_title}}
    </check>
    <check if="no next story">
      <action>Clear TODO:</action>
      - TODO_STORY: (empty)
      - TODO_TITLE: (empty)
    </check>
    <check if="all stories complete (STORIES_DONE == STORIES_SEQUENCE)">
      <action>Mark Phase 4 complete:</action>
      - PHASE_4_COMPLETE: true
      - CURRENT_WORKFLOW: "Complete"
      - NEXT_ACTION: "All stories complete!"
      - NEXT_COMMAND: (empty)
    </check>
    <check if="stories remain">
      <action>Update NEXT_ACTION:</action>
      - If IN_PROGRESS_STORY exists: "Implement story {{IN_PROGRESS_STORY}}"
      - If only TODO_STORY exists: "Draft story {{TODO_STORY}}"
      - NEXT_COMMAND: "dev-story" or "create-story"
    </check>
    <action>Update LAST_UPDATED to {{date}}</action>
    <action>Save status file</action>
    <template-output>success = true</template-output>
    <template-output>completed_story = {{completed_story_id}}</template-output>
    <template-output>stories_remaining = {{count}}</template-output>
    <template-output>all_complete = {{true/false}}</template-output>
  </check>
  <!-- ============================================= -->
  <!-- ACTION: set_current_workflow (manual override) -->
  <!-- ============================================= -->
@ -481,7 +320,7 @@ Your choice:</ask>
  <!-- ============================================= -->
  <check if="action not recognized">
    <template-output>success = false</template-output>
-    <template-output>error = "Unknown action: {{action}}. Valid actions: complete_workflow, populate_stories, start_story, complete_story, set_current_workflow"</template-output>
+    <template-output>error = "Unknown action: {{action}}. Valid actions: complete_workflow, set_current_workflow"</template-output>
  </check>
 </check>
--- a/src/modules/bmm/workflows/workflow-status/workflow-status-template.md
+++ b/src/modules/bmm/workflows/workflow-status/workflow-status-template.md
@ -19,15 +19,6 @@ PHASE_2_COMPLETE: {{phase_2_complete}}
 PHASE_3_COMPLETE: {{phase_3_complete}}
 PHASE_4_COMPLETE: {{phase_4_complete}}
 ## Development Queue
 STORIES_SEQUENCE: {{ordered_story_list}}
 TODO_STORY: {{todo_story}}
 TODO_TITLE: {{todo_title}}
 IN_PROGRESS_STORY: {{in_progress_story}}
 IN_PROGRESS_TITLE: {{in_progress_title}}
 STORIES_DONE: {{completed_story_list}}
 ## Next Action
 NEXT_ACTION: {{next_action}}