diff --git a/src/bmm/agents/dev.agent.yaml b/src/bmm/agents/dev.agent.yaml
index c707124d0..6de3d2c97 100644
--- a/src/bmm/agents/dev.agent.yaml
+++ b/src/bmm/agents/dev.agent.yaml
@@ -30,9 +30,9 @@ agent:
menu:
- trigger: DS or fuzzy match on dev-story
- workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml"
+ workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story/workflow.md"
description: "[DS] Dev Story: Write the next or specified stories tests and code."
- trigger: CR or fuzzy match on code-review
- workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml"
+ workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md"
description: "[CR] Code Review: Initiate a comprehensive code review across multiple quality facets. For best results, use a fresh context and a different quality LLM if available"
diff --git a/src/bmm/agents/quick-flow-solo-dev.agent.yaml b/src/bmm/agents/quick-flow-solo-dev.agent.yaml
index 553cc9d4d..72f861e8e 100644
--- a/src/bmm/agents/quick-flow-solo-dev.agent.yaml
+++ b/src/bmm/agents/quick-flow-solo-dev.agent.yaml
@@ -32,5 +32,5 @@ agent:
description: "[QQ] Quick Dev New (Preview): Unified quick flow â clarify intent, plan, implement, review, present (experimental)"
- trigger: CR or fuzzy match on code-review
- workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml"
+ workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md"
description: "[CR] Code Review: Initiate a comprehensive code review across multiple quality facets. For best results, use a fresh context and a different quality LLM if available"
diff --git a/src/bmm/agents/sm.agent.yaml b/src/bmm/agents/sm.agent.yaml
index 26430f175..11716df24 100644
--- a/src/bmm/agents/sm.agent.yaml
+++ b/src/bmm/agents/sm.agent.yaml
@@ -24,7 +24,7 @@ agent:
description: "[SP] Sprint Planning: Generate or update the record that will sequence the tasks to complete the full project that the dev agent will follow"
- trigger: CS or fuzzy match on create-story
- workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
+ workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.md"
description: "[CS] Context Story: Prepare a story with all required context for implementation for the developer agent"
- trigger: ER or fuzzy match on epic-retrospective
diff --git a/src/bmm/module-help.csv b/src/bmm/module-help.csv
index 7a04cfdbd..5872c20dd 100644
--- a/src/bmm/module-help.csv
+++ b/src/bmm/module-help.csv
@@ -24,9 +24,9 @@ bmm,3-solutioning,Create Epics and Stories,CE,30,_bmad/bmm/workflows/3-solutioni
bmm,3-solutioning,Check Implementation Readiness,IR,70,_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md,bmad-bmm-check-implementation-readiness,true,architect,Validate Mode,"Ensure PRD UX Architecture and Epics Stories are aligned",planning_artifacts,"readiness report",
bmm,4-implementation,Sprint Planning,SP,10,_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md,bmad-bmm-sprint-planning,true,sm,Create Mode,"Generate sprint plan for development tasks - this kicks off the implementation phase by producing a plan the implementation agents will follow in sequence for every story in the plan.",implementation_artifacts,"sprint status",
bmm,4-implementation,Sprint Status,SS,20,_bmad/bmm/workflows/4-implementation/sprint-status/workflow.md,bmad-bmm-sprint-status,false,sm,Create Mode,"Anytime: Summarize sprint status and route to next workflow",,,
-bmm,4-implementation,Validate Story,VS,35,_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml,bmad-bmm-create-story,false,sm,Validate Mode,"Validates story readiness and completeness before development work begins",implementation_artifacts,"story validation report",
-bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story,
-bmm,4-implementation,Dev Story,DS,40,_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,,
-bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,,
+bmm,4-implementation,Validate Story,VS,35,_bmad/bmm/workflows/4-implementation/create-story/workflow.md,bmad-bmm-create-story,false,sm,Validate Mode,"Validates story readiness and completeness before development work begins",implementation_artifacts,"story validation report",
+bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.md,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story,
+bmm,4-implementation,Dev Story,DS,40,_bmad/bmm/workflows/4-implementation/dev-story/workflow.md,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,,
+bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.md,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,,
bmm,4-implementation,QA Automation Test,QA,45,_bmad/bmm/workflows/qa-generate-e2e-tests/workflow.md,bmad-bmm-qa-automate,false,qa,Create Mode,"Generate automated API and E2E tests for implemented code using the project's existing test framework (detects existing well known in use test frameworks). Use after implementation to add test coverage. NOT for code review or story validation - use CR for that.",implementation_artifacts,"test suite",
bmm,4-implementation,Retrospective,ER,60,_bmad/bmm/workflows/4-implementation/retrospective/workflow.md,bmad-bmm-retrospective,false,sm,Create Mode,"Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC",implementation_artifacts,retrospective,
diff --git a/src/bmm/workflows/4-implementation/code-review/instructions.xml b/src/bmm/workflows/4-implementation/code-review/instructions.xml
deleted file mode 100644
index 37b3eb63f..000000000
--- a/src/bmm/workflows/4-implementation/code-review/instructions.xml
+++ /dev/null
@@ -1,229 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
- Generate all documents in {document_output_language}
-
- đĨ YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! đĨ
- Your purpose: Validate story file claims against actual implementation
- Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?
- Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews - YOU are so much better than the dev agent
- that wrote this slop
- Read EVERY file in the File List - verify implementation against story requirements
- Tasks marked complete but not done = CRITICAL finding
- Acceptance Criteria not implemented = HIGH severity finding
- Do not review files that are not part of the application's source code. Always exclude the _bmad/ and _bmad-output/ folders from the review. Always exclude IDE and CLI configuration folders like .cursor/ and .windsurf/ and .claude/
-
-
-
- Use provided {{story_path}} or ask user which story file to review
- Read COMPLETE story file
- Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" â "1-2-user-authentication") or story
- metadata
- Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record â File List, Change Log
-
-
- Check if git repository detected in current directory
-
- Run `git status --porcelain` to find uncommitted changes
- Run `git diff --name-only` to see modified files
- Run `git diff --cached --name-only` to see staged files
- Compile list of actually changed files from git output
-
-
-
- Compare story's Dev Agent Record â File List with actual git changes
- Note discrepancies:
- - Files in git but not in story File List
- - Files in story File List but no git changes
- - Missing documentation of what was actually changed
-
-
-
- Load {project_context} for coding standards (if exists)
-
-
-
- Extract ALL Acceptance Criteria from story
- Extract ALL Tasks/Subtasks with completion status ([x] vs [ ])
- From Dev Agent Record â File List, compile list of claimed changes
-
- Create review plan:
- 1. **AC Validation**: Verify each AC is actually implemented
- 2. **Task Audit**: Verify each [x] task is really done
- 3. **Code Quality**: Security, performance, maintainability
- 4. **Test Quality**: Real tests vs placeholder bullshit
-
-
-
-
- VALIDATE EVERY CLAIM - Check git reality vs story claims
-
-
- Review git vs story File List discrepancies:
- 1. **Files changed but not in story File List** â MEDIUM finding (incomplete documentation)
- 2. **Story lists files but no git changes** â HIGH finding (false claims)
- 3. **Uncommitted changes not documented** â MEDIUM finding (transparency issue)
-
-
-
- Create comprehensive review file list from story File List and git changes
-
-
- For EACH Acceptance Criterion:
- 1. Read the AC requirement
- 2. Search implementation files for evidence
- 3. Determine: IMPLEMENTED, PARTIAL, or MISSING
- 4. If MISSING/PARTIAL â HIGH SEVERITY finding
-
-
-
- For EACH task marked [x]:
- 1. Read the task description
- 2. Search files for evidence it was actually done
- 3. **CRITICAL**: If marked [x] but NOT DONE â CRITICAL finding
- 4. Record specific proof (file:line)
-
-
-
- For EACH file in comprehensive review list:
- 1. **Security**: Look for injection risks, missing validation, auth issues
- 2. **Performance**: N+1 queries, inefficient loops, missing caching
- 3. **Error Handling**: Missing try/catch, poor error messages
- 4. **Code Quality**: Complex functions, magic numbers, poor naming
- 5. **Test Quality**: Are tests real assertions or placeholders?
-
-
-
- NOT LOOKING HARD ENOUGH - Find more problems!
- Re-examine code for:
- - Edge cases and null handling
- - Architecture violations
- - Documentation gaps
- - Integration issues
- - Dependency problems
- - Git commit message quality (if applicable)
-
- Find at least 3 more specific, actionable issues
-
-
-
-
- Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)
- Set {{fixed_count}} = 0
- Set {{action_count}} = 0
-
-
-
- What should I do with these issues?
-
- 1. **Fix them automatically** - I'll update the code and tests
- 2. **Create action items** - Add to story Tasks/Subtasks for later
- 3. **Show me details** - Deep dive into specific issues
-
- Choose [1], [2], or specify which issue to examine:
-
-
- Fix all HIGH and MEDIUM issues in the code
- Add/update tests as needed
- Update File List in story if files changed
- Update story Dev Agent Record with fixes applied
- Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed
- Set {{action_count}} = 0
-
-
-
- Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks
- For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`
- Set {{action_count}} = number of action items created
- Set {{fixed_count}} = 0
-
-
-
- Show detailed explanation with code examples
- Return to fix decision
-
-
-
-
-
-
- Set {{new_status}} = "done"
- Update story Status field to "done"
-
-
- Set {{new_status}} = "in-progress"
- Update story Status field to "in-progress"
-
- Save story file
-
-
-
- Set {{current_sprint_status}} = "enabled"
-
-
- Set {{current_sprint_status}} = "no-sprint-tracking"
-
-
-
-
- Load the FULL file: {sprint_status}
- Find development_status key matching {{story_key}}
-
-
- Update development_status[{{story_key}}] = "done"
- Update last_updated field to current date
- Save file, preserving ALL comments and structure
-
-
-
-
- Update development_status[{{story_key}}] = "in-progress"
- Update last_updated field to current date
- Save file, preserving ALL comments and structure
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/src/bmm/workflows/4-implementation/code-review/workflow.md b/src/bmm/workflows/4-implementation/code-review/workflow.md
new file mode 100644
index 000000000..fbfdf4cb2
--- /dev/null
+++ b/src/bmm/workflows/4-implementation/code-review/workflow.md
@@ -0,0 +1,271 @@
+---
+name: code-review
+description: 'Perform adversarial code review finding specific issues. Use when the user says "run code review" or "review this code"'
+---
+
+# Code Review Workflow
+
+**Goal:** Perform adversarial code review finding specific issues.
+
+**Your Role:** Adversarial Code Reviewer.
+- YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing!
+- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+- Generate all documents in {document_output_language}
+- Your purpose: Validate story file claims against actual implementation
+- Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?
+- Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews - YOU are so much better than the dev agent that wrote this slop
+- Read EVERY file in the File List - verify implementation against story requirements
+- Tasks marked complete but not done = CRITICAL finding
+- Acceptance Criteria not implemented = HIGH severity finding
+- Do not review files that are not part of the application's source code. Always exclude the `_bmad/` and `_bmad-output/` folders from the review. Always exclude IDE and CLI configuration folders like `.cursor/` and `.windsurf/` and `.claude/`
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/code-review`
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `validation` = `{installed_path}/checklist.md`
+
+### Input Files
+
+| Input | Description | Path Pattern(s) | Load Strategy |
+|-------|-------------|------------------|---------------|
+| architecture | System architecture for review context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD |
+| ux_design | UX design specification (if UI review) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | FULL_LOAD |
+| epics | Epic containing story being reviewed | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD |
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+
+
+
+ Use provided {{story_path}} or ask user which story file to review
+ Read COMPLETE story file
+ Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" â "1-2-user-authentication") or story
+ metadata
+ Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record â File List, Change Log
+
+
+ Check if git repository detected in current directory
+
+ Run `git status --porcelain` to find uncommitted changes
+ Run `git diff --name-only` to see modified files
+ Run `git diff --cached --name-only` to see staged files
+ Compile list of actually changed files from git output
+
+
+
+ Compare story's Dev Agent Record â File List with actual git changes
+ Note discrepancies:
+ - Files in git but not in story File List
+ - Files in story File List but no git changes
+ - Missing documentation of what was actually changed
+
+
+
+ Load {project_context} for coding standards (if exists)
+
+
+
+ Extract ALL Acceptance Criteria from story
+ Extract ALL Tasks/Subtasks with completion status ([x] vs [ ])
+ From Dev Agent Record â File List, compile list of claimed changes
+
+ Create review plan:
+ 1. **AC Validation**: Verify each AC is actually implemented
+ 2. **Task Audit**: Verify each [x] task is really done
+ 3. **Code Quality**: Security, performance, maintainability
+ 4. **Test Quality**: Real tests vs placeholder bullshit
+
+
+
+
+ VALIDATE EVERY CLAIM - Check git reality vs story claims
+
+
+ Review git vs story File List discrepancies:
+ 1. **Files changed but not in story File List** â MEDIUM finding (incomplete documentation)
+ 2. **Story lists files but no git changes** â HIGH finding (false claims)
+ 3. **Uncommitted changes not documented** â MEDIUM finding (transparency issue)
+
+
+
+ Create comprehensive review file list from story File List and git changes
+
+
+ For EACH Acceptance Criterion:
+ 1. Read the AC requirement
+ 2. Search implementation files for evidence
+ 3. Determine: IMPLEMENTED, PARTIAL, or MISSING
+ 4. If MISSING/PARTIAL â HIGH SEVERITY finding
+
+
+
+ For EACH task marked [x]:
+ 1. Read the task description
+ 2. Search files for evidence it was actually done
+ 3. **CRITICAL**: If marked [x] but NOT DONE â CRITICAL finding
+ 4. Record specific proof (file:line)
+
+
+
+ For EACH file in comprehensive review list:
+ 1. **Security**: Look for injection risks, missing validation, auth issues
+ 2. **Performance**: N+1 queries, inefficient loops, missing caching
+ 3. **Error Handling**: Missing try/catch, poor error messages
+ 4. **Code Quality**: Complex functions, magic numbers, poor naming
+ 5. **Test Quality**: Are tests real assertions or placeholders?
+
+
+
+ NOT LOOKING HARD ENOUGH - Find more problems!
+ Re-examine code for:
+ - Edge cases and null handling
+ - Architecture violations
+ - Documentation gaps
+ - Integration issues
+ - Dependency problems
+ - Git commit message quality (if applicable)
+
+ Find at least 3 more specific, actionable issues
+
+
+
+
+ Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)
+ Set {{fixed_count}} = 0
+ Set {{action_count}} = 0
+
+
+
+ What should I do with these issues?
+
+ 1. **Fix them automatically** - I'll update the code and tests
+ 2. **Create action items** - Add to story Tasks/Subtasks for later
+ 3. **Show me details** - Deep dive into specific issues
+
+ Choose [1], [2], or specify which issue to examine:
+
+
+ Fix all HIGH and MEDIUM issues in the code
+ Add/update tests as needed
+ Update File List in story if files changed
+ Update story Dev Agent Record with fixes applied
+ Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed
+ Set {{action_count}} = 0
+
+
+
+ Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks
+ For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`
+ Set {{action_count}} = number of action items created
+ Set {{fixed_count}} = 0
+
+
+
+ Show detailed explanation with code examples
+ Return to fix decision
+
+
+
+
+
+
+ Set {{new_status}} = "done"
+ Update story Status field to "done"
+
+
+ Set {{new_status}} = "in-progress"
+ Update story Status field to "in-progress"
+
+ Save story file
+
+
+
+ Set {{current_sprint_status}} = "enabled"
+
+
+ Set {{current_sprint_status}} = "no-sprint-tracking"
+
+
+
+
+ Load the FULL file: {sprint_status}
+ Find development_status key matching {{story_key}}
+
+
+ Update development_status[{{story_key}}] = "done"
+ Update last_updated field to current date
+ Save file, preserving ALL comments and structure
+
+
+
+
+ Update development_status[{{story_key}}] = "in-progress"
+ Update last_updated field to current date
+ Save file, preserving ALL comments and structure
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/bmm/workflows/4-implementation/code-review/workflow.yaml b/src/bmm/workflows/4-implementation/code-review/workflow.yaml
deleted file mode 100644
index 7965af5ae..000000000
--- a/src/bmm/workflows/4-implementation/code-review/workflow.yaml
+++ /dev/null
@@ -1,43 +0,0 @@
-# Review Story Workflow
-name: code-review
-description: 'Perform adversarial code review finding specific issues. Use when the user says "run code review" or "review this code"'
-
-# Critical variables from config
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-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
-planning_artifacts: "{config_source}:planning_artifacts"
-implementation_artifacts: "{config_source}:implementation_artifacts"
-sprint_status: "{implementation_artifacts}/sprint-status.yaml"
-
-# Workflow components
-installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review"
-instructions: "{installed_path}/instructions.xml"
-validation: "{installed_path}/checklist.md"
-template: false
-
-project_context: "**/project-context.md"
-
-# Smart input file references - handles both whole docs and sharded docs
-# Priority: Whole document first, then sharded version
-# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
-input_file_patterns:
- architecture:
- description: "System architecture for review context"
- whole: "{planning_artifacts}/*architecture*.md"
- sharded: "{planning_artifacts}/*architecture*/*.md"
- load_strategy: "FULL_LOAD"
- ux_design:
- description: "UX design specification (if UI review)"
- whole: "{planning_artifacts}/*ux*.md"
- sharded: "{planning_artifacts}/*ux*/*.md"
- load_strategy: "FULL_LOAD"
- epics:
- description: "Epic containing story being reviewed"
- whole: "{planning_artifacts}/*epic*.md"
- sharded_index: "{planning_artifacts}/*epic*/index.md"
- sharded_single: "{planning_artifacts}/*epic*/epic-{{epic_num}}.md"
- load_strategy: "SELECTIVE_LOAD"
diff --git a/src/bmm/workflows/4-implementation/create-story/checklist.md b/src/bmm/workflows/4-implementation/create-story/checklist.md
index d9ed06375..7b8550e2d 100644
--- a/src/bmm/workflows/4-implementation/create-story/checklist.md
+++ b/src/bmm/workflows/4-implementation/create-story/checklist.md
@@ -36,20 +36,20 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de
- The `{project-root}/_bmad/core/tasks/workflow.xml` framework will automatically:
- Load this checklist file
- Load the newly created story file (`{story_file_path}`)
- - Load workflow variables from `{installed_path}/workflow.yaml`
+ - Load workflow variables from `{installed_path}/workflow.md`
- Execute the validation process
### **When Running in Fresh Context:**
- User should provide the story file path being reviewed
- Load the story file directly
-- Load the corresponding workflow.yaml for variable context
+- Load the corresponding workflow.md for variable context
- Proceed with systematic analysis
### **Required Inputs:**
- **Story file**: The story file to review and improve
-- **Workflow variables**: From workflow.yaml (implementation_artifacts, epics_file, etc.)
+- **Workflow variables**: From workflow.md (implementation_artifacts, epics_file, etc.)
- **Source documents**: Epics, architecture, etc. (discovered or provided)
- **Validation framework**: `validate-workflow.xml` (handles checklist execution)
@@ -61,7 +61,7 @@ You will systematically re-do the entire story creation process, but with a crit
### **Step 1: Load and Understand the Target**
-1. **Load the workflow configuration**: `{installed_path}/workflow.yaml` for variable inclusion
+1. **Load the workflow configuration**: `{installed_path}/workflow.md` for variable inclusion
2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
3. **Load validation framework**: `{project-root}/_bmad/core/tasks/workflow.xml`
4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml
deleted file mode 100644
index efdc87c0e..000000000
--- a/src/bmm/workflows/4-implementation/create-story/instructions.xml
+++ /dev/null
@@ -1,347 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
-
- đĨ CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or
- disasters! đĨ
- Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent
- EVERYTHING needed for flawless implementation
- COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX,
- vague implementations, lying about completion, not learning from past work
- đ¨ EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim!
- This is the most important function in the entire development process!
- đŦ UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly
- analyze different artifacts simultaneously and thoroughly
- â SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is
- written
- đ¯ ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents
-
-
-
- Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth"
- Set {{epic_num}}, {{story_num}}, {{story_key}} from user input
- GOTO step 2a
-
-
- Check if {{sprint_status}} file exists for auto discover
-
-
-
- Choose option [1], provide epic-story number, path to story docs, or [q] to quit:
-
-
- HALT - No work needed
-
-
-
-
- HALT - User needs to run sprint-planning
-
-
-
- Parse user input: extract epic_num, story_num, story_title
- Set {{epic_num}}, {{story_num}}, {{story_key}} from user input
- GOTO step 2a
-
-
-
- Use user-provided path for story documents
- GOTO step 2a
-
-
-
-
-
- MUST read COMPLETE {sprint_status} file from start to end to preserve order
- Load the FULL file: {{sprint_status}}
- Read ALL lines from beginning to end - do not skip any content
- Parse the development_status section completely
-
- Find the FIRST story (by reading in order from top to bottom) where:
- - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
- - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
- - Status value equals "backlog"
-
-
-
-
- HALT
-
-
- Extract from found story key (e.g., "1-2-user-authentication"):
- - epic_num: first number before dash (e.g., "1")
- - story_num: second number after first dash (e.g., "2")
- - story_title: remainder after second dash (e.g., "user-authentication")
-
- Set {{story_id}} = "{{epic_num}}.{{story_num}}"
- Store story_key for later use (e.g., "1-2-user-authentication")
-
-
- Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern
-
- Load {{sprint_status}} and check epic-{{epic_num}} status
- If epic status is "backlog" â update to "in-progress"
- If epic status is "contexted" (legacy status) â update to "in-progress" (backward compatibility)
- If epic status is "in-progress" â no change needed
-
-
-
-
-
-
- HALT - Cannot proceed
-
-
-
-
-
- HALT - Cannot proceed
-
-
-
-
- GOTO step 2a
-
- Load the FULL file: {{sprint_status}}
- Read ALL lines from beginning to end - do not skip any content
- Parse the development_status section completely
-
- Find the FIRST story (by reading in order from top to bottom) where:
- - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
- - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
- - Status value equals "backlog"
-
-
-
-
- HALT
-
-
- Extract from found story key (e.g., "1-2-user-authentication"):
- - epic_num: first number before dash (e.g., "1")
- - story_num: second number after first dash (e.g., "2")
- - story_title: remainder after second dash (e.g., "user-authentication")
-
- Set {{story_id}} = "{{epic_num}}.{{story_num}}"
- Store story_key for later use (e.g., "1-2-user-authentication")
-
-
- Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern
-
- Load {{sprint_status}} and check epic-{{epic_num}} status
- If epic status is "backlog" â update to "in-progress"
- If epic status is "contexted" (legacy status) â update to "in-progress" (backward compatibility)
- If epic status is "in-progress" â no change needed
-
-
-
-
-
-
- HALT - Cannot proceed
-
-
-
-
-
- HALT - Cannot proceed
-
-
-
-
- GOTO step 2a
-
-
-
- đŦ EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer fuckups!
-
-
-
- Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content},
- {project_context}
-
-
- From {epics_content}, extract Epic {{epic_num}} complete context: **EPIC ANALYSIS:** - Epic
- objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story
- statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to
- original documents
- Extract our story ({{epic_num}}-{{story_num}}) details: **STORY FOUNDATION:** - User story statement
- (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story -
- Business context and value - Success criteria
-
- Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}}
- Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md **PREVIOUS STORY INTELLIGENCE:** -
- Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their
- patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established Extract
- all learnings that could impact current story implementation
-
-
-
-
- Get last 5 commit titles to understand recent work patterns
- Analyze 1-5 most recent commits for relevance to current story:
- - Files created/modified
- - Code patterns and conventions used
- - Library dependencies added/changed
- - Architecture decisions implemented
- - Testing approaches used
-
- Extract actionable insights for current story implementation
-
-
-
-
- đī¸ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow! **ARCHITECTURE DOCUMENT ANALYSIS:** Systematically
- analyze architecture content for story-relevant requirements:
-
-
-
- Load complete {architecture_content}
-
-
- Load architecture index and scan all architecture files
- **CRITICAL ARCHITECTURE EXTRACTION:** For
- each architecture section, determine if relevant to this story: - **Technical Stack:** Languages, frameworks, libraries with
- versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint
- patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:**
- Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing
- Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build
- processes - **Integration Patterns:** External service integrations, data flows Extract any story-specific requirements that the
- developer MUST follow
- Identify any architectural decisions that override previous patterns
-
-
-
- đ ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations! **WEB INTELLIGENCE:** Identify specific
- technical areas that require latest version knowledge:
-
-
- From architecture analysis, identify specific libraries, APIs, or
- frameworks
- For each critical technology, research latest stable version and key changes:
- - Latest API documentation and breaking changes
- - Security vulnerabilities or updates
- - Performance improvements or deprecations
- - Best practices for current version
-
- **EXTERNAL CONTEXT INCLUSION:** Include in story any critical latest information the developer needs:
- - Specific library versions and why chosen
- - API endpoints with parameters and authentication
- - Recent security patches or considerations
- - Performance optimization techniques
- - Migration considerations if upgrading
-
-
-
-
- đ CREATE ULTIMATE STORY FILE - The developer's master implementation guide!
-
- Initialize from template.md:
- {default_output_file}
- story_header
-
-
- story_requirements
-
-
-
- developer_context_section **DEV AGENT GUARDRAILS:**
- technical_requirements
- architecture_compliance
- library_framework_requirements
-
- file_structure_requirements
- testing_requirements
-
-
-
- previous_story_intelligence
-
-
-
-
- git_intelligence_summary
-
-
-
-
- latest_tech_information
-
-
-
- project_context_reference
-
-
-
- story_completion_status
-
-
- Set story Status to: "ready-for-dev"
- Add completion note: "Ultimate
- context engine analysis completed - comprehensive developer guide created"
-
-
-
- Validate the newly created story file {story_file} against {installed_path}/checklist.md and apply any required fixes before finalizing
- Save story document unconditionally
-
-
-
- Update {{sprint_status}}
- Load the FULL file and read all development_status entries
- Find development_status key matching {{story_key}}
- Verify current status is "backlog" (expected previous state)
- Update development_status[{{story_key}}] = "ready-for-dev"
- Update last_updated field to current date
- Save file, preserving ALL comments and structure including STATUS DEFINITIONS
-
-
- Report completion
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.md b/src/bmm/workflows/4-implementation/create-story/workflow.md
new file mode 100644
index 000000000..55556adb6
--- /dev/null
+++ b/src/bmm/workflows/4-implementation/create-story/workflow.md
@@ -0,0 +1,389 @@
+---
+name: create-story
+description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"'
+---
+
+# Create Story Workflow
+
+**Goal:** Create a comprehensive story file that gives the dev agent everything needed for flawless implementation.
+
+**Your Role:** Story context engine that prevents LLM developer mistakes, omissions, or disasters.
+- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
+- Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent EVERYTHING needed for flawless implementation
+- COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, vague implementations, lying about completion, not learning from past work
+- EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! This is the most important function in the entire development process!
+- UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different artifacts simultaneously and thoroughly
+- SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is written
+- ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/create-story`
+- `template` = `{installed_path}/template.md`
+- `validation` = `{installed_path}/checklist.md`
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `epics_file` = `{planning_artifacts}/epics.md`
+- `prd_file` = `{planning_artifacts}/prd.md`
+- `architecture_file` = `{planning_artifacts}/architecture.md`
+- `ux_file` = `{planning_artifacts}/*ux*.md`
+- `story_title` = "" (will be elicited if not derivable)
+- `project_context` = `**/project-context.md` (load if exists)
+- `default_output_file` = `{implementation_artifacts}/{{story_key}}.md`
+
+### Input Files
+
+| Input | Description | Path Pattern(s) | Load Strategy |
+|-------|-------------|------------------|---------------|
+| prd | PRD (fallback - epics file should have most content) | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | SELECTIVE_LOAD |
+| architecture | Architecture (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | SELECTIVE_LOAD |
+| ux | UX design (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | SELECTIVE_LOAD |
+| epics | Enhanced epics+stories file with BDD and source hints | whole: `{planning_artifacts}/*epic*.md`, sharded: `{planning_artifacts}/*epic*/*.md` | SELECTIVE_LOAD |
+
+---
+
+## EXECUTION
+
+
+
+
+
+ Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth"
+ Set {{epic_num}}, {{story_num}}, {{story_key}} from user input
+ GOTO step 2a
+
+
+ Check if {{sprint_status}} file exists for auto discover
+
+
+
+ Choose option [1], provide epic-story number, path to story docs, or [q] to quit:
+
+
+ HALT - No work needed
+
+
+
+
+ HALT - User needs to run sprint-planning
+
+
+
+ Parse user input: extract epic_num, story_num, story_title
+ Set {{epic_num}}, {{story_num}}, {{story_key}} from user input
+ GOTO step 2a
+
+
+
+ Use user-provided path for story documents
+ GOTO step 2a
+
+
+
+
+
+ MUST read COMPLETE {sprint_status} file from start to end to preserve order
+ Load the FULL file: {{sprint_status}}
+ Read ALL lines from beginning to end - do not skip any content
+ Parse the development_status section completely
+
+ Find the FIRST story (by reading in order from top to bottom) where:
+ - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+ - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+ - Status value equals "backlog"
+
+
+
+
+ HALT
+
+
+ Extract from found story key (e.g., "1-2-user-authentication"):
+ - epic_num: first number before dash (e.g., "1")
+ - story_num: second number after first dash (e.g., "2")
+ - story_title: remainder after second dash (e.g., "user-authentication")
+
+ Set {{story_id}} = "{{epic_num}}.{{story_num}}"
+ Store story_key for later use (e.g., "1-2-user-authentication")
+
+
+ Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern
+
+ Load {{sprint_status}} and check epic-{{epic_num}} status
+ If epic status is "backlog" â update to "in-progress"
+ If epic status is "contexted" (legacy status) â update to "in-progress" (backward compatibility)
+ If epic status is "in-progress" â no change needed
+
+
+
+
+
+
+ HALT - Cannot proceed
+
+
+
+
+
+ HALT - Cannot proceed
+
+
+
+
+ GOTO step 2a
+
+ Load the FULL file: {{sprint_status}}
+ Read ALL lines from beginning to end - do not skip any content
+ Parse the development_status section completely
+
+ Find the FIRST story (by reading in order from top to bottom) where:
+ - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+ - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+ - Status value equals "backlog"
+
+
+
+
+ HALT
+
+
+ Extract from found story key (e.g., "1-2-user-authentication"):
+ - epic_num: first number before dash (e.g., "1")
+ - story_num: second number after first dash (e.g., "2")
+ - story_title: remainder after second dash (e.g., "user-authentication")
+
+ Set {{story_id}} = "{{epic_num}}.{{story_num}}"
+ Store story_key for later use (e.g., "1-2-user-authentication")
+
+
+ Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern
+
+ Load {{sprint_status}} and check epic-{{epic_num}} status
+ If epic status is "backlog" â update to "in-progress"
+ If epic status is "contexted" (legacy status) â update to "in-progress" (backward compatibility)
+ If epic status is "in-progress" â no change needed
+
+
+
+
+
+
+ HALT - Cannot proceed
+
+
+
+
+
+ HALT - Cannot proceed
+
+
+
+
+ GOTO step 2a
+
+
+
+ đŦ EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer fuckups!
+
+
+
+ Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content},
+ {project_context}
+
+
+ From {epics_content}, extract Epic {{epic_num}} complete context: **EPIC ANALYSIS:** - Epic
+ objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story
+ statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to
+ original documents
+ Extract our story ({{epic_num}}-{{story_num}}) details: **STORY FOUNDATION:** - User story statement
+ (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story -
+ Business context and value - Success criteria
+
+ Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}}
+ Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md **PREVIOUS STORY INTELLIGENCE:** -
+ Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their
+ patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established Extract
+ all learnings that could impact current story implementation
+
+
+
+
+ Get last 5 commit titles to understand recent work patterns
+ Analyze 1-5 most recent commits for relevance to current story:
+ - Files created/modified
+ - Code patterns and conventions used
+ - Library dependencies added/changed
+ - Architecture decisions implemented
+ - Testing approaches used
+
+ Extract actionable insights for current story implementation
+
+
+
+
+ đī¸ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow! **ARCHITECTURE DOCUMENT ANALYSIS:** Systematically
+ analyze architecture content for story-relevant requirements:
+
+
+
+ Load complete {architecture_content}
+
+
+ Load architecture index and scan all architecture files
+ **CRITICAL ARCHITECTURE EXTRACTION:** For
+ each architecture section, determine if relevant to this story: - **Technical Stack:** Languages, frameworks, libraries with
+ versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint
+ patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:**
+ Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing
+ Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build
+ processes - **Integration Patterns:** External service integrations, data flows Extract any story-specific requirements that the
+ developer MUST follow
+ Identify any architectural decisions that override previous patterns
+
+
+
+ đ ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations! **WEB INTELLIGENCE:** Identify specific
+ technical areas that require latest version knowledge:
+
+
+ From architecture analysis, identify specific libraries, APIs, or
+ frameworks
+ For each critical technology, research latest stable version and key changes:
+ - Latest API documentation and breaking changes
+ - Security vulnerabilities or updates
+ - Performance improvements or deprecations
+ - Best practices for current version
+
+ **EXTERNAL CONTEXT INCLUSION:** Include in story any critical latest information the developer needs:
+ - Specific library versions and why chosen
+ - API endpoints with parameters and authentication
+ - Recent security patches or considerations
+ - Performance optimization techniques
+ - Migration considerations if upgrading
+
+
+
+
+ đ CREATE ULTIMATE STORY FILE - The developer's master implementation guide!
+
+ Initialize from template.md:
+ {default_output_file}
+ story_header
+
+
+ story_requirements
+
+
+
+ developer_context_section **DEV AGENT GUARDRAILS:**
+ technical_requirements
+ architecture_compliance
+ library_framework_requirements
+
+ file_structure_requirements
+ testing_requirements
+
+
+
+ previous_story_intelligence
+
+
+
+
+ git_intelligence_summary
+
+
+
+
+ latest_tech_information
+
+
+
+ project_context_reference
+
+
+
+ story_completion_status
+
+
+ Set story Status to: "ready-for-dev"
+ Add completion note: "Ultimate
+ context engine analysis completed - comprehensive developer guide created"
+
+
+
+ Validate the newly created story file {story_file} against {installed_path}/checklist.md and apply any required fixes before finalizing
+ Save story document unconditionally
+
+
+
+ Update {{sprint_status}}
+ Load the FULL file and read all development_status entries
+ Find development_status key matching {{story_key}}
+ Verify current status is "backlog" (expected previous state)
+ Update development_status[{{story_key}}] = "ready-for-dev"
+ Update last_updated field to current date
+ Save file, preserving ALL comments and structure including STATUS DEFINITIONS
+
+
+ Report completion
+
+
+
+
diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/bmm/workflows/4-implementation/create-story/workflow.yaml
deleted file mode 100644
index 972972aff..000000000
--- a/src/bmm/workflows/4-implementation/create-story/workflow.yaml
+++ /dev/null
@@ -1,52 +0,0 @@
-name: create-story
-description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"'
-
-# Critical variables from config
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-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
-planning_artifacts: "{config_source}:planning_artifacts"
-implementation_artifacts: "{config_source}:implementation_artifacts"
-
-# Workflow components
-installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story"
-template: "{installed_path}/template.md"
-instructions: "{installed_path}/instructions.xml"
-validation: "{installed_path}/checklist.md"
-
-# Variables and inputs
-sprint_status: "{implementation_artifacts}/sprint-status.yaml" # Primary source for story tracking
-epics_file: "{planning_artifacts}/epics.md" # Enhanced epics+stories with BDD and source hints
-prd_file: "{planning_artifacts}/prd.md" # Fallback for requirements (if not in epics file)
-architecture_file: "{planning_artifacts}/architecture.md" # Fallback for constraints (if not in epics file)
-ux_file: "{planning_artifacts}/*ux*.md" # Fallback for UX requirements (if not in epics file)
-story_title: "" # Will be elicited if not derivable
-project_context: "**/project-context.md"
-default_output_file: "{implementation_artifacts}/{{story_key}}.md"
-
-# Smart input file references - Simplified for enhanced approach
-# The epics+stories file should contain everything needed with source hints
-input_file_patterns:
- prd:
- description: "PRD (fallback - epics file should have most content)"
- whole: "{planning_artifacts}/*prd*.md"
- sharded: "{planning_artifacts}/*prd*/*.md"
- load_strategy: "SELECTIVE_LOAD" # Only load if needed
- architecture:
- description: "Architecture (fallback - epics file should have relevant sections)"
- whole: "{planning_artifacts}/*architecture*.md"
- sharded: "{planning_artifacts}/*architecture*/*.md"
- load_strategy: "SELECTIVE_LOAD" # Only load if needed
- ux:
- description: "UX design (fallback - epics file should have relevant sections)"
- whole: "{planning_artifacts}/*ux*.md"
- sharded: "{planning_artifacts}/*ux*/*.md"
- load_strategy: "SELECTIVE_LOAD" # Only load if needed
- epics:
- description: "Enhanced epics+stories file with BDD and source hints"
- whole: "{planning_artifacts}/*epic*.md"
- sharded: "{planning_artifacts}/*epic*/*.md"
- load_strategy: "SELECTIVE_LOAD" # Only load needed epic
diff --git a/src/bmm/workflows/4-implementation/dev-story/workflow.md b/src/bmm/workflows/4-implementation/dev-story/workflow.md
new file mode 100644
index 000000000..c2200d398
--- /dev/null
+++ b/src/bmm/workflows/4-implementation/dev-story/workflow.md
@@ -0,0 +1,457 @@
+---
+name: dev-story
+description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"'
+---
+
+# Dev Story Workflow
+
+**Goal:** Execute story implementation following a context filled story spec file.
+
+**Your Role:** Developer implementing the story.
+- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+- Generate all documents in {document_output_language}
+- Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status
+- Execute ALL steps in exact order; do NOT skip steps
+- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.
+- Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.
+- User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/dev-story`
+- `validation` = `{installed_path}/checklist.md`
+- `story_file` = `` (explicit story path; auto-discovered if empty)
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+
+ Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+ Generate all documents in {document_output_language}
+ Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List,
+ Change Log, and Status
+ Execute ALL steps in exact order; do NOT skip steps
+ Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution
+ until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives
+ other instruction.
+ Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.
+ User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.
+
+
+
+ Use {{story_path}} directly
+ Read COMPLETE story file
+ Extract story_key from filename or metadata
+
+
+
+
+
+ MUST read COMPLETE sprint-status.yaml file from start to end to preserve order
+ Load the FULL file: {{sprint_status}}
+ Read ALL lines from beginning to end - do not skip any content
+ Parse the development_status section completely to understand story order
+
+ Find the FIRST story (by reading in order from top to bottom) where:
+ - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+ - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+ - Status value equals "ready-for-dev"
+
+
+
+
+ Choose option [1], [2], [3], or [4], or specify story file path:
+
+
+ HALT - Run create-story to create next story
+
+
+
+ HALT - Run validate-create-story to improve existing stories
+
+
+
+ Provide the story file path to develop:
+ Store user-provided story path as {{story_path}}
+
+
+
+
+
+ Display detailed sprint status analysis
+ HALT - User can review sprint status and provide story path
+
+
+
+ Store user-provided story path as {{story_path}}
+
+
+
+
+
+
+
+ Search {implementation_artifacts} for stories directly
+ Find stories with "ready-for-dev" status in files
+ Look for story files matching pattern: *-*-*.md
+ Read each candidate story file to check Status section
+
+
+
+ What would you like to do? Choose option [1], [2], or [3]:
+
+
+ HALT - Run create-story to create next story
+
+
+
+ HALT - Run validate-create-story to improve existing stories
+
+
+
+ It's unclear what story you want developed. Please provide the full path to the story file:
+ Store user-provided story path as {{story_path}}
+ Continue with provided story file
+
+
+
+
+ Use discovered story file and extract story_key
+
+
+
+ Store the found story_key (e.g., "1-2-user-authentication") for later status updates
+ Find matching story file in {implementation_artifacts} using story_key pattern: {{story_key}}.md
+ Read COMPLETE story file from discovered path
+
+
+
+ Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status
+
+ Load comprehensive context from story file's Dev Notes section
+ Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications
+ Use enhanced story context to inform implementation decisions and approaches
+
+ Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks
+
+
+ Completion sequence
+
+ HALT: "Cannot develop story without access to story file"
+ ASK user to clarify or HALT
+
+
+
+ Load all available context to inform implementation
+
+ Load {project_context} for coding standards and project-wide patterns (if exists)
+ Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status
+ Load comprehensive context from story file's Dev Notes section
+ Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications
+ Use enhanced story context to inform implementation decisions and approaches
+
+
+
+
+ Determine if this is a fresh start or continuation after code review
+
+ Check if "Senior Developer Review (AI)" section exists in the story file
+ Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks
+
+
+ Set review_continuation = true
+ Extract from "Senior Developer Review (AI)" section:
+ - Review outcome (Approve/Changes Requested/Blocked)
+ - Review date
+ - Total action items with checkboxes (count checked vs unchecked)
+ - Severity breakdown (High/Med/Low counts)
+
+ Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection
+ Store list of unchecked review items as {{pending_review_items}}
+
+
+
+
+
+ Set review_continuation = false
+ Set {{pending_review_items}} = empty
+
+
+
+
+
+
+
+ Load the FULL file: {{sprint_status}}
+ Read all development_status entries to find {{story_key}}
+ Get current status value for development_status[{{story_key}}]
+
+
+ Update the story in the sprint status report to = "in-progress"
+ Update last_updated field to current date
+
+
+
+
+
+
+
+
+
+
+
+ Store {{current_sprint_status}} for later use
+
+
+
+
+ Set {{current_sprint_status}} = "no-sprint-tracking"
+
+
+
+
+ FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION
+
+ Review the current task/subtask from the story file - this is your authoritative implementation guide
+ Plan implementation following red-green-refactor cycle
+
+
+ Write FAILING tests first for the task/subtask functionality
+ Confirm tests fail before implementation - this validates test correctness
+
+
+ Implement MINIMAL code to make tests pass
+ Run tests to confirm they now pass
+ Handle error conditions and edge cases as specified in task/subtask
+
+
+ Improve code structure while keeping tests green
+ Ensure code follows architecture patterns and coding standards from Dev Notes
+
+ Document technical approach and decisions in Dev Agent Record â Implementation Plan
+
+ HALT: "Additional dependencies need user approval"
+ HALT and request guidance
+ HALT: "Cannot proceed without necessary configuration files"
+
+ NEVER implement anything not mapped to a specific task/subtask in the story file
+ NEVER proceed to next task until current task/subtask is complete AND tests pass
+ Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition
+ Do NOT propose to pause for review until Step 9 completion gates are satisfied
+
+
+
+ Create unit tests for business logic and core functionality introduced/changed by the task
+ Add integration tests for component interactions specified in story requirements
+ Include end-to-end tests for critical user flows when story requirements demand them
+ Cover edge cases and error handling scenarios identified in story Dev Notes
+
+
+
+ Determine how to run tests for this repo (infer test framework from project structure)
+ Run all existing tests to ensure no regressions
+ Run the new tests to verify implementation correctness
+ Run linting and code quality checks if configured in project
+ Validate implementation meets ALL story acceptance criteria; enforce quantitative thresholds explicitly
+ STOP and fix before continuing - identify breaking changes immediately
+ STOP and fix before continuing - ensure implementation correctness
+
+
+
+ NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING
+
+
+ Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100%
+ Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features
+ Validate that ALL acceptance criteria related to this task are satisfied
+ Run full test suite to ensure NO regressions introduced
+
+
+
+ Extract review item details (severity, description, related AC/file)
+ Add to resolution tracking list: {{resolved_review_items}}
+
+
+ Mark task checkbox [x] in "Tasks/Subtasks â Review Follow-ups (AI)" section
+
+
+ Find matching action item in "Senior Developer Review (AI) â Action Items" section by matching description
+ Mark that action item checkbox [x] as resolved
+
+ Add to Dev Agent Record â Completion Notes: "â
Resolved review finding [{{severity}}]: {{description}}"
+
+
+
+
+ ONLY THEN mark the task (and subtasks) checkbox with [x]
+ Update File List section with ALL new, modified, or deleted files (paths relative to repo root)
+ Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested
+
+
+
+ DO NOT mark task complete - fix issues first
+ HALT if unable to fix validation failures
+
+
+
+ Count total resolved review items in this session
+ Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"
+
+
+ Save the story file
+ Determine if more incomplete tasks remain
+
+ Next task
+
+
+ Completion
+
+
+
+
+ Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)
+ Run the full regression suite (do not skip)
+ Confirm File List includes every changed file
+ Execute enhanced definition-of-done validation
+ Update the story Status to: "review"
+
+
+ Validate definition-of-done checklist with essential requirements:
+ - All tasks/subtasks marked complete with [x]
+ - Implementation satisfies every Acceptance Criterion
+ - Unit tests for core functionality added/updated
+ - Integration tests for component interactions added when required
+ - End-to-end tests for critical flows added when story demands them
+ - All tests pass (no regressions, new tests successful)
+ - Code quality checks pass (linting, static analysis if configured)
+ - File List includes every new/modified/deleted file (relative paths)
+ - Dev Agent Record contains implementation notes
+ - Change Log includes summary of changes
+ - Only permitted story sections were modified
+
+
+
+
+ Load the FULL file: {sprint_status}
+ Find development_status key matching {{story_key}}
+ Verify current status is "in-progress" (expected previous state)
+ Update development_status[{{story_key}}] = "review"
+ Update last_updated field to current date
+ Save file, preserving ALL comments and structure including STATUS DEFINITIONS
+
+
+
+
+
+
+
+
+
+
+
+
+ HALT - Complete remaining tasks before marking ready for review
+ HALT - Fix regression issues before completing
+ HALT - Update File List with all changed files
+ HALT - Address DoD failures before completing
+
+
+
+ Execute the enhanced definition-of-done checklist using the validation framework
+ Prepare a concise summary in Dev Agent Record â Completion Notes
+
+ Communicate to {user_name} that story implementation is complete and ready for review
+ Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified
+ Provide the story file path and current status (now "review")
+
+ Based on {user_skill_level}, ask if user needs any explanations about:
+ - What was implemented and how it works
+ - Why certain technical decisions were made
+ - How to test or verify the changes
+ - Any patterns, libraries, or approaches used
+ - Anything else they'd like clarified
+
+
+
+ Provide clear, contextual explanations tailored to {user_skill_level}
+ Use examples and references to specific code when helpful
+
+
+ Once explanations are complete (or user indicates no questions), suggest logical next steps
+ Recommended next steps (flexible based on project setup):
+ - Review the implemented story and test the changes
+ - Verify all acceptance criteria are met
+ - Ensure deployment readiness if applicable
+ - Run `code-review` workflow for peer review
+ - Optional: If Test Architect module installed, run `/bmad:tea:automate` to expand guardrail tests
+
+
+
+
+ Suggest checking {sprint_status} to see project progress
+
+ Remain flexible - allow user to choose their own path or ask for other assistance
+
+
+
diff --git a/src/bmm/workflows/4-implementation/dev-story/workflow.yaml b/src/bmm/workflows/4-implementation/dev-story/workflow.yaml
deleted file mode 100644
index b5ee9308a..000000000
--- a/src/bmm/workflows/4-implementation/dev-story/workflow.yaml
+++ /dev/null
@@ -1,20 +0,0 @@
-name: dev-story
-description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"'
-
-# Critical variables from config
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-user_name: "{config_source}:user_name"
-communication_language: "{config_source}:communication_language"
-user_skill_level: "{config_source}:user_skill_level"
-document_output_language: "{config_source}:document_output_language"
-date: system-generated
-
-# Workflow components
-installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story"
-instructions: "{installed_path}/instructions.xml"
-validation: "{installed_path}/checklist.md"
-
-story_file: "" # Explicit story path; auto-discovered if empty
-implementation_artifacts: "{config_source}:implementation_artifacts"
-sprint_status: "{implementation_artifacts}/sprint-status.yaml"
-project_context: "**/project-context.md"