bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.21

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

@@ -3,43 +3,55 @@ name: "retrospective"
 description: "Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic"
 author: "BMad"
 
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/_bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
 date: system-generated
+implementation_artifacts: "{config_source}:implementation_artifacts"
 
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective"
+installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective"
 template: false
 instructions: "{installed_path}/instructions.md"
 
-mode: interactive
-trigger: "Run AFTER completing an epic"
-
 required_inputs:
-  - agent_manifest: "{project-root}/bmad/_cfg/agent-manifest.csv"
-
-output_artifacts:
-  - retrospective_summary: "Comprehensive review of what went well and what could improve"
-  - lessons_learned: "Key insights for future epics"
-  - action_items: "Specific improvements with ownership"
-  - next_epic_preparation: "Dependencies, gaps, and preparation tasks for next epic"
-  - critical_path: "Blockers or prerequisites that must be addressed"
-
-facilitation:
-  facilitator: "Bob (Scrum Master)"
-  tone: "Psychological safety - no blame, focus on systems and processes"
-  format: "Two-part: (1) Review completed epic + (2) Preview next epic preparation"
-
-validation_required:
-  - testing_complete: "Has full regression testing been completed?"
-  - deployment_status: "Has epic been deployed to production?"
-  - business_validation: "Have stakeholders reviewed and accepted deliverables?"
-  - technical_health: "Is codebase in stable, maintainable state?"
-  - blocker_resolution: "Any unresolved blockers that will impact next epic?"
+  - agent_manifest: "{project-root}/_bmad/_config/agent-manifest.csv"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives
+input_file_patterns:
+  epics:
+    description: "The completed epic for retrospective"
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+    load_strategy: "SELECTIVE_LOAD"
+  previous_retrospective:
+    description: "Previous epic's retrospective (optional)"
+    pattern: "{implementation_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md"
+    load_strategy: "SELECTIVE_LOAD"
+  architecture:
+    description: "System architecture for context"
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  prd:
+    description: "Product requirements for context"
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{output_folder}/*.md"
+    load_strategy: "INDEX_GUIDED"
+
+# Required files
+sprint_status_file: "{implementation_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+story_directory: "{implementation_artifacts}"
+retrospectives_folder: "{implementation_artifacts}"
 
 standalone: true
-
 web_bundle: false

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

@@ -1,7 +1,24 @@
 # 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>
+<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>
+
+## 📚 Document Discovery - Full Epic Loading
+
+**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking.
+
+**Epic Discovery Process:**
+
+1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file
+2. **Check for sharded version** - If whole document not found, look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.)
+   - Process all epics and their stories from the combined content
+   - This ensures complete sprint status coverage
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc.
 
 <workflow>
 
@@ -26,6 +43,11 @@
 <action>Build complete inventory of all epics and stories from all epic files</action>
 </step>
 
+  <step n="0.5" goal="Discover and load project documents">
+    <invoke-protocol name="discover_inputs" />
+    <note>After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy)</note>
+  </step>
+
 <step n="2" goal="Build sprint status structure">
 <action>For each epic found, create entries in this order:</action>
 
@@ -46,34 +68,23 @@ development_status:
 </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`)
+- Never downgrade status (e.g., don't change `done` to `ready-for-dev`)
 
 **Status Flow Reference:**
 
-- Epic: `backlog` → `contexted`
-- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done`
-- Retrospective: `optional` ↔ `completed`
+- Epic: `backlog` → `in-progress` → `done`
+- Story: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Retrospective: `optional` ↔ `done`
   </step>
 
 <step n="4" goal="Generate sprint status file">
@@ -91,27 +102,31 @@ development_status:
 # STATUS DEFINITIONS:
 # ==================
 # Epic Status:
-#   - backlog: Epic exists in epic file but not contexted
-#   - contexted: Epic tech context created (required before drafting stories)
+#   - backlog: Epic not yet started
+#   - in-progress: Epic actively being worked on
+#   - done: All stories in epic completed
+#
+# Epic Status Transitions:
+#   - backlog → in-progress: Automatically when first story is created (via create-story)
+#   - in-progress → done: Manually when all stories reach 'done' status
 #
 # Story Status:
 #   - backlog: Story only exists in epic file
-#   - drafted: Story file created in stories folder
-#   - ready-for-dev: Draft approved and story context created
+#   - ready-for-dev: Story file created in stories folder
 #   - in-progress: Developer actively working on implementation
-#   - review: Under SM review (via code-review workflow)
+#   - review: Ready for code review (via Dev's code-review workflow)
 #   - done: Story completed
 #
 # Retrospective Status:
 #   - optional: Can be completed but not required
-#   - completed: Retrospective has been done
+#   - done: Retrospective has been completed
 #
 # WORKFLOW NOTES:
 # ===============
-# - Epics should be 'contexted' before stories can be 'drafted'
+# - Epic transitions to 'in-progress' automatically when first story is created
 # - Stories can be worked in parallel if team capacity allows
-# - SM typically drafts next story after previous one is 'done' to incorporate learnings
-# - Dev moves story to 'review', SM reviews, then Dev moves to 'done'
+# - SM typically creates next story after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
 
 generated: { date }
 project: { project_name }
@@ -124,8 +139,6 @@ development_status:
 ```
 
 <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>
@@ -133,10 +146,10 @@ development_status:
 <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 in epic files appears in {status_file}
+- [ ] Every story in epic files appears in {status_file}
 - [ ] Every epic has a corresponding retrospective entry
-- [ ] No items in sprint-status.yaml that don't exist in epic files
+- [ ] No items in {status_file} that don't exist in epic files
 - [ ] All status values are legal (match state machine definitions)
 - [ ] File is valid YAML syntax
 
@@ -144,8 +157,7 @@ development_status:
 
 - Total epics: {{epic_count}}
 - Total stories: {{story_count}}
-- Epics contexted: {{contexted_count}}
-- Stories in progress: {{in_progress_count}}
+- Epics in-progress: {{in_progress_count}}
 - Stories done: {{done_count}}
 
 <action>Display completion summary to {user_name} in {communication_language}:</action>
@@ -155,13 +167,12 @@ development_status:
 - **File Location:** {status_file}
 - **Total Epics:** {{epic_count}}
 - **Total Stories:** {{story_count}}
-- **Contexted Epics:** {{contexted_count}}
-- **Stories In Progress:** {{in_progress_count}}
+- **Epics In Progress:** {{epics_in_progress_count}}
 - **Stories Completed:** {{done_count}}
 
 **Next Steps:**
 
-1. Review the generated sprint-status.yaml
+1. Review the generated {status_file}
 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
@@ -177,45 +188,38 @@ development_status:
 **Epic Status Flow:**
 
 ```
-backlog → contexted
+backlog → in-progress → done
 ```
 
-- **backlog**: Epic exists in epic file but tech context not created
-- **contexted**: Epic tech context has been generated (prerequisite for story drafting)
+- **backlog**: Epic not yet started
+- **in-progress**: Epic actively being worked on (stories being created/implemented)
+- **done**: All stories in epic completed
 
 **Story Status Flow:**
 
 ```
-backlog → drafted → ready-for-dev → in-progress → review → done
+backlog → ready-for-dev → in-progress → review → done
 ```
 
 - **backlog**: Story only exists in epic file
-- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
-- **ready-for-dev**: Draft approved + story context created
+- **ready-for-dev**: Story file created (e.g., `stories/1-3-plant-naming.md`)
 - **in-progress**: Developer actively working
-- **review**: Under SM review (via code-review workflow)
+- **review**: Ready for code review (via Dev's code-review workflow)
 - **done**: Completed
 
 **Retrospective Status:**
 
 ```
-optional ↔ completed
+optional ↔ done
 ```
 
-- **optional**: Can be done but not required
-- **completed**: Retrospective has been completed
+- **optional**: Ready to be conducted but not required
+- **done**: Finished
 
 ### Guidelines
 
-1. **Epic Context Recommended**: Epics should be `contexted` before stories can be `drafted`
+1. **Epic Activation**: Mark epic as `in-progress` when starting work on its first story
 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`)
+5. **Learning Transfer**: SM typically creates next story after previous one is `done` to incorporate learnings

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

@@ -11,26 +11,26 @@
 # STATUS DEFINITIONS:
 # ==================
 # Epic Status:
-#   - backlog: Epic exists in epic file but not contexted
-#   - contexted: Next epic tech context created by *epic-tech-context (required)
+#   - backlog: Epic not yet started
+#   - in-progress: Epic actively being worked on
+#   - done: All stories in epic completed
 #
 # Story Status:
 #   - backlog: Story only exists in epic file
-#   - drafted: Story file created in stories folder by *create-story
-#   - ready-for-dev: Draft approved and story context created by *story-ready
-#   - in-progress: Developer actively working on implementation by *dev-story
-#   - review: Implementation complete, ready for review by *code-review
-#   - done: Story completed by *story-done
+#   - ready-for-dev: Story file created, ready for development
+#   - in-progress: Developer actively working on implementation
+#   - review: Implementation complete, ready for review
+#   - done: Story completed
 #
 # Retrospective Status:
 #   - optional: Can be completed but not required
-#   - completed: Retrospective has been done by *retrospective
+#   - done: Retrospective has been completed
 #
 # WORKFLOW NOTES:
 # ===============
-# - Epics should be 'contexted' before stories can be 'drafted'
-# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings
-# - Dev moves story to 'review', dev reviews, then Dev moves to 'done'
+# - Mark epic as 'in-progress' when starting work on its first story
+# - SM typically creates next story ONLY after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM)
 
 # EXAMPLE STRUCTURE (your actual epics/stories will replace these):
 
@@ -38,12 +38,12 @@ 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"
+story_location: "{story_location}"
 
 development_status:
-  epic-1: contexted
+  epic-1: backlog
   1-1-user-authentication: done
-  1-2-account-management: drafted
+  1-2-account-management: ready-for-dev
   1-3-plant-data-model: backlog
   1-4-add-plant-manual: backlog
   epic-1-retrospective: optional

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

@@ -3,35 +3,48 @@ description: "Generate and manage the sprint status tracking file for Phase 4 im
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
+config_source: "{project-root}/_bmad/bmm/config.yaml"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
+implementation_artifacts: "{config_source}:implementation_artifacts"
+planning_artifacts: "{config_source}:planning_artifacts"
+output_folder: "{implementation_artifacts}"
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/sprint-planning"
+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 context
+  project_context: "**/project-context.md"
   # 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
+  story_location: "{config_source}:implementation_artifacts" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
+  story_location_absolute: "{config_source}:implementation_artifacts" # Absolute path for file operations
 
   # Source files (file-system only)
-  epics_location: "{output_folder}" # Directory containing epic*.md files
+  epics_location: "{planning_artifacts}" # Directory containing epic*.md files
   epics_pattern: "epic*.md" # Pattern to find epic files
 
   # Output configuration
-  status_file: "{output_folder}/sprint-status.yaml"
+  status_file: "{implementation_artifacts}/sprint-status.yaml"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status
+input_file_patterns:
+  epics:
+    description: "All epics with user stories"
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/*.md"
+    load_strategy: "FULL_LOAD"
 
 # Output configuration
 default_output_file: "{status_file}"

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

@@ -0,0 +1,229 @@
+# Sprint Status - Multi-Mode Service
+
+<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-status/workflow.yaml</critical>
+<critical>Modes: interactive (default), validate, data</critical>
+<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES. Do NOT mention hours, days, weeks, or timelines.</critical>
+
+<workflow>
+
+<step n="0" goal="Determine execution mode">
+  <action>Set mode = {{mode}} if provided by caller; otherwise mode = "interactive"</action>
+
+  <check if="mode == data">
+    <action>Jump to Step 20</action>
+  </check>
+
+  <check if="mode == validate">
+    <action>Jump to Step 30</action>
+  </check>
+
+  <check if="mode == interactive">
+    <action>Continue to Step 1</action>
+  </check>
+</step>
+
+<step n="1" goal="Locate sprint status file">
+  <action>Try {sprint_status_file}</action>
+  <check if="file not found">
+    <output>❌ sprint-status.yaml not found.
+Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-status.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Continue to Step 2</action>
+</step>
+
+<step n="2" goal="Read and parse sprint-status.yaml">
+  <action>Read the FULL file: {sprint_status_file}</action>
+  <action>Parse fields: generated, project, project_key, tracking_system, story_location</action>
+  <action>Parse development_status map. Classify keys:</action>
+  - Epics: keys starting with "epic-" (and not ending with "-retrospective")
+  - Retrospectives: keys ending with "-retrospective"
+  - Stories: everything else (e.g., 1-2-login-form)
+  <action>Map legacy story status "drafted" → "ready-for-dev"</action>
+  <action>Count story statuses: backlog, ready-for-dev, in-progress, review, done</action>
+  <action>Map legacy epic status "contexted" → "in-progress"</action>
+  <action>Count epic statuses: backlog, in-progress, done</action>
+  <action>Count retrospective statuses: optional, done</action>
+
+<action>Validate all statuses against known values:</action>
+
+- Valid story statuses: backlog, ready-for-dev, in-progress, review, done, drafted (legacy)
+- Valid epic statuses: backlog, in-progress, done, contexted (legacy)
+- Valid retrospective statuses: optional, done
+
+  <check if="any status is unrecognized">
+    <output>
+⚠️ **Unknown status detected:**
+{{#each invalid_entries}}
+
+- `{{key}}`: "{{status}}" (not recognized)
+  {{/each}}
+
+**Valid statuses:**
+
+- Stories: backlog, ready-for-dev, in-progress, review, done
+- Epics: backlog, in-progress, done
+- Retrospectives: optional, done
+  </output>
+  <ask>How should these be corrected?
+  {{#each invalid_entries}}
+  {{@index}}. {{key}}: "{{status}}" → [select valid status]
+  {{/each}}
+
+Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue without fixing:</ask>
+<check if="user provided corrections">
+<action>Update sprint-status.yaml with corrected values</action>
+<action>Re-parse the file with corrected statuses</action>
+</check>
+</check>
+
+<action>Detect risks:</action>
+
+- IF any story has status "review": suggest `/bmad:bmm:workflows:code-review`
+- IF any story has status "in-progress" AND no stories have status "ready-for-dev": recommend staying focused on active story
+- IF all epics have status "backlog" AND no stories have status "ready-for-dev": prompt `/bmad:bmm:workflows:create-story`
+- IF `generated` timestamp is more than 7 days old: warn "sprint-status.yaml may be stale"
+- IF any story key doesn't match an epic pattern (e.g., story "5-1-..." but no "epic-5"): warn "orphaned story detected"
+- IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories"
+  </step>
+
+<step n="3" goal="Select next action recommendation">
+  <action>Pick the next recommended workflow using priority:</action>
+  <note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note>
+  1. If any story status == in-progress → recommend `dev-story` for the first in-progress story
+  2. Else if any story status == review → recommend `code-review` for the first review story
+  3. Else if any story status == ready-for-dev → recommend `dev-story`
+  4. Else if any story status == backlog → recommend `create-story`
+  5. Else if any retrospective status == optional → recommend `retrospective`
+  6. Else → All implementation items done; suggest `workflow-status` to plan next phase
+  <action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate)</action>
+</step>
+
+<step n="4" goal="Display summary">
+  <output>
+## 📊 Sprint Status
+
+- Project: {{project}} ({{project_key}})
+- Tracking: {{tracking_system}}
+- Status file: {sprint_status_file}
+
+**Stories:** backlog {{count_backlog}}, ready-for-dev {{count_ready}}, in-progress {{count_in_progress}}, review {{count_review}}, done {{count_done}}
+
+**Epics:** backlog {{epic_backlog}}, in-progress {{epic_in_progress}}, done {{epic_done}}
+
+**Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}})
+
+{{#if risks}}
+**Risks:**
+{{#each risks}}
+
+- {{this}}
+  {{/each}}
+  {{/if}}
+
+  </output>
+  </step>
+
+<step n="5" goal="Offer actions">
+  <ask>Pick an option:
+1) Run recommended workflow now
+2) Show all stories grouped by status
+3) Show raw sprint-status.yaml
+4) Exit
+Choice:</ask>
+
+  <check if="choice == 1">
+    <output>Run `/bmad:bmm:workflows:{{next_workflow_id}}`.
+If the command targets a story, set `story_key={{next_story_id}}` when prompted.</output>
+  </check>
+
+  <check if="choice == 2">
+    <output>
+### Stories by Status
+- In Progress: {{stories_in_progress}}
+- Review: {{stories_in_review}}
+- Ready for Dev: {{stories_ready_for_dev}}
+- Backlog: {{stories_backlog}}
+- Done: {{stories_done}}
+    </output>
+  </check>
+
+  <check if="choice == 3">
+    <action>Display the full contents of {sprint_status_file}</action>
+  </check>
+
+  <check if="choice == 4">
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<!-- ========================= -->
+<!-- Data mode for other flows -->
+<!-- ========================= -->
+
+<step n="20" goal="Data mode output">
+  <action>Load and parse {sprint_status_file} same as Step 2</action>
+  <action>Compute recommendation same as Step 3</action>
+  <template-output>next_workflow_id = {{next_workflow_id}}</template-output>
+  <template-output>next_story_id = {{next_story_id}}</template-output>
+  <template-output>count_backlog = {{count_backlog}}</template-output>
+  <template-output>count_ready = {{count_ready}}</template-output>
+  <template-output>count_in_progress = {{count_in_progress}}</template-output>
+  <template-output>count_review = {{count_review}}</template-output>
+  <template-output>count_done = {{count_done}}</template-output>
+  <template-output>epic_backlog = {{epic_backlog}}</template-output>
+  <template-output>epic_in_progress = {{epic_in_progress}}</template-output>
+  <template-output>epic_done = {{epic_done}}</template-output>
+  <template-output>risks = {{risks}}</template-output>
+  <action>Return to caller</action>
+</step>
+
+<!-- ========================= -->
+<!-- Validate mode -->
+<!-- ========================= -->
+
+<step n="30" goal="Validate sprint-status file">
+  <action>Check that {sprint_status_file} exists</action>
+  <check if="missing">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "sprint-status.yaml missing"</template-output>
+    <template-output>suggestion = "Run sprint-planning to create it"</template-output>
+    <action>Return</action>
+  </check>
+
+<action>Read and parse {sprint_status_file}</action>
+
+<action>Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location</action>
+<check if="any required field missing">
+<template-output>is_valid = false</template-output>
+<template-output>error = "Missing required field(s): {{missing_fields}}"</template-output>
+<template-output>suggestion = "Re-run sprint-planning or add missing fields manually"</template-output>
+<action>Return</action>
+</check>
+
+<action>Verify development_status section exists with at least one entry</action>
+<check if="development_status missing or empty">
+<template-output>is_valid = false</template-output>
+<template-output>error = "development_status missing or empty"</template-output>
+<template-output>suggestion = "Re-run sprint-planning or repair the file manually"</template-output>
+<action>Return</action>
+</check>
+
+<action>Validate all status values against known valid statuses:</action>
+
+- Stories: backlog, ready-for-dev, in-progress, review, done (legacy: drafted)
+- Epics: backlog, in-progress, done (legacy: contexted)
+- Retrospectives: optional, done
+  <check if="any invalid status found">
+  <template-output>is_valid = false</template-output>
+  <template-output>error = "Invalid status values: {{invalid_entries}}"</template-output>
+  <template-output>suggestion = "Fix invalid statuses in sprint-status.yaml"</template-output>
+  <action>Return</action>
+  </check>
+
+<template-output>is_valid = true</template-output>
+<template-output>message = "sprint-status.yaml valid: metadata complete, all statuses recognized"</template-output>
+</step>
+
+</workflow>