use sprint plan for al workflow level 4 implementations

bmd/bmad-custom-module-installer-plan.md

@@ -207,7 +207,7 @@ User runs: npm run install:bmad
 
 ---
 
-## Proposed Solution Architecture
+## Proposed Architecture
 
 ### New Command: `install-module`
 

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

docs/sprint-status.yaml

@@ -0,0 +1,97 @@
+# generated: 2025-10-21
+# project: MyPlantFamily
+# project_key: MyPlantFamily
+# 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: MyPlantFamily
+project_key: MyPlantFamily
+tracking_system: file-system
+story_location: "{project-root}/docs/stories"
+
+development_status:
+  # Epic 1: Foundation & Core Plant Management
+  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: AI Personality System & Engagement Loop
+  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: Care Scheduling, Photos & Growth Tracking
+  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: Social Sharing & Premium Monetization
+  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

src/modules/bmm/README.md

@@ -43,7 +43,7 @@ The heart of BMM - structured workflows for the four development phases:
    - `story-ready` - Approve story for development (SM agent)
    - `story-context` - Expertise injection (SM agent)
    - `dev-story` - Implementation (DEV agent)
-   - `story-approved` - Mark story done (DEV agent)
+   - `story-done` - Mark story done (DEV agent)
    - `review-story` - Quality validation (DEV/SR agent)
    - `correct-course` - Issue resolution
    - `retrospective` - Continuous improvement
@@ -101,7 +101,7 @@ BACKLOG → TODO → IN PROGRESS → DONE
 - **IN PROGRESS**: Single story approved for DEV to implement
 - **DONE**: Completed stories with dates and points
 
-Agents never search for "next story" - they always read the exact story from the status file. Simple workflows (`story-ready`, `story-approved`) advance the queue automatically.
+Agents never search for "next story" - they always read the exact story from the status file. Simple workflows (`story-ready`, `story-done`) advance the queue automatically.
 
 ### Context Injection
 

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

@@ -34,8 +34,8 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml"
       description: "Execute Dev Story workflow, implementing tasks and tests, or performing updates to the story"
 
-    - trigger: story-approved
-      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-approved/workflow.yaml"
+    - trigger: story-done
+      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-done/workflow.yaml"
       description: Mark story done after DoD complete
 
     - trigger: review

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

@@ -25,6 +25,10 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations
 
+    - trigger: sprint-planning
+      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
+      description: Generate or update sprint-status.yaml from epic files
+
     - trigger: create-story
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
       description: Create a Draft Story with Context

src/modules/bmm/testarch/README.md

@@ -139,7 +139,7 @@ This complexity **requires specialized documentation** (this guide), **extensive
 <details>
 <summary>Worked Example – “Nova CRM” Greenfield Feature</summary>
 
-1. **Planning:** Analyst runs `*product-brief`; PM executes `*plan-project` to produce PRD and epics; Architect completes `*solution-architecture` for the new module.
+1. **Planning:** Analyst runs `*product-brief`; PM executes `*plan-project` to produce PRD and epics; Architect completes `*create-architecture` for the new module.
 2. **Setup:** TEA checks harness via `*framework`, configures `*ci`, and runs `*test-design` to capture risk/coverage plans.
 3. **Story Prep:** Scrum Master generates the story via `*create-story`; PO validates using `*solutioning-gate-check`.
 4. **Implementation:** TEA optionally runs `*atdd`; Dev implements with guidance from failing tests and the plan.
@@ -174,7 +174,7 @@ This complexity **requires specialized documentation** (this guide), **extensive
 <details>
 <summary>Worked Example – “Atlas Payments” Brownfield Story</summary>
 
-1. **Context Refresh:** Analyst reruns `*product-brief`; PM executes `*plan-project` to update PRD, analysis, and `epics.md`; Architect triggers `*solution-architecture` capturing legacy payment flows.
+1. **Context Refresh:** Analyst reruns `*product-brief`; PM executes `*plan-project` to update PRD, analysis, and `epics.md`; Architect triggers `*create-architecture` capturing legacy payment flows.
 2. **Baseline Coverage:** TEA executes `*trace` to record current coverage in `docs/qa/assessments/atlas-payment-trace.md`.
 3. **Risk and Design:** `*test-design` flags settlement edge cases, plans mitigations, and allocates new API/E2E scenarios with P0 priorities.
 4. **Story Prep:** Scrum Master generates `stories/story-1.1.md` via `*create-story`, automatically pulling updated context.

src/modules/bmm/workflows/1-analysis/brainstorm-project/README.md

@@ -4,7 +4,7 @@ last-redoc-date: 2025-10-01
 
 # Project Brainstorming Workflow
 
-This workflow facilitates structured ideation for non-game software projects through systematic exploration of problem spaces, solution architectures, and implementation strategies. Unlike traditional requirement gathering, it employs creative techniques to uncover non-obvious approaches and identify innovative solutions that address core business needs while considering technical constraints and organizational capabilities.
+This workflow facilitates structured ideation for non-game software projects through systematic exploration of problem spaces, architectures, and implementation strategies. Unlike traditional requirement gathering, it employs creative techniques to uncover non-obvious approaches and identify innovative solutions that address core business needs while considering technical constraints and organizational capabilities.
 
 The workflow operates through a project-specific context framework that captures business objectives, technical environment, stakeholder needs, and organizational constraints. It generates multiple solution vectors through parallel ideation tracks: architectural approaches, user experience paradigms, integration patterns, and value delivery mechanisms. Each track produces concrete proposals that are evaluated against feasibility, impact, and alignment with strategic objectives.
 
@@ -23,7 +23,7 @@ bmad bmm 1-analysis brainstorm-project
 
 ## Outputs
 
-- **Solution Architecture Proposals**: Multiple technical approaches with trade-off analysis and feasibility assessments
+- **Architecture Proposals**: Multiple technical approaches with trade-off analysis and feasibility assessments
 - **Value Delivery Framework**: Prioritized feature concepts aligned with business objectives and user needs
 - **Risk and Opportunity Analysis**: Identified technical dependencies, integration challenges, and innovation opportunities
 - **Strategic Recommendation**: Synthesized direction with rationale and implementation considerations

src/modules/bmm/workflows/2-plan-workflows/README.md

@@ -27,25 +27,25 @@ The workflow routes to different planning approaches based on project level:
 **Planning:** PRD (product-focused) + Tech-spec (technical planning)
 **Output:** `PRD.md`, `epics.md`, `tech-spec.md`
 **Next Phase:** Tech-spec workflow (lightweight solutioning), then implementation (Phase 4)
-**Note:** Level 2 uses tech-spec instead of full solution-architecture to keep planning lightweight
+**Note:** Level 2 uses tech-spec instead of full architecture to keep planning lightweight
 
 ### Level 3 - Medium Project (15-40 stories, 2-5 epics)
 
 **Planning:** PRD (strategic product document)
 **Output:** `PRD.md`, `epics.md`
-**Next Phase:** Solution-architecture workflow (Phase 3), then implementation (Phase 4)
+**Next Phase:** create-architecture workflow (Phase 3), then implementation (Phase 4)
 
 ### Level 4 - Large/Enterprise Project (40-100+ stories, 5-10 epics)
 
 **Planning:** PRD (comprehensive product specification)
 **Output:** `PRD.md`, `epics.md`
-**Next Phase:** Solution-architecture workflow (Phase 3), then implementation (Phase 4)
+**Next Phase:** create-architecture workflow (Phase 3), then implementation (Phase 4)
 
 **Critical Distinction:**
 
 - **Levels 0-1:** No PRD, tech-spec only
 - **Level 2:** PRD + tech-spec (skips full architecture)
-- **Levels 3-4:** PRD → full solution-architecture workflow
+- **Levels 3-4:** PRD → full create-architecture workflow
 
 Critical to v6's flow improvement is this workflow's integration with the bmm-workflow-status.md tracking document, which maintains project state across sessions, tracks which agents participate in each phase, and provides continuity for multi-session planning efforts. The workflow can resume from any point, intelligently detecting existing artifacts and determining next steps without redundant work. For UX-heavy projects, it can generate standalone UX specifications or AI frontend prompts from existing specs.
 
@@ -138,7 +138,7 @@ The workflow adapts automatically based on project assessment, but key configura
 
 - PRD workflow (comprehensive product specification)
 - Generates `PRD.md` and `epics.md`
-- Hands off to Phase 3 (solution-architecture workflow)
+- Hands off to Phase 3 (create-architecture workflow)
 - Full architecture design before implementation
 
 ### Phase 3: Validation and Handoff (Final steps)
@@ -177,7 +177,7 @@ The workflow adapts automatically based on project assessment, but key configura
 
 - `PRD.md` - Comprehensive product specification
 - `epics.md` - Complete epic/story breakdown
-- Hands off to solution-architecture workflow (Phase 3)
+- Hands off to create-architecture workflow (Phase 3)
 - `architecture.md` - Generated by architect workflow
 - Then to implementation
 

src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md

@@ -390,10 +390,10 @@ Since this is a Level {{project_level}} game project, you need solutioning for p
 
 <action>Generate comprehensive checklist based on project analysis</action>
 
-### Phase 1: Solution Architecture and Engine Selection
+### Phase 1: Architecture and Engine Selection
 
 - [ ] **Run solutioning workflow** (REQUIRED)
-  - Command: `workflow solution-architecture`
+  - Command: `workflow create-architecture`
   - Input: GDD.md, bmm-workflow-status.md
   - Output: architecture.md with engine/platform specifics
   - Note: Registry.csv will provide engine-specific guidance

src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md

@@ -84,7 +84,7 @@
 
 ### If Level 3-4:
 
-- [ ] PRD provides sufficient context for solution-architecture workflow
+- [ ] PRD provides sufficient context for create-architecture workflow
 - [ ] Epic structure supports phased delivery approach
 - [ ] Clear value delivery path through epic sequence
 

src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md

@@ -438,7 +438,7 @@ For each epic from the epic list, expand with full story details:
 {{#if project_level >= 3}}
 
 - Review PRD and epics with stakeholders
-- **Next:** Run `solution-architecture` for full technical design
+- **Next:** Run `create-architecture` for full technical design
 - Then proceed to implementation
   {{/if}}
 

src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml

@@ -1,6 +1,6 @@
 # Product Requirements Document (PRD) Workflow
 name: prd
-description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to solution-architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow."
+description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow."
 author: "BMad"
 
 # Critical variables from config
@@ -35,7 +35,7 @@ recommended_inputs:
 
 web_bundle:
   name: "prd"
-  description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to solution-architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow."
+  description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow."
   author: "BMad"
   instructions: "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md"
   web_bundle_files:

src/modules/bmm/workflows/3-solutioning/architecture/instructions.md

@@ -8,7 +8,7 @@
 <critical>The goal is ARCHITECTURAL DECISIONS that prevent AI agent conflicts, not detailed implementation specs</critical>
 <critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
-<critical>This workflow replaces solution-architecture with a conversation-driven approach</critical>
+<critical>This workflow replaces architecture with a conversation-driven approach</critical>
 
 <step n="0" goal="Validate workflow and extract project configuration">
 

src/modules/bmm/workflows/3-solutioning/architecture/readme.md

@@ -85,7 +85,7 @@ Step 12: Final review and update workflow status
 - **checklist.md** - Validation requirements for the output document
 - **architecture-template.md** - Strict format for the final document
 
-## How It's Different from Old Solution-Architecture
+## How It's Different from Old architecture
 
 | Aspect               | Old Workflow                                 | New Workflow                                    |
 | -------------------- | -------------------------------------------- | ----------------------------------------------- |
@@ -266,9 +266,9 @@ This workflow assumes:
 - AI agents need clear constraints to prevent conflicts
 - The architecture document is for agents, not humans
 
-## Migration from solution-architecture
+## Migration from architecture
 
-Projects using the old `solution-architecture` workflow should:
+Projects using the old `architecture` workflow should:
 
 1. Complete any in-progress architecture work
 2. Use `architecture` for new projects
@@ -315,4 +315,4 @@ Projects using the old `solution-architecture` workflow should:
 - Starter decisions are documented as "PROVIDED BY STARTER"
 - First implementation story uses starter initialization command
 
-  1.0.0 - Initial release replacing solution-architecture workflow
+  1.0.0 - Initial release replacing architecture workflow

src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml

@@ -39,7 +39,7 @@ default_output_file: "{output_folder}/architecture.md"
 
 # Workflow metadata
 version: "1.3.2"
-replaces: "solution-architecture"
+replaces: "architecture"
 paradigm: "facilitation-driven"
 execution_time: "30-90 minutes depending on user skill level"
 features:

src/modules/bmm/workflows/4-implementation/README.md

@@ -0,0 +1,221 @@
+# Phase 4: Implementation
+
+## Overview
+
+Phase 4 is where planning transitions into actual development. This phase manages the iterative implementation of stories defined in the epic files, tracking their progress through a well-defined status workflow.
+
+## Status Definitions
+
+### Epic Status
+
+Epics progress through a simple two-state flow:
+
+| Status        | Description                                                                                                                                     | Next Status |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| **backlog**   | Epic exists in epic file but technical context has not been created                                                                             | contexted   |
+| **contexted** | Epic technical context has been created via `epic-tech-context` workflow. This is a prerequisite before any stories in the epic can be drafted. | -           |
+
+**File Indicators:**
+
+- `backlog`: No `epic-{n}-context.md` file exists
+- `contexted`: `{output_folder}/epic-{n}-context.md` file exists
+
+### Story Status
+
+Stories progress through a six-state flow representing their journey from idea to implementation:
+
+| Status            | Description                                                                        | Set By        | Next Status   |
+| ----------------- | ---------------------------------------------------------------------------------- | ------------- | ------------- |
+| **backlog**       | Story only exists in the epic file, no work has begun                              | Initial state | drafted       |
+| **drafted**       | Story file has been created via `create-story` workflow                            | SM Agent      | ready-for-dev |
+| **ready-for-dev** | Story has been drafted, approved, and context created via `story-context` workflow | SM Agent      | in-progress   |
+| **in-progress**   | Developer is actively implementing the story                                       | Dev Agent     | review        |
+| **review**        | Implementation complete, under SM review via `review-story` workflow               | Dev Agent     | done          |
+| **done**          | Story has been reviewed and completed                                              | Dev Agent     | -             |
+
+**File Indicators:**
+
+- `backlog`: No story file exists
+- `drafted`: `{story_dir}/{story-key}.md` file exists (e.g., `1-1-user-auth.md`)
+- `ready-for-dev`: Both story file and context exist (e.g., `1-1-user-auth-context.md`)
+- `in-progress`, `review`, `done`: Manual status updates in sprint-status.yaml
+
+### Retrospective Status
+
+Optional retrospectives can be completed after an epic:
+
+| Status        | Description                                        |
+| ------------- | -------------------------------------------------- |
+| **optional**  | Retrospective can be completed but is not required |
+| **completed** | Retrospective has been completed                   |
+
+## Status Transitions
+
+### Epic Flow
+
+```mermaid
+graph LR
+    backlog --> contexted[contexted via epic-tech-context]
+```
+
+### Story Flow
+
+```mermaid
+graph LR
+    backlog --> drafted[drafted via create-story]
+    drafted --> ready[ready-for-dev via story-context]
+    ready --> progress[in-progress - dev starts]
+    progress --> review[review via review-story]
+    review --> done[done - dev completes]
+```
+
+## Sprint Status Management
+
+The `sprint-status.yaml` file is the single source of truth for tracking all work items. It contains:
+
+- All epics with their current status
+- All stories with their current status
+- Retrospective placeholders for each epic
+- Clear documentation of status definitions
+
+### Example Sprint Status File
+
+```yaml
+development_status:
+  epic-1: contexted
+  1-1-project-foundation: done
+  1-2-app-shell: done
+  1-3-user-authentication: in-progress
+  1-4-plant-data-model: ready-for-dev
+  1-5-add-plant-manual: drafted
+  1-6-photo-identification: backlog
+  1-7-plant-naming: backlog
+  epic-1-retrospective: optional
+
+  epic-2: backlog
+  2-1-personality-system: backlog
+  2-2-chat-interface: backlog
+  2-3-llm-integration: backlog
+  epic-2-retrospective: optional
+```
+
+## Workflows in Phase 4
+
+### Core Workflows
+
+| Workflow              | Purpose                                            | Updates Status                      |
+| --------------------- | -------------------------------------------------- | ----------------------------------- |
+| **sprint-planning**   | Generate/update sprint-status.yaml from epic files | Auto-detects file-based statuses    |
+| **epic-tech-context** | Create technical context for an epic               | epic: backlog → contexted           |
+| **create-story**      | Draft a story from epics/PRD                       | story: backlog → drafted            |
+| **story-context**     | Add implementation context to story                | story: drafted → ready-for-dev      |
+| **dev-story**         | Developer implements the story                     | story: ready-for-dev → in-progress  |
+| **review-story**      | SM reviews implementation                          | story: in-progress → review         |
+| **retrospective**     | Conduct epic retrospective                         | retrospective: optional → completed |
+| **correct-course**    | Course correction when needed                      | Various status updates              |
+
+### Sprint Planning Workflow
+
+The `sprint-planning` workflow is the foundation of Phase 4. It:
+
+1. **Parses all epic files** (`epic*.md` or `epics.md`)
+2. **Extracts all epics and stories** maintaining their order
+3. **Auto-detects current status** based on existing files:
+   - Checks for epic context files
+   - Checks for story files
+   - Checks for story context files
+4. **Generates sprint-status.yaml** with current reality
+5. **Preserves manual status updates** (won't downgrade statuses)
+
+Run this workflow:
+
+- Initially after Phase 3 completion
+- After creating epic contexts
+- Periodically to sync file-based status
+- To verify current project state
+
+### Workflow Guidelines
+
+1. **Epic Context First**: Epics should be contexted before drafting their stories
+2. **Flexible Parallelism**: Multiple stories can be in-progress based on team capacity
+3. **Sequential Default**: Stories within an epic are typically worked in order
+4. **Learning Transfer**: SM drafts next story after previous is done, incorporating learnings
+5. **Review Flow**: Dev moves to review, SM reviews, Dev moves to done
+
+## Agent Responsibilities
+
+### SM (Scrum Master) Agent
+
+- Run `sprint-planning` to generate initial status
+- Create epic contexts (`epic-tech-context`)
+- Draft stories (`create-story`)
+- Create story contexts (`story-context`)
+- Review completed work (`review-story`)
+- Update status in sprint-status.yaml
+
+### Developer Agent
+
+- Check sprint-status.yaml for `ready-for-dev` stories
+- Update status to `in-progress` when starting
+- Implement stories (`dev-story`)
+- Move to `review` when complete
+- Address review feedback
+- Update to `done` after approval
+
+### Test Architect
+
+- Monitor stories entering `review` status
+- Track epic progress
+- Identify when retrospectives needed
+- Validate implementation quality
+
+## Best Practices
+
+1. **Always run sprint-planning first** to establish current state
+2. **Update status immediately** as work progresses
+3. **Check sprint-status.yaml** before starting any work
+4. **Preserve learning** by drafting stories sequentially when possible
+5. **Document decisions** in story and context files
+
+## Naming Conventions
+
+### Story File Naming
+
+- Format: `{epic}-{story}-{kebab-title}.md`
+- Example: `1-1-user-authentication.md`
+- Avoids YAML float parsing issues (1.1 vs 1.10)
+- Makes files self-descriptive
+
+### Git Branch Naming
+
+- Format: `feat/{epic}-{story}-{kebab-title}`
+- Example: `feat/1-1-user-authentication`
+- Consistent with story file naming
+- Clean for branch management
+
+## File Structure
+
+```
+{output_folder}/
+├── sprint-status.yaml                      # Sprint status tracking
+├── epic*.md or epics.md                    # Epic definitions
+├── epic-1-context.md                       # Epic technical contexts
+├── epic-2-context.md
+└── stories/
+    ├── 1-1-user-authentication.md          # Story drafts
+    ├── 1-1-user-authentication-context.md  # Story contexts
+    ├── 1-2-account-management.md
+    ├── 1-2-account-management-context.md
+    └── ...
+```
+
+## Next Steps
+
+After Phase 4 implementation, projects typically move to:
+
+- Deployment and release
+- User acceptance testing
+- Production monitoring
+- Maintenance and updates
+
+The sprint-status.yaml file provides a complete audit trail of the development process and can be used for project reporting and retrospectives.

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>

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"

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

@@ -4,7 +4,7 @@ validation-target: 'Newly generated story markdown file'
 required-inputs:
   - 'epics.md (preferred) or PRD'
 optional-inputs:
-  - 'solution-architecture document for architecture context'
+  - 'architecture document for architecture context'
 validation-rules:
   - 'Story structure matches sections: Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Change Log, Dev Agent Record'
   - 'Dev Notes include Project Structure Notes and References subsections'

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

@@ -3,12 +3,9 @@
 ```xml
 <critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
-<critical>Default execution mode: #yolo (minimal prompts). Only elicit if absolutely required and {{non_interactive}} == false.</critical>
-
-<critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
+<critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
 
 <workflow>
 
@@ -16,7 +13,7 @@
     <action>Resolve variables from config_source: story_dir (dev_story_location), output_folder, user_name, communication_language. If story_dir missing and {{non_interactive}} == false → ASK user to provide a stories directory and update variable. If {{non_interactive}} == true and missing, HALT with a clear message.</action>
     <action>Create {{story_dir}} if it does not exist</action>
     <action>Resolve installed component paths from workflow.yaml: template, instructions, validation</action>
-    <action>Resolve recommended inputs if present: epics_file, prd_file, solution-architecture_file</action>
+    <action>Resolve recommended inputs if present: epics_file, prd_file, architecture_file</action>
   </step>
 
   <step n="2" goal="Discover and load source documents">
@@ -25,51 +22,54 @@
       1) tech_spec_file (epic-scoped)
       2) epics_file (acceptance criteria and breakdown)
       3) prd_file (business requirements and constraints)
-      4) solution-architecture_file (architecture constraints)
+      4) architecture_file (architecture constraints)
       5) Architecture docs under docs/ and output_folder/: tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md, backend-architecture.md, frontend-architecture.md, data-models.md, database-schema.md, rest-api-spec.md, external-apis.md (include if present)
     </action>
     <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>
+  <step n="3" goal="Determine target story from sprint status">
+    <action>Query sprint-status for next backlog story:</action>
+
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: get_next_story</param>
+      <param>filter_status: backlog</param>
     </invoke-workflow>
 
-    <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
+    <check if="{{result_found}} == false">
+      <output>📋 No backlog stories found in sprint-status.yaml
 
-      <critical>This is the PRIMARY source - DO NOT search or guess</critical>
+All stories are either already drafted or completed.
 
-      <action>Set {{story_path}} = {story_dir}/{{todo_story_file}}</action>
-      <action>Skip legacy discovery in Step 3</action>
+**Options:**
+1. Run sprint-planning to refresh story tracking
+2. Load PM agent and run correct-course to add more stories
+3. Check if current sprint is complete
+      </output>
+      <action>HALT</action>
     </check>
 
-    <check if="status_exists == false OR todo_story_id == ''">
-      <action>Fall back to legacy story discovery in Step 3</action>
-    </check>
-  </step>
+    <action>Parse {{result_story_key}} to extract epic_num, story_num, and story_title
+      Example: "1-2-user-authentication" → epic_num=1, story_num=2, title="user-authentication"
+    </action>
+    <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
 
-  <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>
-    <check>If files found → Parse epic_num and story_num; pick the highest pair</check>
-    <action>Open the latest story (if exists) and read Status</action>
-    <check>If Status != Done/Approved and {{non_interactive}} == true → TARGET the latest story for update (do not create a new one)</check>
-    <check>If Status == Done/Approved → Candidate next story is {{epic_num}}.{{story_num+1}}</check>
-    <action>If creating a new story candidate: VERIFY planning in {{epics_file}}. Confirm that epic {{epic_num}} explicitly enumerates a next story matching {{story_num+1}} (or an equivalent next planned story entry). If epics.md is missing or does not enumerate another story for this epic, HALT with message:</action>
-    <action>"No planned next story found in epics.md for epic {{epic_num}}. Please load either PM (Product Manager) agent at {project-root}/bmad/bmm/agents/pm.md or SM (Scrum Master) agent at {project-root}/bmad/bmm/agents/sm.md and run `*correct-course` to add/modify epic stories, then rerun create-story."</action>
-    <check>If verification passes → Set {{story_num}} = {{story_num}} + 1</check>
-    <ask optional="true" if="{{non_interactive}} == false">If starting a new epic and {{non_interactive}} == false, ASK for {{epic_num}} and reset {{story_num}} to 1. In {{non_interactive}} == true, do NOT auto-advance epic; stay within current epic and continue incrementing story_num.</ask>
+    <action>Verify story is enumerated in {{epics_file}}. If not found, HALT with message:</action>
+    <action>"Story {{result_story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story."</action>
+
+    <action>Check if story file already exists at expected path in {{story_dir}}</action>
+    <check if="story file exists">
+      <output>ℹ️ Story file already exists: {{story_file_path}}
+
+Will update existing story file rather than creating new one.
+      </output>
+      <action>Set update_mode = true</action>
+    </check>
   </step>
 
   <step n="4" goal="Extract requirements and derive story statement">
     <action>From tech_spec_file (preferred) or epics_file: extract epic {{epic_num}} title/summary, acceptance criteria for the next story, and any component references. If not present, fall back to PRD sections mapping to this epic/story.</action>
-    <action>From solution-architecture and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
+    <action>From architecture and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
     <action>Derive a clear user story statement (role, action, benefit) grounded strictly in the above sources. If ambiguous and {{non_interactive}} == false → ASK user to clarify. If {{non_interactive}} == true → generate the best grounded statement WITHOUT inventing domain facts.</action>
     <template-output file="{default_output_file}">requirements_context_summary</template-output>
   </step>
@@ -100,58 +100,37 @@
   <step n="8" goal="Validate, save, and optionally generate context">
     <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
     <action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
+
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: update_story_status</param>
+      <param>story_key: {{result_story_key}}</param>
+      <param>new_status: drafted</param>
+      <param>validate: true</param>
+    </invoke-workflow>
+
+    <check if="{{result_success}} == false">
+      <output>⚠️ Could not update story status: {{result_error}}
+
+Story file was created successfully, but sprint-status.yaml was not updated.
+You may need to run sprint-planning to refresh tracking.
+      </output>
+    </check>
+
     <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>
-
-  <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}!**
+    <output>**✅ Story Created Successfully, {user_name}!**
 
 **Story Details:**
 - Story ID: {{story_id}}
+- Story Key: {{result_story_key}}
 - File: {{story_file}}
-- Status: Draft (needs review)
-
-**Status file updated:**
-- Current step: create-story (Story {{story_id}}) ✓
-- Progress: {{new_progress_percentage}}%
+- Status: {{result_new_status}} (was {{result_old_status}})
 
 **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
-
-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>
+    </output>
   </step>
 
 </workflow>

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
@@ -22,7 +20,7 @@ variables:
   story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
   epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
   prd_file: "{output_folder}/PRD.md" # Fallback for requirements
-  solution-architecture_file: "{output_folder}/architecture.md" # Optional architecture context
+  architecture_file: "{output_folder}/architecture.md" # Optional architecture context
   tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
   tech_spec_search_dir: "{project-root}/docs"
   tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
@@ -44,6 +42,6 @@ default_output_file: "{story_dir}/story-{{epic_num}}.{{story_num}}.md"
 recommended_inputs:
   - epics: "Epic breakdown (epics.md)"
   - prd: "PRD document"
-  - solution-architecture: "Solution Architecture (optional)"
+  - architecture: "Architecture (optional)"
 
 web_bundle: false

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

@@ -15,32 +15,38 @@
 
 <workflow>
 
-  <step n="1" goal="Load story from status file IN PROGRESS section">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-      <param>mode: data</param>
-      <param>data_request: next_story</param>
+  <step n="1" goal="Locate and load story from sprint status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file</action>
+      <action>Extract story_key from filename or metadata</action>
+      <goto>task_check</goto>
+    </check>
+
+    <action>Query sprint-status for ready stories:</action>
+
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: get_next_story</param>
+      <param>filter_status: ready-for-dev</param>
     </invoke-workflow>
 
-    <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
+    <check if="{{result_found}} == false">
+      <output>📋 No ready-for-dev stories found in sprint-status.yaml
 
-      <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>
+**Options:**
+1. Run `story-ready` to mark drafted stories as ready
+2. Run `create-story` if no stories are drafted yet
+3. Check sprint-status.yaml to see current story states
+      </output>
+      <action>HALT</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>Use {{result_story_key}} to find story file in {{story_dir}}</action>
+    <action>Read COMPLETE story file from discovered path</action>
+    <action>Store {{result_story_key}} for later status updates</action>
+
+    <anchor id="task_check" />
 
-    <action>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>
     <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
 
@@ -49,6 +55,34 @@
     <check>If task requirements ambiguous → ASK user to clarify or HALT</check>
   </step>
 
+  <step n="1.5" goal="Mark story in-progress in sprint status">
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: get_story_status</param>
+      <param>story_key: {{result_story_key}}</param>
+    </invoke-workflow>
+
+    <check if="{{result_status}} == 'ready-for-dev'">
+      <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+        <param>action: update_story_status</param>
+        <param>story_key: {{result_story_key}}</param>
+        <param>new_status: in-progress</param>
+        <param>validate: true</param>
+      </invoke-workflow>
+
+      <check if="{{result_success}} == true">
+        <output>🚀 Starting work on story {{result_story_key}}
+Status updated: {{result_old_status}} → {{result_new_status}}
+        </output>
+      </check>
+    </check>
+
+    <check if="{{result_status}} == 'in-progress'">
+      <output>⏯️ Resuming work on story {{result_story_key}}
+Story is already marked in-progress
+      </output>
+    </check>
+  </step>
+
   <step n="2" goal="Plan and implement task">
     <action>Review acceptance criteria and dev notes for the selected task</action>
     <action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
@@ -95,6 +129,21 @@
     <action>Confirm File List includes every changed file</action>
     <action>Execute story definition-of-done checklist, if the story includes one</action>
     <action>Update the story Status to: Ready for Review</action>
+
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: update_story_status</param>
+      <param>story_key: {{result_story_key}}</param>
+      <param>new_status: review</param>
+      <param>validate: true</param>
+    </invoke-workflow>
+
+    <check if="{{result_success}} == false">
+      <output>⚠️ Story file updated, but sprint-status update failed: {{result_error}}
+
+Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync.
+      </output>
+    </check>
+
     <check>If any task is incomplete → Return to step 1 to complete remaining work (Do NOT finish with partial progress)</check>
     <check>If regression failures exist → STOP and resolve before completing</check>
     <check>If File List is incomplete → Update it before completing</check>
@@ -104,58 +153,21 @@
     <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>
-
-  <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}!**
+    <output>**✅ Story Implementation Complete, {user_name}!**
 
 **Story Details:**
 - Story ID: {{current_story_id}}
+- Story Key: {{result_story_key}}
 - Title: {{current_story_title}}
 - File: {{story_path}}
-- Status: Ready for Review
-
-**Status file updated:**
-- Current step: dev-story (Story {{current_story_id}}) ✓
-- Progress: {{new_progress_percentage}}%
+- Status: {{result_new_status}} (was {{result_old_status}})
 
 **Next Steps:**
 1. Review the implemented story and test the changes
 2. Verify all acceptance criteria are met
-3. When satisfied, run `story-approved` to mark story complete and advance the queue
-
-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>
+3. Run `review-story` workflow for senior developer review
+4. When review passes, run `story-done` to mark complete
+    </output>
   </step>
 
 </workflow>

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

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

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Solution Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
+Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
 
 ## Key Features
 
@@ -35,7 +35,7 @@ workflow tech-spec --input PRD.md --input architecture.md --input front-end-spec
 
 - **output_folder**: Location for generated technical specification
 - **epic_id**: Used in output filename (extracted from PRD or prompted)
-- **recommended_inputs**: PRD, solution-architecture, front-end spec, brownfield notes
+- **recommended_inputs**: PRD, architecture, front-end spec, brownfield notes
 
 ## Workflow Structure
 
@@ -104,7 +104,7 @@ tech-spec/
 ### Output Structure
 
 1. **Overview and Scope** - Project context and boundaries
-2. **System Architecture Alignment** - Connection to solution-architecture
+2. **System Architecture Alignment** - Connection to architecture
 3. **Detailed Design** - Services, data models, APIs, and workflows
 4. **Non-Functional Requirements** - Performance, security, reliability, observability
 5. **Dependencies and Integrations** - External systems and technical dependencies
@@ -116,7 +116,7 @@ tech-spec/
 ## Requirements
 
 - **PRD Document**: Product Requirements Document with clear acceptance criteria
-- **Architecture Document**: solution-architecture or technical design
+- **Architecture Document**: architecture or technical design
 - **Repository Access**: For dependency analysis and framework detection
 - **Epic Context**: Clear epic identification and scope definition
 

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

@@ -5,73 +5,41 @@
 <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">
-    <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, solution-architecture usually generates tech specs automatically.
-
-Options:
-1. Continue anyway (manual tech spec generation)
-2. Exit (check if solution-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 solution-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">
+  <step n="1" 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 (or ASK if not present).</action>
+    <action>Extract {{epic_title}} and {{epic_id}} from PRD.</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="1.5" goal="Validate epic in sprint status">
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: get_epic_status</param>
+      <param>epic_id: {{epic_id}}</param>
+    </invoke-workflow>
+
+    <check if="{{result_found}} == false">
+      <output>⚠️ Epic {{epic_id}} not found in sprint-status.yaml
+
+This epic hasn't been registered in the sprint plan yet.
+Run sprint-planning workflow to initialize epic tracking.
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <check if="{{result_status}} == 'contexted'">
+      <output>ℹ️ Epic {{epic_id}} already marked as contexted
+
+Continuing to regenerate tech spec...
+      </output>
+    </check>
+  </step>
+
+  <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 +48,8 @@ What would you like to do?</ask>
     </template-output>
   </step>
 
-  <step n="4" goal="Detailed design">
-    <action>Derive concrete implementation specifics from Architecture and PRD (NO invention).</action>
+  <step n="3" goal="Detailed design">
+    <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 +58,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 +67,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 +82,41 @@ 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>
 
-  <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>
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: update_epic_status</param>
+      <param>epic_id: {{epic_id}}</param>
+      <param>new_status: contexted</param>
+    </invoke-workflow>
 
-    <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="{{result_success}} == false">
+      <output>⚠️ Could not update epic status: {{result_error}}</output>
+    </check>
 
-      <check if="success == true">
-        <output>✅ Status updated for Epic {{epic_id}} tech-spec</output>
-      </check>
-
-      <output>**✅ Tech Spec Generated Successfully, {user_name}!**
+    <output>**✅ Tech Spec Generated Successfully, {user_name}!**
 
 **Epic Details:**
 - Epic ID: {{epic_id}}
 - Epic Title: {{epic_title}}
 - Tech Spec File: {{default_output_file}}
+- Epic Status: {{result_new_status}} (was {{result_old_status}})
 
-**Status file updated:**
-- 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
+**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed.
 
 **Next Steps:**
 1. If more epics need tech specs: Run tech-spec again with different epic_id
 2. If all tech specs complete: Proceed to Phase 4 implementation
-3. Check status anytime with: `workflow-status`
-      </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>
+   - Load SM agent and run `create-story` to begin implementing stories
+    </output>
   </step>
 
 </workflow>

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
-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"
+web_bundle: false

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

@@ -20,27 +20,54 @@ FACILITATION NOTES:
 
 <workflow>
 
-<step n="1" goal="Check workflow 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="Epic Context Discovery">
+<step n="1" 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>
 <action>If auto-detection fails or user indicates different epic, ask them to share which epic they just completed</action>
 
+<action>Verify epic completion status in sprint-status:</action>
+
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+  <param>action: check_epic_complete</param>
+  <param>epic_id: {{epic_number}}</param>
+</invoke-workflow>
+
+<check if="{{result_complete}} == false">
+  <output>⚠️ Epic {{epic_number}} is not yet complete for retrospective
+
+**Epic Status:**
+
+- Total Stories: {{result_total_stories}}
+- Completed (Done): {{result_done_stories}}
+- Pending: {{result_total_stories - result_done_stories}}
+
+**Pending Stories:**
+{{result_pending_stories}}
+
+**Options:**
+
+1. Complete remaining stories before running retrospective
+2. Continue with partial retrospective (not recommended)
+3. Run sprint-planning to refresh story tracking
+   </output>
+
+<ask if="{{non_interactive}} == false">Epic is incomplete. Continue anyway? (yes/no)</ask>
+
+  <check if="user says no">
+    <action>HALT</action>
+  </check>
+
+<action if="user says yes">Set {{partial_retrospective}} = true</action>
+</check>
+
+<check if="{{result_complete}} == true">
+  <output>✅ Epic {{epic_number}} is complete - all {{result_done_stories}} stories done!
+
+Ready to proceed with retrospective.
+</output>
+</check>
+
 <action>Load the completed epic from: {output_folder}/prd/epic-{{epic_number}}.md</action>
 <action>Extract epic details:
 
@@ -376,68 +403,50 @@ 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>
 
-<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>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+  <param>action: complete_retrospective</param>
+  <param>epic_id: {{completed_number}}</param>
+</invoke-workflow>
 
-<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="{{result_success}} == true">
+  <output>✅ Retrospective marked as completed in sprint-status.yaml
 
-  <check if="success == true">
-    <output>✅ Status updated: Retrospective complete for Epic {{completed_number}}</output>
-  </check>
+Retrospective key: {{result_retro_key}}
+Status: {{result_old_status}} → {{result_new_status}}
+</output>
 </check>
 
-<output>**✅ Retrospective Complete**
+<check if="{{result_success}} == false">
+  <output>⚠️ Could not update retrospective status: {{result_error}}
+
+Retrospective document was saved, but sprint-status.yaml may need manual update.
+</output>
+</check>
+
+<action>Confirm all action items have been captured</action>
+<action>Remind user to schedule prep sprint if needed</action>
+<output>**✅ Retrospective Complete, {user_name}!**
 
 **Epic Review:**
 
 - Epic {{completed_number}}: {{epic_title}} reviewed
+- Retrospective Status: {{result_new_status}}
+- 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>
+   - Load PM agent and run `epic-tech-context` for next epic
+   - Or continue with existing contexted epics
+     </output>
+     </step>
 
 </workflow>
 

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"

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

@@ -14,27 +14,50 @@
 
 <workflow>
 
-  <step n="1" goal="Check workflow 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>
+  <step n="1" goal="Locate story and verify review status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE file and parse sections</action>
+      <action>Extract story_key from filename or story metadata</action>
+      <goto>verify_status</goto>
     </check>
 
-    <action>Store {{status_file_path}} for later updates (if exists)</action>
-  </step>
+    <action>Query sprint-status for review stories:</action>
 
-  <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>
-    <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>
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: list_stories</param>
+      <param>filter_status: review</param>
+      <param>limit: 10</param>
+    </invoke-workflow>
+
+    <check if="{{result_count}} == 0">
+      <output>📋 No stories in review status found
+
+**Options:**
+1. Run `dev-story` to implement and mark stories ready for review
+2. Check sprint-status.yaml for current story states
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Display available review stories:
+
+**Stories Ready for Review ({{result_count}} found):**
+
+{{result_story_list}}
+
+    </action>
+
+    <ask if="{{non_interactive}} == false">Select story to review (enter story key or number):</ask>
+    <action if="{{non_interactive}} == true">Auto-select first story from result_stories</action>
+
+    <action>Resolve selected story_key and find file path in {{story_dir}}</action>
+    <action>Resolve {{story_path}} and read the COMPLETE file</action>
+
+    <anchor id="verify_status" />
+
+    <action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available</action>
+    <action>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>
@@ -95,6 +118,32 @@ Running in standalone mode - no progress tracking.</output>
     <action>Save the story file.</action>
   </step>
 
+  <step n="7.5" goal="Update sprint-status based on review outcome">
+    <action>Determine target status based on review outcome:
+      - If {{outcome}} == "Approve" → target_status = "done"
+      - If {{outcome}} == "Changes Requested" → target_status = "in-progress"
+      - If {{outcome}} == "Blocked" → target_status = "review" (stay in review)
+    </action>
+
+    <invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+      <param>action: update_story_status</param>
+      <param>story_key: {{story_key}}</param>
+      <param>new_status: {{target_status}}</param>
+      <param>validate: true</param>
+    </invoke-workflow>
+
+    <check if="{{result_success}} == true">
+      <output>✅ Sprint status updated: {{result_old_status}} → {{result_new_status}}</output>
+    </check>
+
+    <check if="{{result_success}} == false">
+      <output>⚠️ Could not update sprint-status: {{result_error}}
+
+Review was saved to story file, but sprint-status.yaml may be out of sync.
+      </output>
+    </check>
+  </step>
+
   <step n="8" goal="Persist action items to tasks/backlog/epic">
     <action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
     <action if="{{persist_action_items}} == true and 'story_tasks' in {{persist_targets}}">
@@ -115,131 +164,21 @@ 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">
-    <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}!**
+    <output>**✅ Story Review Complete, {user_name}!**
 
 **Story Details:**
 - Story: {{epic_num}}.{{story_num}}
+- Story Key: {{story_key}}
 - Review Outcome: {{outcome}}
+- Sprint Status: {{result_new_status}}
 - 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-approved` to mark story complete
-
-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>
+2. If approved: Story is marked done, continue with next story
+3. If changes requested: Address action items and re-run `dev-story`
+4. If blocked: Resolve blockers before proceeding
+    </output>
   </step>
 
 </workflow>

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

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

@@ -0,0 +1,156 @@
+# Sprint Planning Workflow
+
+## Overview
+
+The sprint-planning workflow generates and manages the sprint status tracking file that serves as the single source of truth for Phase 4 implementation. It extracts all epics and stories from epic files and tracks their progress through the development lifecycle.
+
+In Agile terminology, this workflow facilitates **Sprint Planning** or **Sprint 0 Kickoff** - the transition from planning/architecture into actual development execution.
+
+## Purpose
+
+This workflow creates a `sprint-status.yaml` file that:
+
+- Lists all epics, stories, and retrospectives in order
+- Tracks the current status of each item
+- Provides a clear view of what needs to be worked on next
+- Ensures only one story is in progress at a time
+- Maintains the development flow from backlog to done
+
+## When to Use
+
+Run this workflow:
+
+1. **Initially** - After Phase 3 (solutioning) is complete and epics are finalized
+2. **After epic context creation** - To update epic status to 'contexted'
+3. **Periodically** - To auto-detect newly created story files
+4. **For status checks** - To see overall project progress
+
+## Status State Machine
+
+### Epic Flow
+
+```
+backlog → contexted
+```
+
+### Story Flow
+
+```
+backlog → drafted → ready-for-dev → in-progress → review → done
+```
+
+### Retrospective Flow
+
+```
+optional ↔ completed
+```
+
+## Key Guidelines
+
+1. **Epic Context Recommended**: Epics should be `contexted` before their stories can be `drafted`
+2. **Flexible Parallelism**: Multiple stories can be `in-progress` based on team capacity
+3. **Sequential Default**: Stories within an epic are typically worked in order, but parallel work is supported
+4. **Review Flow**: Stories should go through `review` before `done`
+5. **Learning Transfer**: SM typically drafts next story after previous is `done`, incorporating learnings
+
+## File Locations
+
+### Input Files
+
+- **Epic Files**: `{output_folder}/epic*.md` or `{output_folder}/epics.md`
+- **Epic Context**: `{output_folder}/epic-{n}-context.md`
+- **Story Files**: `{story_dir}/{epic}-{story}-{title}.md`
+  - Example: `stories/1-1-user-authentication.md`
+- **Story Context**: `{story_dir}/{epic}-{story}-{title}-context.md`
+  - Example: `stories/1-1-user-authentication-context.md`
+
+### Output File
+
+- **Status File**: `{output_folder}/sprint-status.yaml`
+
+## Usage by Agents
+
+### SM (Scrum Master) Agent
+
+```yaml
+Tasks:
+  - Check sprint-status.yaml for stories in 'done' status
+  - Identify next 'backlog' story to draft
+  - Run create-story workflow
+  - Update status to 'drafted'
+  - Create story context
+  - Update status to 'ready-for-dev'
+```
+
+### Developer Agent
+
+```yaml
+Tasks:
+  - Find stories with 'ready-for-dev' status
+  - Update to 'in-progress' when starting
+  - Implement the story
+  - Update to 'review' when complete
+  - Address review feedback
+  - Update to 'done' after review
+```
+
+### Test Architect
+
+```yaml
+Tasks:
+  - Monitor stories entering 'review'
+  - Track epic progress
+  - Identify when retrospectives are needed
+```
+
+## Example Output
+
+```yaml
+# Sprint Status
+# Generated: 2025-01-20
+# Project: MyPlantFamily
+
+development_status:
+  epic-1: contexted
+  1-1-project-foundation: done
+  1-2-app-shell: done
+  1-3-user-authentication: in-progress
+  1-4-plant-data-model: ready-for-dev
+  1-5-add-plant-manual: drafted
+  1-6-photo-identification: backlog
+  epic-1-retrospective: optional
+
+  epic-2: contexted
+  2-1-personality-system: in-progress
+  2-2-chat-interface: drafted
+  2-3-llm-integration: backlog
+  2-4-reminder-system: backlog
+  epic-2-retrospective: optional
+```
+
+## Integration with BMM Workflow
+
+This workflow is part of Phase 4 (Implementation) and integrates with:
+
+1. **epic-tech-context** - Creates technical context for epics
+2. **create-story** - Drafts individual story files
+3. **story-context** - Adds implementation context to stories
+4. **dev-story** - Developer implements the story
+5. **review-story** - SM reviews implementation
+6. **retrospective** - Optional epic retrospective
+
+## Benefits
+
+- **Clear Visibility**: Everyone knows what's being worked on
+- **Flexible Capacity**: Supports both sequential and parallel work patterns
+- **Learning Transfer**: SM can incorporate learnings when drafting next story
+- **Progress Tracking**: Easy to see overall project status
+- **Automation Friendly**: Simple YAML format for agent updates
+
+## Tips
+
+1. **Initial Generation**: Run immediately after epics are finalized
+2. **Regular Updates**: Agents should update status as they work
+3. **Manual Override**: You can manually edit the file if needed
+4. **Backup First**: The workflow backs up existing status before regenerating
+5. **Validation**: The workflow validates legal status transitions

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

@@ -0,0 +1,33 @@
+# Sprint Planning Validation Checklist
+
+## Core Validation
+
+### Complete Coverage Check
+
+- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every story found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml that don't exist in epic files
+
+### Parsing Verification
+
+Compare epic files against generated sprint-status.yaml:
+
+```
+Epic Files Contains:                Sprint Status Contains:
+✓ Epic 1                            ✓ epic-1: [status]
+  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth: [status]
+  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt: [status]
+  ✓ Story 1.3: Plant Naming           ✓ 1-3-plant-naming: [status]
+                                      ✓ epic-1-retrospective: [status]
+✓ Epic 2                            ✓ epic-2: [status]
+  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model: [status]
+  ✓ Story 2.2: Chat Interface         ✓ 2-2-chat-interface: [status]
+                                      ✓ epic-2-retrospective: [status]
+```
+
+### Final Check
+
+- [ ] Total count of epics matches
+- [ ] Total count of stories matches
+- [ ] All items are in the expected order (epic, stories, retrospective)

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

@@ -0,0 +1,221 @@
+# Sprint Planning - Sprint Status Generator
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml</critical>
+
+<workflow>
+
+<step n="1" goal="Parse epic files and extract all work items">
+<action>Communicate in {communication_language} with {user_name}</action>
+<action>Look for all files matching `{epics_pattern}` in {epics_location}</action>
+<action>Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files</action>
+
+<action>For each epic file found, extract:</action>
+
+- Epic numbers from headers like `## Epic 1:` or `## Epic 2:`
+- Story IDs and titles from patterns like `### Story 1.1: User Authentication`
+- Convert story format from `Epic.Story: Title` to kebab-case key: `epic-story-title`
+
+**Story ID Conversion Rules:**
+
+- Original: `### Story 1.1: User Authentication`
+- Replace period with dash: `1-1`
+- Convert title to kebab-case: `user-authentication`
+- Final key: `1-1-user-authentication`
+
+<action>Build complete inventory of all epics and stories from all epic files</action>
+</step>
+
+<step n="2" goal="Build sprint status structure">
+<action>For each epic found, create entries in this order:</action>
+
+1. **Epic entry** - Key: `epic-{num}`, Default status: `backlog`
+2. **Story entries** - Key: `{epic}-{story}-{title}`, Default status: `backlog`
+3. **Retrospective entry** - Key: `epic-{num}-retrospective`, Default status: `optional`
+
+**Example structure:**
+
+```yaml
+development_status:
+  epic-1: backlog
+  1-1-user-authentication: backlog
+  1-2-account-management: backlog
+  epic-1-retrospective: optional
+```
+
+</step>
+
+<step n="3" goal="Apply intelligent status detection">
+<action>For each epic, check if tech context file exists:</action>
+
+- Check: `{output_folder}/epic-{num}-context.md`
+- If exists → set epic status to `contexted`
+- Else → keep as `backlog`
+
+<action>For each story, detect current status by checking files:</action>
+
+**Story file detection:**
+
+- Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`)
+- If exists → upgrade status to at least `drafted`
+
+**Story context detection:**
+
+- Check: `{story_location_absolute}/{story-key}-context.md` (e.g., `stories/1-1-user-authentication-context.md`)
+- If exists → upgrade status to at least `ready-for-dev`
+
+**Preservation rule:**
+
+- If existing `{status_file}` exists and has more advanced status, preserve it
+- Never downgrade status (e.g., don't change `done` to `drafted`)
+
+**Status Flow Reference:**
+
+- Epic: `backlog` → `contexted`
+- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Retrospective: `optional` ↔ `completed`
+  </step>
+
+<step n="4" goal="Generate sprint status file">
+<action>Create or update {status_file} with:</action>
+
+**File Structure:**
+
+```yaml
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# 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: { date }
+project: { project_name }
+project_key: { project_key }
+tracking_system: { tracking_system }
+story_location: { story_location }
+
+development_status:
+  # All epics, stories, and retrospectives in order
+```
+
+<action>Write the complete sprint status YAML to {status_file}</action>
+<action>CRITICAL: For story_location field, write the variable value EXACTLY as defined in workflow.yaml: "{project-root}/docs/stories"</action>
+<action>CRITICAL: Do NOT resolve {project-root} to an absolute path - keep it as the literal string "{project-root}/docs/stories"</action>
+<action>CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing</action>
+<action>Ensure all items are ordered: epic, its stories, its retrospective, next epic...</action>
+</step>
+
+<step n="5" goal="Validate and report">
+<action>Perform validation checks:</action>
+
+- [ ] Every epic in epic files appears in sprint-status.yaml
+- [ ] Every story in epic files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml that don't exist in epic files
+- [ ] All status values are legal (match state machine definitions)
+- [ ] File is valid YAML syntax
+
+<action>Count totals:</action>
+
+- Total epics: {{epic_count}}
+- Total stories: {{story_count}}
+- Epics contexted: {{contexted_count}}
+- Stories in progress: {{in_progress_count}}
+- Stories done: {{done_count}}
+
+<action>Display completion summary to {user_name} in {communication_language}:</action>
+
+**Sprint Status Generated Successfully**
+
+- **File Location:** {status_file}
+- **Total Epics:** {{epic_count}}
+- **Total Stories:** {{story_count}}
+- **Contexted Epics:** {{contexted_count}}
+- **Stories In Progress:** {{in_progress_count}}
+- **Stories Completed:** {{done_count}}
+
+**Next Steps:**
+
+1. Review the generated sprint-status.yaml
+2. Use this file to track development progress
+3. Agents will update statuses as they work
+4. Re-run this workflow to refresh auto-detected statuses
+
+</step>
+
+</workflow>
+
+## Additional Documentation
+
+### Status State Machine
+
+**Epic Status Flow:**
+
+```
+backlog → contexted
+```
+
+- **backlog**: Epic exists in epic file but tech context not created
+- **contexted**: Epic tech context has been generated (prerequisite for story drafting)
+
+**Story Status Flow:**
+
+```
+backlog → drafted → ready-for-dev → in-progress → review → done
+```
+
+- **backlog**: Story only exists in epic file
+- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
+- **ready-for-dev**: Draft approved + story context created
+- **in-progress**: Developer actively working
+- **review**: Under SM review (via review-story workflow)
+- **done**: Completed
+
+**Retrospective Status:**
+
+```
+optional ↔ completed
+```
+
+- **optional**: Can be done but not required
+- **completed**: Retrospective has been completed
+
+### Guidelines
+
+1. **Epic Context Recommended**: Epics should be `contexted` before stories can be `drafted`
+2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported
+3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
+4. **Review Before Done**: Stories should pass through `review` before `done`
+5. **Learning Transfer**: SM typically drafts next story after previous one is `done` to incorporate learnings
+
+### Error Handling
+
+- If epic file can't be parsed, report specific file and continue with others
+- If existing status file is malformed, backup and regenerate
+- Log warnings for duplicate story IDs across epics
+- Validate status transitions are legal (can't go from `backlog` to `done`)

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

@@ -0,0 +1,56 @@
+# Sprint Status Template
+# This is an EXAMPLE showing the expected format
+# The actual file will be generated with all epics/stories from your epic files
+
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# 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'
+
+# EXAMPLE STRUCTURE (your actual epics/stories will replace these):
+
+generated: 05-06-2-2025 21:30
+project: My Awesome Project
+project_key: jira-1234
+tracking_system: file-system
+story_location: "{project-root}/docs/stories"
+
+development_status:
+  epic-1: contexted
+  1-1-user-authentication: done
+  1-2-account-management: drafted
+  1-3-plant-data-model: backlog
+  1-4-add-plant-manual: backlog
+  epic-1-retrospective: optional
+
+  epic-2: backlog
+  2-1-personality-system: backlog
+  2-2-chat-interface: backlog
+  2-3-llm-integration: backlog
+  epic-2-retrospective: optional

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

@@ -0,0 +1,39 @@
+name: sprint-planning
+description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/sprint-planning"
+instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/sprint-status-template.yaml"
+validation: "{installed_path}/checklist.md"
+
+# Variables and inputs
+variables:
+  # Project identification
+  project_name: "{config_source}:project_name"
+  project_key: "{config_source}:project_name" # Future: Jira project key, Linear workspace ID, etc.
+
+  # Tracking system configuration
+  tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
+  story_location: "{project-root}/docs/stories" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
+  story_location_absolute: "{config_source}:dev_story_location" # Absolute path for file operations
+
+  # Source files (file-system only)
+  epics_location: "{output_folder}" # Directory containing epic*.md files
+  epics_pattern: "epic*.md" # Pattern to find epic files
+
+  # Output configuration
+  status_file: "{output_folder}/sprint-status.yaml"
+
+# Output configuration
+default_output_file: "{status_file}"
+
+web_bundle: false

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

@@ -1,161 +0,0 @@
-# Story Approved Workflow Instructions (DEV Agent)
-
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
-<critical>Generate all documents in {document_output_language}</critical>
-
-<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, move story IN PROGRESS → DONE, move TODO → IN PROGRESS, move BACKLOG → TODO</critical>
-
-<step n="1" goal="Get story queue from status file">
-
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: data</param>
-  <param>data_request: all</param>
-</invoke-workflow>
-
-<check if="status_exists == false OR in_progress_story == ''">
-  <output>❌ No status file or no IN PROGRESS story found.
-
-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`
-- To: `Status: Done`
-
-<action>Add completion notes if Dev Agent Record section exists:</action>
-
-Find "## Dev Agent Record" section and add:
-
-```
-### Completion Notes
-**Completed:** {{date}}
-**Definition of Done:** All acceptance criteria met, code reviewed, tests passing, deployed
-```
-
-<action>Save the story file</action>
-
-</step>
-
-<step n="3" goal="Update status file - advance story queue">
-
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: update</param>
-  <param>action: complete_story</param>
-</invoke-workflow>
-
-<check if="success == false">
-  <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}}
-- **Title:** {{current_story_title}}
-- **File:** `{{current_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
-2. Close out the project
-3. Celebrate! 🎊
-   {{/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>
-
-</workflow>
-```

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">
-    <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">
+  <step n="1" goal="Locate story and initialize output">
     <action>If {{story_path}} provided and valid → use it; else auto-discover from {{story_dir}}.</action>
     <action>Auto-discovery: read {{story_dir}} (dev_story_location). If invalid/missing or contains no .md files, ASK for a story file path or directory to scan.</action>
     <action>If a directory is provided, list markdown files named "story-*.md" recursively; sort by last modified time; display top {{story_selection_limit}} with index, filename, path, modified time.</action>
@@ -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>
-
-  <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}!**
+    <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
-
-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>
+    </output>
   </step>
 
 </workflow>

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"

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

@@ -0,0 +1,117 @@
+# Story Approved Workflow Instructions (DEV Agent)
+
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<workflow>
+
+<critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
+<critical>Workflow: Update story file status to Done</critical>
+
+<step n="1" goal="Find reviewed story and mark done">
+
+<action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_done</action>
+
+<action>Otherwise query sprint-status for reviewed stories:</action>
+
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+  <param>action: list_stories</param>
+  <param>filter_status: review</param>
+  <param>limit: 10</param>
+</invoke-workflow>
+
+<check if="{{result_count}} == 0">
+  <output>📋 No stories in review status found
+
+All stories are either still in development or already done.
+
+**Options:**
+
+1. Run `dev-story` to implement stories
+2. Run `review-story` if stories need review first
+3. Check sprint-status.yaml for current story states
+   </output>
+   <action>HALT</action>
+   </check>
+
+<action>Display available reviewed stories:
+
+**Stories Ready to Mark Done ({{result_count}} found):**
+
+{{result_story_list}}
+
+</action>
+
+<ask>Select the story to mark as Done (enter story key or number):</ask>
+
+<action>Resolve selected story_key from user input</action>
+<action>Find matching story file in {{story_dir}} using story_key pattern</action>
+
+<anchor id="mark_done" />
+
+<action>Read the story file from resolved path</action>
+<action>Extract story_id and story_title from the file</action>
+
+<action>Find the "Status:" line (usually at the top)</action>
+<action>Update story file: Change Status to "Done"</action>
+
+<action>Add completion notes to Dev Agent Record section:</action>
+<action>Find "## Dev Agent Record" section and add:
+
+```
+### Completion Notes
+**Completed:** {{date}}
+**Definition of Done:** All acceptance criteria met, code reviewed, tests passing
+```
+
+</action>
+
+<action>Save the story file</action>
+
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+  <param>action: update_story_status</param>
+  <param>story_key: {{story_key}}</param>
+  <param>new_status: done</param>
+  <param>validate: true</param>
+</invoke-workflow>
+
+<check if="{{result_success}} == false">
+  <output>⚠️ Story file updated, but could not update sprint-status: {{result_error}}
+
+Story is marked Done in file, but sprint-status.yaml may be out of sync.
+</output>
+</check>
+
+</step>
+
+<step n="2" goal="Confirm completion to user">
+
+<output>**Story Approved and Marked Done, {user_name}!**
+
+✅ Story file updated: `{{story_file}}` → Status: Done
+✅ Sprint status updated: {{result_old_status}} → {{result_new_status}}
+
+**Completed Story:**
+
+- **ID:** {{story_id}}
+- **Key:** {{story_key}}
+- **Title:** {{story_title}}
+- **File:** `{{story_file}}`
+- **Completed:** {{date}}
+
+**Next Steps:**
+
+1. Continue with next story in your backlog
+   - Run `create-story` for next backlog story
+   - Or run `dev-story` if ready stories exist
+2. Check epic completion status
+   - Run `retrospective` workflow to check if epic is complete
+   - Epic retrospective will verify all stories are done
+     </output>
+
+</step>
+
+</workflow>
+```

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

@@ -1,5 +1,5 @@
-# Story Approved Workflow (DEV Agent)
-name: story-approved
+# Story Done Workflow (DEV Agent)
+name: story-done
 description: "Marks a story as done (DoD complete) and moves it from IN PROGRESS → DONE in the status file. Advances the story queue. Simple status-update workflow with no searching required."
 author: "BMad"
 
@@ -8,19 +8,16 @@ 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
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/story-approved"
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/story-done"
 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: ""

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

@@ -8,86 +8,85 @@
 <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, move story TODO → IN PROGRESS, move next story BACKLOG → TODO</critical>
+<critical>Simple workflow: Update story file status to Ready</critical>
 
-<step n="1" goal="Get TODO story from status file">
+<step n="1" goal="Find drafted story and mark as ready">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: data</param>
-  <param>data_request: next_story</param>
+<action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready</action>
+
+<action>Otherwise query sprint-status for drafted stories:</action>
+
+<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="status_exists == false OR todo_story_id == ''">
-  <output>❌ No status file or no TODO story found.
+<check if="{{result_count}} == 0">
+  <output>📋 No drafted stories found in sprint-status.yaml
 
-This workflow requires an active status file with a TODO story.
+All stories are either still in backlog or already marked ready/in-progress/done.
 
-Run `workflow-status` to check your project state.</output>
-<action>Exit workflow</action>
-</check>
+**Options:**
 
-<action>Use extracted story information:</action>
+1. Run `create-story` to draft more stories
+2. Run `sprint-planning` to refresh story tracking
+   </output>
+   <action>HALT</action>
+   </check>
 
-- {{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
+<action>Display available drafted stories:
 
-</step>
+**Drafted Stories Available ({{result_count}} found):**
 
-<step n="2" goal="Update the story file status">
+{{result_story_list}}
 
-<action>Read the story file: {story_dir}/{todo_story_file}</action>
+</action>
+
+<ask if="{{non_interactive}} == false">Select the drafted story to mark as Ready (enter story key or number):</ask>
+<action if="{{non_interactive}} == true">Auto-select first story from result_stories</action>
+
+<action>Resolve selected story_key from user input or auto-selection</action>
+<action>Find matching story file in {{story_dir}} using story_key pattern</action>
+
+<anchor id="mark_ready" />
+
+<action>Read the story file from resolved path</action>
+<action>Extract story_id and story_title from the file</action>
 
 <action>Find the "Status:" line (usually at the top)</action>
-
-<action>Update story file:</action>
-
-- Change: `Status: Draft`
-- To: `Status: Ready`
-
+<action>Update story file: Change Status to "Ready"</action>
 <action>Save the story file</action>
 
-</step>
-
-<step n="3" goal="Update status file - move story TODO → IN PROGRESS">
-
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: update</param>
-  <param>action: start_story</param>
+<invoke-workflow path="{project-root}/bmad/bmm/workflows/helpers/sprint-status">
+  <param>action: update_story_status</param>
+  <param>story_key: {{story_key}}</param>
+  <param>new_status: ready-for-dev</param>
+  <param>validate: true</param>
 </invoke-workflow>
 
-<check if="success == false">
-  <output>⚠️ Failed to update status: {{error}}</output>
-  <output>Story file was updated, but status file update failed.</output>
-</check>
+<check if="{{result_success}} == false">
+  <output>⚠️ Story file updated, but could not update sprint-status: {{result_error}}
 
-<check if="success == true">
-  <output>Status updated: Story {{in_progress_story}} ready for development.</output>
-  <check if="next_todo != ''">
-    <output>Next TODO: {{next_todo}}</output>
-  </check>
+You may need to run sprint-planning to refresh tracking.
+</output>
 </check>
 
 </step>
 
-<step n="4" goal="Confirm completion to user">
+<step n="2" goal="Confirm completion to user">
 
-<action>Display summary</action>
+<output>**Story Marked Ready for Development, {user_name}!**
 
-**Story Marked Ready for Development, {user_name}!**
+✅ Story file updated: `{{story_file}}` → Status: Ready
+✅ Sprint status updated: {{result_old_status}} → {{result_new_status}}
 
-✅ Story file updated: `{{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}}
+**Story Details:**
 
-**Current Story (IN PROGRESS):**
-
-- **ID:** {{todo_story_id}}
-- **Title:** {{todo_story_title}}
-- **File:** `{{todo_story_file}}`
+- **ID:** {{story_id}}
+- **Key:** {{story_key}}
+- **Title:** {{story_title}}
+- **File:** `{{story_file}}`
 - **Status:** Ready for development
 
 **Next Steps:**

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: ""

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

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_

src/modules/bmm/workflows/README.md

@@ -174,7 +174,7 @@ workflow-status determines routing:
     └─→ Level 3-4 → bmad pm prd
         └─→ Validates status file + level
         └─→ Generates PRD.md + epics.md
-        └─→ Then: Phase 3 (solution-architecture)
+        └─→ Then: Phase 3 (architecture)
         └─→ Then: Phase 4 (implementation)
 
     GAME PROJECTS:
@@ -250,7 +250,7 @@ BACKLOG → TODO → IN PROGRESS → DONE
   - Story status is "Ready" or "In Review"
 
 - **DONE**: Completed stories with dates and points
-  - Moved here by `story-approved` workflow after DoD complete
+  - Moved here by `story-done` workflow after DoD complete
   - Immutable record of completed work
 
 **Key Innovation**: Agents never search for "next story" - they always read the exact story from the status file.
@@ -294,7 +294,7 @@ Phase Transition (Phase 2 or 3 → Phase 4)
 ┌─────────────────────────────────────────────────┐
 │  User reviews implementation (DoD check)         │
 │  ↓                                               │
-│  DEV: story-approved (marks story done)          │
+│  DEV: story-done (marks story done)          │
 │  Actions: IN PROGRESS → DONE                     │
 │           TODO → IN PROGRESS (if exists)         │
 │           BACKLOG → TODO (if exists)             │
@@ -319,7 +319,7 @@ Phase Transition (Phase 2 or 3 → Phase 4)
 | **story-ready**    | SM     | Approve drafted story for development | TODO → IN PROGRESS    | Reads TODO section       |
 | **story-context**  | SM     | Generate expertise injection XML      | (No state change)     | Reads IN PROGRESS        |
 | **dev-story**      | DEV    | Implement story                       | (No state change)     | Reads IN PROGRESS        |
-| **story-approved** | DEV    | Mark story done after DoD complete    | IN PROGRESS → DONE    | Reads IN PROGRESS        |
+| **story-done**     | DEV    | Mark story done after DoD complete    | IN PROGRESS → DONE    | Reads IN PROGRESS        |
 | **review-story**   | SR/DEV | Quality validation (optional)         | (No state change)     | Manual story selection   |
 | **correct-course** | SM     | Handle issues/changes                 | (Adaptive)            | Manual story selection   |
 | **retrospective**  | SM     | Capture epic learnings                | (No state change)     | Manual or epic-triggered |
@@ -335,7 +335,7 @@ Status: Ready       (User approved via story-ready, ready for implementation)
   ↓
 Status: In Review   (Implementation complete, awaiting final approval)
   ↓
-Status: Done        (User approved via story-approved, DoD complete)
+Status: Done        (User approved via story-done, DoD complete)
 ```
 
 **Status File Position vs Story File Status:**
@@ -475,7 +475,7 @@ bmad architect tech-spec # Level 0-1 software projects
 bmad pm gdd             # Game projects
 
 # Phase 3: Solutioning (L3-4)
-bmad architect solution-architecture
+bmad architect architecture
 bmad architect tech-spec  # Per epic, JIT
 
 # Phase 4: Implementation
@@ -483,7 +483,7 @@ bmad sm create-story      # Draft story from TODO section
 bmad sm story-ready       # Approve story for development (after user review)
 bmad sm story-context     # Generate context XML (optional but recommended)
 bmad dev dev-story        # Implement story from IN PROGRESS section
-bmad dev story-approved   # Mark story done (after user confirms DoD)
+bmad dev story-done   # Mark story done (after user confirms DoD)
 bmad dev review-story     # Quality validation (optional)
 bmad sm correct-course    # If issues arise
 bmad sm retrospective     # After epic complete

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

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>

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

src/modules/bmm/workflows/testarch/atdd/README.md

@@ -664,7 +664,7 @@ npm run test:e2e -- user-authentication.spec.ts --debug
 2. Run failing tests to confirm RED phase: `npm run test:e2e`
 3. Begin implementation using checklist as guide
 4. Share progress in daily standup
-5. When all tests pass, run `bmad sm story-approved` to move story to DONE
+5. When all tests pass, run `bmad sm story-done` to move story to DONE
 
 ```
 

src/modules/bmm/workflows/testarch/atdd/atdd-checklist-template.md

@@ -296,7 +296,7 @@ test('should do something', async ({ {fixtureName} }) => {
 4. **Work one test at a time** (red → green for each)
 5. **Share progress** in daily standup
 6. **When all tests pass**, refactor code for quality
-7. **When refactoring complete**, run `bmad sm story-approved` to move story to DONE
+7. **When refactoring complete**, run `bmad sm story-done` to move story to DONE
 
 ---
 

src/modules/bmm/workflows/testarch/framework/README.md

@@ -141,7 +141,7 @@ Automatically consults TEA knowledge base:
 
 **Coordinates with:**
 
-- **solution-architecture** (Phase 3): Aligns test structure with system architecture
+- **architecture** (Phase 3): Aligns test structure with system architecture
 - **tech-spec**: Uses technical specifications to inform test configuration
 
 **Updates:**

src/modules/bmm/workflows/testarch/test-design/README.md

@@ -305,7 +305,7 @@ Automatically consults TEA knowledge base:
 **Before test-design:**
 
 - **plan-project** (Phase 2): Creates PRD and epics
-- **solution-architecture** (Phase 3): Defines technical approach
+- **architecture** (Phase 3): Defines technical approach
 - **tech-spec** (Phase 3): Implementation details
 
 **After test-design:**

src/modules/bmm/workflows/testarch/trace/README.md

@@ -786,7 +786,7 @@ Use for: Alpha/beta releases, internal tools, proof-of-concept
 - `bmad tea *automate` - Expand regression suite based on gaps
 - `bmad tea *nfr-assess` - Validate non-functional requirements (for gate)
 - `bmad tea *test-review` - Review test quality issues flagged by trace
-- `bmad sm story-approved` - Mark story as complete (triggers gate)
+- `bmad sm story-done` - Mark story as complete (triggers gate)
 
 ---
 

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

@@ -9,7 +9,7 @@
 <step n="1" goal="Scan for existing work">
 <action>Search {output_folder}/ for existing BMM artifacts:</action>
 - PRD files (*prd*.md)
-- Architecture docs (architecture*.md, solution-architecture*.md, architecture/*)
+- Architecture docs (architecture*.md, architecture*.md, architecture/*)
 - Briefs (*brief*.md)
 - Brainstorming docs (brainstorm*.md)
 - Research docs (*research*.md)

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>

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

@@ -44,6 +44,12 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
     workflows:
       - id: "create-story"
         required: true
@@ -58,10 +64,10 @@ phases:
         required: true
         agent: "dev"
         command: "dev-story"
-      - id: "story-approved"
+      - id: "story-done"
         required: true
         agent: "dev"
-        command: "story-approved"
+        command: "story-done"
 
 story_naming: "story-<short-title>.md"
 story_example: "story-fix-auth-bug.md"

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

@@ -48,6 +48,13 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
+    story_loop: "for_each_story"
     workflows:
       - id: "create-story"
         required: true
@@ -66,10 +73,10 @@ phases:
         optional: true
         agent: "dev"
         command: "review-story"
-      - id: "story-approved"
+      - id: "story-done"
         required: true
         agent: "dev"
-        command: "story-approved"
+        command: "story-done"
 
 story_naming: "story-<short-title>.md"
 story_example: "story-add-auth.md, story-update-dashboard.md"

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

@@ -62,6 +62,13 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
+    story_loop: "for_each_story"
     workflows:
       - id: "create-story"
         required: true
@@ -81,13 +88,13 @@ phases:
         agent: "dev"
         command: "dev-story"
       - id: "review-story"
-        recommended: true
+        optional: true
         agent: "dev"
         command: "review-story"
-      - id: "story-approved"
+      - id: "story-done"
         required: true
         agent: "dev"
-        command: "story-approved"
+        command: "story-done"
 
 story_naming: "story-<short-title>.md"
 story_example: "story-user-dashboard.md, story-api-integration.md"

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

@@ -77,59 +77,64 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
     epic_loop: "for_each_epic"
-    epic_workflows:
-      - id: "tech-spec"
-        required: true
-        agent: "architect"
-        command: "tech-spec"
-        note: "Must respect existing patterns"
-    story_loop: "for_each_story_in_epic"
-    story_workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-        note: "Heavy emphasis on existing code context"
-      - id: "validate-story-context"
-        required: true
-        agent: "sm"
-        command: "validate-story-context"
-        note: "Ensure no breaking changes"
-      - id: "story-ready"
-        recommended: true
-        agent: "sm"
-        command: "story-ready"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        required: true
-        agent: "dev"
-        command: "review-story"
-        note: "Check integration points"
-      - id: "correct-course"
-        conditional: "if_review_fails"
-        agent: "dev"
-        command: "correct-course"
-      - id: "story-approved"
-        required: true
-        agent: "dev"
-        command: "story-approved"
-    epic_completion:
-      - id: "integration-test"
-        required: true
-        agent: "dev"
-        command: "integration-test"
-      - id: "retrospective"
-        required: true
-        agent: "sm"
-        command: "retrospective"
+    epic_iteration:
+      setup_workflows:
+        - id: "tech-spec"
+          required: true
+          agent: "architect"
+          command: "tech-spec"
+          note: "Must respect existing patterns"
+
+      story_loop: "for_each_story_in_epic"
+      story_workflows:
+        - id: "create-story"
+          required: true
+          agent: "sm"
+          command: "create-story"
+        - id: "story-context"
+          required: true
+          agent: "sm"
+          command: "story-context"
+          note: "Heavy emphasis on existing code context"
+        - id: "validate-story-context"
+          optional: true
+          agent: "sm"
+          command: "validate-story-context"
+          note: "Ensure no breaking changes"
+        - id: "story-ready"
+          optional: true
+          agent: "sm"
+          command: "story-ready"
+        - id: "dev-story"
+          required: true
+          agent: "dev"
+          command: "dev-story"
+        - id: "review-story"
+          optional: true
+          agent: "dev"
+          command: "review-story"
+          note: "Check integration points"
+        - id: "story-done"
+          required: true
+          agent: "dev"
+          command: "story-done"
+
+      completion_workflows:
+        - id: "integration-test"
+          required: true
+          agent: "dev"
+          command: "integration-test"
+        - id: "retrospective"
+          required: true
+          agent: "sm"
+          command: "retrospective"
 
 story_naming: "story-<epic>.<story>.md"
 brownfield_note: "All changes must integrate seamlessly with existing system"

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

@@ -71,60 +71,65 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
     epic_loop: "for_each_epic"
-    epic_workflows:
-      - id: "tech-spec"
-        required: true
-        agent: "sm"
-        command: "tech-spec"
-        note: "JIT per epic - creates stories considering existing code"
-    story_loop: "for_each_story_in_epic"
-    story_workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-        note: "Extensive existing code context required"
-      - id: "validate-story-context"
-        required: true
-        agent: "sm"
-        command: "validate-story-context"
-      - id: "story-ready"
-        required: true
-        agent: "sm"
-        command: "story-ready"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        required: true
-        agent: "dev"
-        command: "review-story"
-        note: "Rigorous review for enterprise changes"
-      - id: "correct-course"
-        conditional: "if_review_fails"
-        agent: "dev"
-        command: "correct-course"
-      - id: "integration-test"
-        required: true
-        agent: "dev"
-        command: "integration-test"
-        note: "Test integration with existing systems"
-      - id: "story-approved"
-        required: true
-        agent: "dev"
-        command: "story-approved"
-    epic_completion:
-      - id: "retrospective"
-        required: true
-        agent: "sm"
-        command: "retrospective"
-        note: "Critical for enterprise-scale learning"
+    epic_iteration:
+      setup_workflows:
+        - id: "tech-spec"
+          required: true
+          agent: "sm"
+          command: "tech-spec"
+          note: "JIT per epic - creates stories considering existing code"
+
+      story_loop: "for_each_story_in_epic"
+      story_workflows:
+        - id: "create-story"
+          required: true
+          agent: "sm"
+          command: "create-story"
+        - id: "story-context"
+          required: true
+          agent: "sm"
+          command: "story-context"
+          note: "Extensive existing code context required"
+        - id: "validate-story-context"
+          optional: true
+          agent: "sm"
+          command: "validate-story-context"
+        - id: "story-ready"
+          optional: true
+          agent: "sm"
+          command: "story-ready"
+        - id: "dev-story"
+          required: true
+          agent: "dev"
+          command: "dev-story"
+        - id: "review-story"
+          optional: true
+          agent: "dev"
+          command: "review-story"
+          note: "Rigorous review for enterprise changes"
+        - id: "integration-test"
+          optional: true
+          agent: "dev"
+          command: "integration-test"
+          note: "Test integration with existing systems"
+        - id: "story-done"
+          required: true
+          agent: "dev"
+          command: "story-done"
+
+      completion_workflows:
+        - id: "retrospective"
+          required: true
+          agent: "sm"
+          command: "retrospective"
+          note: "Critical for enterprise-scale learning"
 
 story_naming: "story-<epic>.<story>.md"
 story_example: "story-1.1.md, story-2.3.md"

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

@@ -58,6 +58,12 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
     note: "Implementation varies by game complexity"
     level_based_implementation:
       level_0_1:
@@ -72,7 +78,7 @@ phases:
           - id: "dev-story"
             required: true
             agent: "dev"
-          - id: "story-approved"
+          - id: "story-done"
             required: true
             agent: "dev"
       level_2_4:
@@ -99,7 +105,7 @@ phases:
           - id: "review-story"
             recommended: true
             agent: "dev"
-          - id: "story-approved"
+          - id: "story-done"
             required: true
             agent: "dev"
         feature_completion:

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

@@ -37,6 +37,12 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
     workflows:
       - id: "create-story"
         required: true
@@ -50,10 +56,10 @@ phases:
         required: true
         agent: "dev"
         command: "dev-story"
-      - id: "story-approved"
+      - id: "story-done"
         required: true
         agent: "dev"
-        command: "story-approved"
+        command: "story-done"
 
 story_naming: "story-<short-title>.md"
 story_example: "story-fix-login.md"

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

@@ -41,7 +41,13 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    loop_type: "for_each_story"
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
+    story_loop: "for_each_story"
     workflows:
       - id: "create-story"
         required: true
@@ -63,10 +69,10 @@ phases:
         optional: true
         agent: "dev"
         command: "review-story"
-      - id: "story-approved"
+      - id: "story-done"
         required: true
         agent: "dev"
-        command: "story-approved"
+        command: "story-done"
 
 story_naming: "story-<title>-<n>.md"
 story_example: "story-oauth-integration-1.md"

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

@@ -62,7 +62,13 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
-    loop_type: "for_each_story"
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
+    story_loop: "for_each_story"
     workflows:
       - id: "create-story"
         required: true
@@ -88,10 +94,10 @@ phases:
         optional: true
         agent: "dev"
         command: "review-story"
-      - id: "story-approved"
+      - id: "story-done"
         required: true
         agent: "dev"
-        command: "story-approved"
+        command: "story-done"
     epic_completion:
       - id: "retrospective"
         optional: true

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

@@ -57,52 +57,57 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
     epic_loop: "for_each_epic"
-    epic_workflows:
-      - id: "tech-spec"
-        required: true
-        agent: "architect"
-        command: "tech-spec"
-        note: "JIT per epic - creates stories for that epic"
-    story_loop: "for_each_story_in_epic"
-    story_workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-      - id: "validate-story-context"
-        recommended: true
-        agent: "sm"
-        command: "validate-story-context"
-      - id: "story-ready"
-        optional: true
-        agent: "sm"
-        command: "story-ready"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        recommended: true
-        agent: "dev"
-        command: "review-story"
-      - id: "correct-course"
-        conditional: "if_review_fails"
-        agent: "dev"
-        command: "correct-course"
-      - id: "story-approved"
-        required: true
-        agent: "dev"
-        command: "story-approved"
-    epic_completion:
-      - id: "retrospective"
-        recommended: true
-        agent: "sm"
-        command: "retrospective"
+    epic_iteration:
+      setup_workflows:
+        - id: "tech-spec"
+          required: true
+          agent: "architect"
+          command: "tech-spec"
+          note: "JIT per epic - creates stories for that epic"
+
+      story_loop: "for_each_story_in_epic"
+      story_workflows:
+        - id: "create-story"
+          required: true
+          agent: "sm"
+          command: "create-story"
+        - id: "story-context"
+          required: true
+          agent: "sm"
+          command: "story-context"
+        - id: "validate-story-context"
+          optional: true
+          agent: "sm"
+          command: "validate-story-context"
+        - id: "story-ready"
+          optional: true
+          agent: "sm"
+          command: "story-ready"
+        - id: "dev-story"
+          required: true
+          agent: "dev"
+          command: "dev-story"
+        - id: "review-story"
+          optional: true
+          agent: "dev"
+          command: "review-story"
+        - id: "story-done"
+          required: true
+          agent: "dev"
+          command: "story-done"
+
+      completion_workflows:
+        - id: "retrospective"
+          recommended: true
+          agent: "sm"
+          command: "retrospective"
 
 story_naming: "story-<epic>.<story>.md"
 story_example: "story-1.1.md, story-2.3.md"

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

@@ -59,53 +59,58 @@ phases:
   - phase: 4
     name: "Implementation"
     required: true
+    phase_initialization:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Initialize sprint tracking - run once when entering Phase 4"
     epic_loop: "for_each_epic"
-    epic_workflows:
-      - id: "tech-spec"
-        required: true
-        agent: "architect"
-        command: "tech-spec"
-        note: "JIT per epic - creates stories for that epic"
-    story_loop: "for_each_story_in_epic"
-    story_workflows:
-      - id: "create-story"
-        required: true
-        agent: "sm"
-        command: "create-story"
-      - id: "story-context"
-        required: true
-        agent: "sm"
-        command: "story-context"
-      - id: "validate-story-context"
-        required: true
-        agent: "sm"
-        command: "validate-story-context"
-      - id: "story-ready"
-        recommended: true
-        agent: "sm"
-        command: "story-ready"
-      - id: "dev-story"
-        required: true
-        agent: "dev"
-        command: "dev-story"
-      - id: "review-story"
-        required: true
-        agent: "dev"
-        command: "review-story"
-      - id: "correct-course"
-        conditional: "if_review_fails"
-        agent: "dev"
-        command: "correct-course"
-      - id: "story-approved"
-        required: true
-        agent: "dev"
-        command: "story-approved"
-    epic_completion:
-      - id: "retrospective"
-        required: true
-        agent: "sm"
-        command: "retrospective"
-        note: "Critical for enterprise-scale learning"
+    epic_iteration:
+      setup_workflows:
+        - id: "tech-spec"
+          required: true
+          agent: "architect"
+          command: "tech-spec"
+          note: "JIT per epic - creates stories for that epic"
+
+      story_loop: "for_each_story_in_epic"
+      story_workflows:
+        - id: "create-story"
+          required: true
+          agent: "sm"
+          command: "create-story"
+        - id: "story-context"
+          required: true
+          agent: "sm"
+          command: "story-context"
+        - id: "validate-story-context"
+          optional: true
+          agent: "sm"
+          command: "validate-story-context"
+        - id: "story-ready"
+          optional: true
+          agent: "sm"
+          command: "story-ready"
+        - id: "dev-story"
+          required: true
+          agent: "dev"
+          command: "dev-story"
+        - id: "review-story"
+          optional: true
+          agent: "dev"
+          command: "review-story"
+        - id: "story-done"
+          required: true
+          agent: "dev"
+          command: "story-done"
+
+      completion_workflows:
+        - id: "retrospective"
+          required: true
+          agent: "sm"
+          command: "retrospective"
+          note: "Critical for enterprise-scale learning"
 
 story_naming: "story-<epic>.<story>.md"
 story_example: "story-1.1.md, story-2.3.md"

src/modules/bmm/workflows/workflow-status/project-levels.yaml

@@ -31,7 +31,7 @@ levels:
     title: "Complex System"
     stories: "12-40 stories"
     description: "Subsystems, integrations, full architecture"
-    documentation: "PRD + solution architecture + JIT tech specs"
+    documentation: "PRD + architecture + JIT tech specs"
     architecture: true
 
   4:

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}}

v6-open-items.md

@@ -18,6 +18,7 @@ Aside from stability and bug fixes found during the alpha period - the main focu
 
 --- done ---
 
+- Done - Sprint Status Workflow to generate the story status tracker
 - Done - Brownfield v6 integrated into the workflow.
 - Done - Full workflow single file tracking.
 - Done - BoMB Tooling included with module install