Merge 7c498a9fbe into 36c21dbada

.augment/code_review_guidelines.yaml

@@ -56,7 +56,7 @@ areas:
       - "src/**/workflows/**"
     rules:
       - id: "workflow_entry_point_required"
-        description: "Every workflow folder must have workflow.yaml, workflow.md, or workflow.xml as entry point"
+        description: "Every workflow folder must have workflow.md (or workflow-*.md variant) as entry point"
         severity: "high"
 
       - id: "sharded_workflow_steps_folder"
@@ -64,7 +64,7 @@ areas:
         severity: "high"
 
       - id: "standard_workflow_instructions"
-        description: "Standard workflows using workflow.yaml must include instructions.md for execution guidance"
+        description: "Standard workflows using workflow.md should include instructions.md for execution guidance"
         severity: "medium"
 
       - id: "workflow_step_limit"
@@ -75,11 +75,10 @@ areas:
   # WORKFLOW ENTRY FILE RULES
   # ============================================
   workflow_definitions:
-    description: "Workflow entry files (workflow.yaml, workflow.md, workflow.xml)"
+    description: "Workflow entry files (workflow.md variants)"
     globs:
-      - "src/**/workflows/**/workflow.yaml"
       - "src/**/workflows/**/workflow.md"
-      - "src/**/workflows/**/workflow.xml"
+      - "src/**/workflows/**/workflow-*.md"
     rules:
       - id: "workflow_name_required"
         description: "Workflow entry files must define 'name' field in frontmatter or root element"

README.md

@@ -69,6 +69,15 @@ Products, platforms, complex features — structured planning then build:
 
 Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/).
 
+### Workflow Path Resolution
+
+BMad workflow/task files often reference placeholders such as `{project-root}` and installed paths like `{project-root}/_bmad/...`.
+
+- In installed projects, `{project-root}` resolves to the consuming repository root where BMAD is installed.
+- `_bmad/...` paths point to the installed BMAD runtime content in that repository.
+- In this source repository, equivalent source files typically live under `src/...`.
+- When a workflow must run directly from source (without install), use explicit `src/...` paths in that workflow step.
+
 ## Modules
 
 BMad Method extends with official modules for specialized domains. Modules are available during installation and can be added to your project at any time. After the V6 beta period these will also be available as Plugins and Granular Skills.

docs/how-to/customize-bmad.md

@@ -96,7 +96,7 @@ Add custom entries to the agent's display menu. Each item needs a `trigger`, a t
 ```yaml
 menu:
   - trigger: my-workflow
-    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
+    workflow: '{project-root}/my-custom/workflows/my-workflow.md'
     description: My custom workflow
   - trigger: deploy
     action: '#deploy-prompt'

docs/reference/commands.md

@@ -27,7 +27,7 @@ The installer uses templates for each command type:
 | Command type | What the generated file does |
 | --- | --- |
 | **Agent launcher** | Loads the agent persona file, activates its menu, and stays in character |
-| **Workflow command** | Loads the workflow engine (`workflow.xml`) and passes the workflow config |
+| **Workflow command** | Loads the workflow engine (`workflow.md`) and passes the workflow config |
 | **Task command** | Loads a standalone task file and follows its instructions |
 | **Tool command** | Loads a standalone tool file and follows its instructions |
 

docs/tutorials/getting-started.md

@@ -65,11 +65,7 @@ The installer creates two folders:
 - `_bmad/` — agents, workflows, tasks, and configuration
 - `_bmad-output/` — empty for now, but this is where your artifacts will be saved
 
-Open your AI IDE in the project folder. Run the `help` workflow (`/bmad-help`) to see what to do next — it detects what you've completed and recommends the next step.
-
-:::note[How to Load Agents and Run Workflows]
-Each workflow has a **slash command** you run in your IDE (e.g., `/bmad-bmm-create-prd`). Running a workflow command automatically loads the appropriate agent — you don't need to load agents separately. You can also load an agent directly for general conversation (e.g., `/bmad-agent-bmm-pm` for the PM agent).
-:::
+Open your AI IDE in the project folder. Run the `help` workflow (`bmad-help` on most platforms) to see what to do next — it detects what you've completed and recommends the next step.
 
 :::caution[Fresh Chats]
 Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
@@ -82,29 +78,29 @@ Work through phases 1-3. **Use fresh chats for each workflow.**
 ### Phase 1: Analysis (Optional)
 
 All workflows in this phase are optional:
-- **brainstorming** (`/bmad-brainstorming`) — Guided ideation
-- **research** (`/bmad-bmm-research`) — Market and technical research
-- **create-product-brief** (`/bmad-bmm-create-product-brief`) — Recommended foundation document
+- **brainstorming** (`bmad-bmm-brainstorming`) — Guided ideation
+- **research** (`bmad-bmm-research`) — Market and technical research
+- **create-product-brief** (`bmad-bmm-create-product-brief`) — Recommended foundation document
 
 ### Phase 2: Planning (Required)
 
 **For BMad Method and Enterprise tracks:**
-1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat
-2. Run the `prd` workflow (`/bmad-bmm-create-prd`)
+1. Load the **PM agent** in a new chat
+2. Run the `create-prd` workflow (`bmad-bmm-create-prd`)
 3. Output: `PRD.md`
 
 **For Quick Flow track:**
-- Use the `quick-spec` workflow (`/bmad-bmm-quick-spec`) instead of PRD, then skip to implementation
+- Use the `quick-spec` workflow instead of PRD, then skip to implementation
 
 :::note[UX Design (Optional)]
-If your project has a user interface, load the **UX-Designer agent** (`/bmad-agent-bmm-ux-designer`) and run the UX design workflow (`/bmad-bmm-create-ux-design`) after creating your PRD.
+If your project has a user interface, load the **UX-Designer agent** and run the UX design workflow after creating your PRD.
 :::
 
 ### Phase 3: Solutioning (BMad Method/Enterprise)
 
 **Create Architecture**
-1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat
-2. Run `create-architecture` (`/bmad-bmm-create-architecture`)
+1. Load the **Architect agent** in a new chat
+2. Run `create-architecture` (`bmad-bmm-create-architecture`)
 3. Output: Architecture document with technical decisions
 
 **Create Epics and Stories**
@@ -113,13 +109,13 @@ If your project has a user interface, load the **UX-Designer agent** (`/bmad-age
 Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
 :::
 
-1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat
-2. Run `create-epics-and-stories` (`/bmad-bmm-create-epics-and-stories`)
+1. Load the **PM agent** in a new chat
+2. Run `create-epics-and-stories` (`bmad-bmm-create-epics-and-stories`)
 3. The workflow uses both PRD and Architecture to create technically-informed stories
 
 **Implementation Readiness Check** *(Highly Recommended)*
-1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat
-2. Run `check-implementation-readiness` (`/bmad-bmm-check-implementation-readiness`)
+1. Load the **Architect agent** in a new chat
+2. Run `check-implementation-readiness` (`bmad-bmm-check-implementation-readiness`)
 3. Validates cohesion across all planning documents
 
 ## Step 2: Build Your Project
@@ -128,19 +124,19 @@ Once planning is complete, move to implementation. **Each workflow should run in
 
 ### Initialize Sprint Planning
 
-Load the **SM agent** (`/bmad-agent-bmm-sm`) and run `sprint-planning` (`/bmad-bmm-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
+Load the **SM agent** and run `sprint-planning` (`bmad-bmm-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
 
 ### The Build Cycle
 
 For each story, repeat this cycle with fresh chats:
 
-| Step | Agent | Workflow       | Command                    | Purpose                            |
-| ---- | ----- | -------------- | -------------------------- | ---------------------------------- |
-| 1    | SM    | `create-story` | `/bmad-bmm-create-story`  | Create story file from epic        |
-| 2    | DEV   | `dev-story`    | `/bmad-bmm-dev-story`     | Implement the story                |
-| 3    | DEV   | `code-review`  | `/bmad-bmm-code-review`   | Quality validation *(recommended)* |
+| Step | Agent | Workflow       | Purpose                            |
+| ---- | ----- | -------------- | ---------------------------------- |
+| 1    | SM    | `create-story` (`bmad-bmm-create-story`) | Create story file from epic        |
+| 2    | DEV   | `dev-story` (`bmad-bmm-dev-story`) | Implement the story                |
+| 3    | DEV   | `code-review` (`bmad-bmm-code-review`) | Quality validation *(recommended)* |
 
-After completing all stories in an epic, load the **SM agent** (`/bmad-agent-bmm-sm`) and run `retrospective` (`/bmad-bmm-retrospective`).
+After completing all stories in an epic, load the **SM agent** and run `retrospective` (`bmad-bmm-retrospective`).
 
 ## What You've Accomplished
 
@@ -166,17 +162,17 @@ your-project/
 
 ## Quick Reference
 
-| Workflow                         | Command                                    | Agent     | Purpose                              |
-| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ |
-| `help`                           | `/bmad-help`                               | Any       | Get guidance on what to do next      |
-| `prd`                            | `/bmad-bmm-create-prd`                     | PM        | Create Product Requirements Document |
-| `create-architecture`            | `/bmad-bmm-create-architecture`            | Architect | Create architecture document         |
-| `create-epics-and-stories`       | `/bmad-bmm-create-epics-and-stories`       | PM        | Break down PRD into epics            |
-| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion           |
-| `sprint-planning`                | `/bmad-bmm-sprint-planning`                | SM        | Initialize sprint tracking           |
-| `create-story`                   | `/bmad-bmm-create-story`                   | SM        | Create a story file                  |
-| `dev-story`                      | `/bmad-bmm-dev-story`                      | DEV       | Implement a story                    |
-| `code-review`                    | `/bmad-bmm-code-review`                    | DEV       | Review implemented code              |
+| Workflow                         | Slash Command                         | Agent     | Purpose                              |
+| -------------------------------- | ------------------------------------- | --------- | ------------------------------------ |
+| `help`                           | `bmad-help`                           | Any       | Get guidance on what to do next      |
+| `create-prd`                     | `bmad-bmm-create-prd`                | PM        | Create Product Requirements Document |
+| `create-architecture`            | `bmad-bmm-create-architecture`       | Architect | Create architecture document         |
+| `create-epics-and-stories`       | `bmad-bmm-create-epics-and-stories`  | PM        | Break down PRD into epics            |
+| `check-implementation-readiness` | `bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion           |
+| `sprint-planning`                | `bmad-bmm-sprint-planning`           | SM        | Initialize sprint tracking           |
+| `create-story`                   | `bmad-bmm-create-story`              | SM        | Create a story file                  |
+| `dev-story`                      | `bmad-bmm-dev-story`                 | DEV       | Implement a story                    |
+| `code-review`                    | `bmad-bmm-code-review`               | DEV       | Review implemented code              |
 
 ## Common Questions
 
@@ -184,10 +180,10 @@ your-project/
 Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
 
 **Can I change my plan later?**
-Yes. The SM agent has a `correct-course` workflow (`/bmad-bmm-correct-course`) for handling scope changes.
+Yes. The SM agent has a `correct-course` workflow for handling scope changes.
 
 **What if I want to brainstorm first?**
-Load the Analyst agent (`/bmad-agent-bmm-analyst`) and run `brainstorming` (`/bmad-brainstorming`) before starting your PRD.
+Load the Analyst agent and run `brainstorming` (`bmad-bmm-brainstorming`) before starting your PRD.
 
 **Do I need to follow a strict order?**
 Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
@@ -196,14 +192,14 @@ Not strictly. Once you learn the flow, you can run workflows directly using the
 
 - **During workflows** — Agents guide you with questions and explanations
 - **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
-- **Stuck?** — Run `help` (`/bmad-help`) to see what to do next
+- **Stuck?** — Run `help` (`bmad-help` on most platforms) to see what to do next
 
 ## Key Takeaways
 
 :::tip[Remember These]
 - **Always use fresh chats** — Start a new chat for each workflow
 - **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture
-- **Use `help` (`/bmad-help`) when stuck** — It detects your progress and suggests next steps
+- **Use `help` when stuck** — It detects your progress and suggests next steps
 :::
 
 Ready to start? Install BMad and let the agents guide you through your first project.

src/bmm/agents/analyst.agent.yaml

@@ -39,5 +39,5 @@ agent:
       description: "[CB] Create Brief: A guided experience to nail down your product idea into an executive brief"
 
     - trigger: DP or fuzzy match on document-project
-      workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md"
       description: "[DP] Document Project: Analyze an existing project to produce useful documentation for both human and LLM"

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"

src/bmm/agents/pm.agent.yaml

@@ -40,5 +40,5 @@ agent:
       description: "[IR] Implementation Readiness: Ensure the PRD, UX, and Architecture and Epics and Stories List are all aligned"
 
     - trigger: CC or fuzzy match on correct-course
-      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md"
       description: "[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation"

src/bmm/agents/qa.agent.yaml

@@ -29,7 +29,7 @@ agent:
 
   menu:
     - trigger: QA or fuzzy match on qa-automate
-      workflow: "{project-root}/_bmad/bmm/workflows/qa/automate/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/qa/automate/workflow.md"
       description: "[QA] Automate - Generate tests for existing features (simplified)"
 
   prompts:

src/bmm/agents/quick-flow-solo-dev.agent.yaml

@@ -28,5 +28,5 @@ agent:
       description: "[QD] Quick-flow Develop: Implement a story tech spec end-to-end (Core of Quick Flow)"
 
     - 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"

src/bmm/agents/sm.agent.yaml

@@ -20,18 +20,18 @@ agent:
 
   menu:
     - trigger: SP or fuzzy match on sprint-planning
-      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md"
       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
-      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.md"
       data: "{project-root}/_bmad/_config/agent-manifest.csv"
       description: "[ER] Epic Retrospective: Party Mode review of all work completed across an epic."
 
     - trigger: CC or fuzzy match on correct-course
-      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md"
       description: "[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation"

src/bmm/agents/tech-writer/tech-writer.agent.yaml

@@ -22,7 +22,7 @@ agent:
 
   menu:
     - trigger: DP or fuzzy match on document-project
-      workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md"
       description: "[DP] Document Project: Generate comprehensive project documentation (brownfield analysis, architecture scanning)"
 
     - trigger: WD or fuzzy match on write-document

src/bmm/module-help.csv

@@ -1,9 +1,9 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
-bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.yaml,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*,
+bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.md,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*,
 bmm,anytime,Generate Project Context,GPC,,_bmad/bmm/workflows/generate-project-context/workflow.md,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context",
 bmm,anytime,Quick Spec,QS,,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps brownfield additions to well established patterns utilities without extensive planning",planning_artifacts,"tech spec",
 bmm,anytime,Quick Dev,QD,,_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,,
-bmm,anytime,Correct Course,CC,,_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal",
+bmm,anytime,Correct Course,CC,,_bmad/bmm/workflows/4-implementation/correct-course/workflow.md,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal",
 bmm,anytime,Write Document,WD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Describe in detail what you want, and the agent will follow the documentation best practices defined in agent memory. Multi-turn conversation with subprocess for research/review.",project-knowledge,"document",
 bmm,anytime,Update Standards,US,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.",_bmad/_memory/tech-writer-sidecar,"standards",
 bmm,anytime,Mermaid Generate,MG,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.",planning_artifacts,"mermaid diagram",
@@ -21,11 +21,11 @@ bmm,2-planning,Create UX,CU,30,_bmad/bmm/workflows/2-plan-workflows/create-ux-de
 bmm,3-solutioning,Create Architecture,CA,10,_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md,bmad-bmm-create-architecture,true,architect,Create Mode,"Guided Workflow to document technical decisions",planning_artifacts,architecture,
 bmm,3-solutioning,Create Epics and Stories,CE,30,_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md,bmad-bmm-create-epics-and-stories,true,pm,Create Mode,"Create the Epics and Stories Listing",planning_artifacts,"epics and stories",
 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.yaml,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.yaml,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,QA Automation Test,QA,45,_bmad/bmm/workflows/qa/automate/workflow.yaml,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.yaml,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,
+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.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/automate/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,

src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md

@@ -7,7 +7,7 @@ nextStepFile: './step-03-users.md'
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md

@@ -7,7 +7,7 @@ nextStepFile: './step-04-metrics.md'
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md

@@ -7,7 +7,7 @@ nextStepFile: './step-05-scope.md'
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md

@@ -7,7 +7,7 @@ nextStepFile: './step-06-complete.md'
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md

@@ -11,7 +11,7 @@ projectTypesCSV: '../data/project-types.csv'
 domainComplexityCSV: '../data/domain-complexity.csv'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md

@@ -7,7 +7,7 @@ nextStepFile: './step-04-journeys.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md

@@ -7,7 +7,7 @@ nextStepFile: './step-05-domain.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 domainComplexityCSV: '../data/domain-complexity.csv'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md

@@ -10,7 +10,7 @@ outputFile: '{planning_artifacts}/prd.md'
 projectTypesCSV: '../data/project-types.csv'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md

@@ -10,7 +10,7 @@ outputFile: '{planning_artifacts}/prd.md'
 projectTypesCSV: '../data/project-types.csv'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md

@@ -7,7 +7,7 @@ nextStepFile: './step-09-functional.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md

@@ -7,7 +7,7 @@ nextStepFile: './step-10-nonfunctional.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md

@@ -7,7 +7,7 @@ nextStepFile: './step-11-polish.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 purposeFile: '../data/prd-purpose.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md

@@ -5,7 +5,7 @@ description: 'Discovery & Understanding - Understand what user wants to edit and
 # File references (ONLY variables used in this step)
 altStepFile: './step-e-01b-legacy-conversion.md'
 prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md

@@ -7,7 +7,7 @@ nextStepFile: './step-e-03-edit.md'
 prdFile: '{prd_file_path}'
 validationReport: '{validation_report_path}'  # If provided
 prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 ---
 
 # Step E-2: Deep Review & Analysis

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md

@@ -4,7 +4,7 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio
 
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-02-format-detection.md'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 prdPurpose: '../data/prd-purpose.md'
 ---

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md

@@ -6,7 +6,7 @@ description: 'SMART Requirements Validation - Validate Functional Requirements m
 nextStepFile: './step-v-11-holistic-quality-validation.md'
 prdFile: '{prd_file_path}'
 validationReportPath: '{validation_report_path}'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 ---
 
 # Step 10: SMART Requirements Validation

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md

@@ -6,7 +6,7 @@ description: 'Holistic Quality Assessment - Assess PRD as cohesive, compelling d
 nextStepFile: './step-v-12-completeness-validation.md'
 prdFile: '{prd_file_path}'
 validationReportPath: '{validation_report_path}'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 ---
 
 # Step 11: Holistic Quality Assessment

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -161,7 +161,7 @@ Show the generated core experience content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current core experience content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current core experience content
 - Process the enhanced experience insights that come back
 - Ask user: "Accept these improvements to the core experience definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -164,7 +164,7 @@ Show the generated emotional response content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current emotional response content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current emotional response content
 - Process the enhanced emotional insights that come back
 - Ask user: "Accept these improvements to the emotional response definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -179,7 +179,7 @@ Show the generated inspiration analysis content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current inspiration analysis content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current inspiration analysis content
 - Process the enhanced pattern insights that come back
 - Ask user: "Accept these improvements to the inspiration analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -197,7 +197,7 @@ Show the generated design system content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current design system content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current design system content
 - Process the enhanced design system insights that come back
 - Ask user: "Accept these improvements to the design system decision? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -199,7 +199,7 @@ Show the generated defining experience content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current defining experience content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current defining experience content
 - Process the enhanced experience insights that come back
 - Ask user: "Accept these improvements to the defining experience? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -169,7 +169,7 @@ Show the generated visual foundation content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current visual foundation content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current visual foundation content
 - Process the enhanced visual insights that come back
 - Ask user: "Accept these improvements to the visual foundation? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -169,7 +169,7 @@ Show the generated design direction content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current design direction content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current design direction content
 - Process the enhanced design insights that come back
 - Ask user: "Accept these improvements to the design direction? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -187,7 +187,7 @@ Show the generated user journey content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current user journey content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current user journey content
 - Process the enhanced journey insights that come back
 - Ask user: "Accept these improvements to the user journeys? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -193,7 +193,7 @@ Show the generated component strategy content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current component strategy content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current component strategy content
 - Process the enhanced component insights that come back
 - Ask user: "Accept these improvements to the component strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -182,7 +182,7 @@ Show the generated UX patterns content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current UX patterns content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current UX patterns content
 - Process the enhanced pattern insights that come back
 - Ask user: "Accept these improvements to the UX patterns? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md

@@ -30,7 +30,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
@@ -209,7 +209,7 @@ Show the generated responsive and accessibility content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current responsive/accessibility content
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current responsive/accessibility content
 - Process the enhanced insights that come back
 - Ask user: "Accept these improvements to the responsive/accessibility strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
@@ -170,7 +170,7 @@ Show the generated content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current context analysis
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current context analysis
 - Process the enhanced architectural insights that come back
 - Ask user: "Accept these enhancements to the project context analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
@@ -277,7 +277,7 @@ Show the generated content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current starter analysis
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with current starter analysis
 - Process enhanced insights about starter options or custom approaches
 - Ask user: "Accept these changes to the starter template evaluation? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md

@@ -15,9 +15,9 @@
 
 ## EXECUTION PROTOCOLS:
 
-- 🎯 Show your analysis before taking any action
+- 🎯 Provide a brief rationale before taking any action
 - 🌐 Search the web to verify technology versions and options
-- ⚠️ Present A/P/C menu after each major decision category
+- ⚠️ Present A/P/C menu after drafting decision content (and when user requests refinement)
 - 💾 ONLY save when user chooses C (Continue)
 - 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
 - 🚫 FORBIDDEN to load next step until C is selected
@@ -32,7 +32,7 @@ This step will generate content and present choices for each decision category:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
@@ -44,7 +44,7 @@ This step will generate content and present choices for each decision category:
 - Project context file may contain technical preferences and rules
 - Technical preferences discovered in step 3 are available
 - Focus on decisions not already made by starter template or existing preferences
-- Collaborative decision making, not recommendations
+- Collaborative decision making first; recommendations are allowed only with explicit rationale and user confirmation
 
 ## YOUR TASK:
 
@@ -58,7 +58,7 @@ Facilitate collaborative architectural decision making, leveraging existing tech
 "Based on our technical preferences discussion in step 3, let's build on those foundations:
 
 **Your Technical Preferences:**
-{{user_technical_preferences_from_step_3}}
+{{user_technical_preferences}}
 
 **Starter Template Decisions:**
 {{starter_template_decisions}}
@@ -72,7 +72,7 @@ Based on technical preferences, starter template choice, and project context, id
 **Already Decided (Don't re-decide these):**
 
 - {{starter_template_decisions}}
-- {{user_technology_preferences}}
+- {{user_technical_preferences}}
 - {{project_context_technical_rules}}
 
 **Critical Decisions:** Must be decided before implementation can proceed
@@ -165,7 +165,7 @@ If decision involves specific technology:
 
 ```
 Search the web: "{{technology}} latest stable version"
-Search the web: "{{technology}} current LTS version"
+Search the web: "{{technology}} current LTS version" (only if the technology publishes an LTS track)
 Search the web: "{{technology}} production readiness"
 ```
 
@@ -264,7 +264,7 @@ Show the generated decisions content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with specific decision categories
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with specific decision categories
 - Process enhanced insights about particular decisions
 - Ask user: "Accept these enhancements to the architectural decisions? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md

@@ -32,7 +32,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
@@ -305,7 +305,7 @@ Show the generated patterns content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current patterns
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with current patterns
 - Process enhanced consistency rules that come back
 - Ask user: "Accept these additional pattern refinements? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md

@@ -32,7 +32,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
@@ -325,7 +325,7 @@ Show the generated project structure content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current project structure
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with current project structure
 - Process enhanced organizational insights that come back
 - Ask user: "Accept these changes to the project structure? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md

@@ -32,7 +32,7 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
+- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
 - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
@@ -305,7 +305,7 @@ Show the validation results and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with validation issues
+- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with validation issues
 - Process enhanced solutions for complex concerns
 - Ask user: "Accept these architectural improvements? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/workflow.md

@@ -36,7 +36,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ### Paths
 
-- `installed_path` = `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture`
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture`
 - `template_path` = `{installed_path}/architecture-decision-template.md`
 - `data_files_path` = `{installed_path}/data/`
 

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md

@@ -13,11 +13,8 @@ outputFile: '{planning_artifacts}/epics.md'
 epicsTemplate: '{workflow_path}/templates/epics-template.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
-
-# Template References
-epicsTemplate: '{workflow_path}/templates/epics-template.md'
 ---
 
 # Step 1: Validate Prerequisites and Extract Requirements
@@ -91,11 +88,18 @@ Search for required documents using these patterns (sharded means a large docume
 1. `{planning_artifacts}/*ux*.md` (whole document)
 2. `{planning_artifacts}/*ux*/index.md` (sharded version)
 
+**Deterministic Selection Rules (required):**
+
+- When multiple files match the same priority level, prefer exact filename matches (`prd.md`, `architecture.md`, `ux-design.md`) before wildcard matches.
+- If multiple wildcard matches remain, prefer files under `{planning_artifacts}` root before nested paths.
+- If ambiguity still remains, present candidates to the user and require explicit selection before extraction.
+- Record the final selected files in `inputDocuments` frontmatter to keep downstream steps deterministic.
+
 Before proceeding, Ask the user if there are any other documents to include for analysis, and if anything found should be excluded. Wait for user confirmation. Once confirmed, create the {outputFile} from the {epicsTemplate} and in the front matter list the files in the array of `inputDocuments: []`.
 
 ### 3. Extract Functional Requirements (FRs)
 
-From the PRD document (full or sharded), read then entire document and extract ALL functional requirements:
+From the PRD document (full or sharded), read the entire document and extract ALL functional requirements:
 
 **Extraction Method:**
 

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md

@@ -12,7 +12,7 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 
 # Template References

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md

@@ -12,7 +12,7 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 
 # Template References

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md

@@ -11,7 +11,7 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 
 # Template References

src/bmm/workflows/4-implementation/code-review/instructions.xml

@@ -1,227 +0,0 @@
-<workflow>
-  <critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml</critical>
-  <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-  <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
-  <critical>Generate all documents in {document_output_language}</critical>
-
-  <critical>🔥 YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! 🔥</critical>
-  <critical>Your purpose: Validate story file claims against actual implementation</critical>
-  <critical>Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?</critical>
-  <critical>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</critical>
-  <critical>Read EVERY file in the File List - verify implementation against story requirements</critical>
-  <critical>Tasks marked complete but not done = CRITICAL finding</critical>
-  <critical>Acceptance Criteria not implemented = HIGH severity finding</critical>
-  <critical>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/</critical>
-
-
-  <step n="1" goal="Load story and discover changes">
-    <action>Use provided {{story_path}} or ask user which story file to review</action>
-    <action>Read COMPLETE story file</action>
-    <action>Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story
-      metadata</action>
-    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log</action>
-
-    <!-- Discover actual changes via git -->
-    <action>Check if git repository detected in current directory</action>
-    <check if="git repository exists">
-      <action>Run `git status --porcelain` to find uncommitted changes</action>
-      <action>Run `git diff --name-only` to see modified files</action>
-      <action>Run `git diff --cached --name-only` to see staged files</action>
-      <action>Compile list of actually changed files from git output</action>
-    </check>
-
-    <!-- Cross-reference story File List vs git reality -->
-    <action>Compare story's Dev Agent Record → File List with actual git changes</action>
-    <action>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
-    </action>
-
-    <invoke-protocol name="discover_inputs" />
-    <action>Load {project_context} for coding standards (if exists)</action>
-  </step>
-
-  <step n="2" goal="Build review attack plan">
-    <action>Extract ALL Acceptance Criteria from story</action>
-    <action>Extract ALL Tasks/Subtasks with completion status ([x] vs [ ])</action>
-    <action>From Dev Agent Record → File List, compile list of claimed changes</action>
-
-    <action>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
-    </action>
-  </step>
-
-  <step n="3" goal="Execute adversarial review">
-    <critical>VALIDATE EVERY CLAIM - Check git reality vs story claims</critical>
-
-    <!-- Git vs Story Discrepancies -->
-    <action>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)
-    </action>
-
-    <!-- Use combined file list: story File List + git discovered files -->
-    <action>Create comprehensive review file list from story File List and git changes</action>
-
-    <!-- AC Validation -->
-    <action>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
-    </action>
-
-    <!-- Task Completion Audit -->
-    <action>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)
-    </action>
-
-    <!-- Code Quality Deep Dive -->
-    <action>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?
-    </action>
-
-    <check if="total_issues_found lt 3">
-      <critical>NOT LOOKING HARD ENOUGH - Find more problems!</critical>
-      <action>Re-examine code for:
-        - Edge cases and null handling
-        - Architecture violations
-        - Documentation gaps
-        - Integration issues
-        - Dependency problems
-        - Git commit message quality (if applicable)
-      </action>
-      <action>Find at least 3 more specific, actionable issues</action>
-    </check>
-  </step>
-
-  <step n="4" goal="Present findings and fix them">
-    <action>Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)</action>
-    <action>Set {{fixed_count}} = 0</action>
-    <action>Set {{action_count}} = 0</action>
-
-    <output>**🔥 CODE REVIEW FINDINGS, {user_name}!**
-
-      **Story:** {{story_file}}
-      **Git vs Story Discrepancies:** {{git_discrepancy_count}} found
-      **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low
-
-      ## 🔴 CRITICAL ISSUES
-      - Tasks marked [x] but not actually implemented
-      - Acceptance Criteria not implemented
-      - Story claims files changed but no git evidence
-      - Security vulnerabilities
-
-      ## 🟡 MEDIUM ISSUES
-      - Files changed but not documented in story File List
-      - Uncommitted changes not tracked
-      - Performance problems
-      - Poor test coverage/quality
-      - Code maintainability issues
-
-      ## 🟢 LOW ISSUES
-      - Code style improvements
-      - Documentation gaps
-      - Git commit message quality
-    </output>
-
-    <ask>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:</ask>
-
-    <check if="user chooses 1">
-      <action>Fix all HIGH and MEDIUM issues in the code</action>
-      <action>Add/update tests as needed</action>
-      <action>Update File List in story if files changed</action>
-      <action>Update story Dev Agent Record with fixes applied</action>
-      <action>Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed</action>
-      <action>Set {{action_count}} = 0</action>
-    </check>
-
-    <check if="user chooses 2">
-      <action>Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks</action>
-      <action>For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`</action>
-      <action>Set {{action_count}} = number of action items created</action>
-      <action>Set {{fixed_count}} = 0</action>
-    </check>
-
-    <check if="user chooses 3">
-      <action>Show detailed explanation with code examples</action>
-      <action>Return to fix decision</action>
-    </check>
-  </step>
-
-  <step n="5" goal="Update story status and sync sprint tracking">
-    <!-- Determine new status based on review outcome -->
-    <check if="all HIGH and MEDIUM issues fixed AND all ACs implemented">
-      <action>Set {{new_status}} = "done"</action>
-      <action>Update story Status field to "done"</action>
-    </check>
-    <check if="HIGH or MEDIUM issues remain OR ACs not fully implemented">
-      <action>Set {{new_status}} = "in-progress"</action>
-      <action>Update story Status field to "in-progress"</action>
-    </check>
-    <action>Save story file</action>
-
-    <!-- Determine sprint tracking status -->
-    <check if="{sprint_status} file exists">
-      <action>Set {{current_sprint_status}} = "enabled"</action>
-    </check>
-    <check if="{sprint_status} file does NOT exist">
-      <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
-    </check>
-
-    <!-- Sync sprint-status.yaml when story status changes (only if sprint tracking enabled) -->
-    <check if="{{current_sprint_status}} != 'no-sprint-tracking'">
-      <action>Load the FULL file: {sprint_status}</action>
-      <action>Find development_status key matching {{story_key}}</action>
-
-      <check if="{{new_status}} == 'done'">
-        <action>Update development_status[{{story_key}}] = "done"</action>
-        <action>Save file, preserving ALL comments and structure</action>
-        <output>✅ Sprint status synced: {{story_key}} → done</output>
-      </check>
-
-      <check if="{{new_status}} == 'in-progress'">
-        <action>Update development_status[{{story_key}}] = "in-progress"</action>
-        <action>Save file, preserving ALL comments and structure</action>
-        <output>🔄 Sprint status synced: {{story_key}} → in-progress</output>
-      </check>
-
-      <check if="story key not found in sprint status">
-        <output>⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml</output>
-      </check>
-    </check>
-
-    <check if="{{current_sprint_status}} == 'no-sprint-tracking'">
-      <output>ℹ️ Story status updated (no sprint tracking configured)</output>
-    </check>
-
-    <output>**✅ Review Complete!**
-
-      **Story Status:** {{new_status}}
-      **Issues Fixed:** {{fixed_count}}
-      **Action Items Created:** {{action_count}}
-
-      {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}}
-    </output>
-  </step>
-
-</workflow>

src/bmm/workflows/4-implementation/code-review/steps/step-01-load-story-and-changes.md

@@ -0,0 +1,36 @@
+---
+name: 'step-01-load-story-and-changes'
+description: 'Load target story, gather git deltas, and establish review scope'
+nextStepFile: './step-02-build-attack-plan.md'
+---
+
+  <step n="1" goal="Load story and discover changes">
+    <action>Use provided {{story_path}} or ask user which story file to review</action>
+    <action>Read COMPLETE story file</action>
+    <action>Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story
+      metadata</action>
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log</action>
+
+    <!-- Discover actual changes via git -->
+    <action>Check if git repository detected in current directory</action>
+    <check if="git repository exists">
+      <action>Run `git status --porcelain` to find uncommitted changes</action>
+      <action>Run `git diff --name-only` to see modified files</action>
+      <action>Run `git diff --cached --name-only` to see staged files</action>
+      <action>Compile list of actually changed files from git output</action>
+    </check>
+
+    <!-- Cross-reference story File List vs git reality -->
+    <action>Compare story's Dev Agent Record → File List with actual git changes</action>
+    <action>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
+    </action>
+
+    <invoke-protocol name="discover_inputs" />
+    <action>Load {project_context} for coding standards (if exists)</action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-02-build-attack-plan.md`.

src/bmm/workflows/4-implementation/code-review/steps/step-02-build-attack-plan.md

@@ -0,0 +1,21 @@
+---
+name: 'step-02-build-attack-plan'
+description: 'Build an explicit adversarial review plan against ACs and completed tasks'
+nextStepFile: './step-03-execute-review.md'
+---
+
+  <step n="2" goal="Build review attack plan">
+    <action>Extract ALL Acceptance Criteria from story</action>
+    <action>Extract ALL Tasks/Subtasks with completion status ([x] vs [ ])</action>
+    <action>From Dev Agent Record → File List, compile list of claimed changes</action>
+
+    <action>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 assertions and meaningful coverage
+    </action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-03-execute-review.md`.

src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md

@@ -0,0 +1,158 @@
+---
+name: 'step-03-execute-review'
+description: 'Execute full adversarial review and record actionable findings'
+nextStepFile: './step-04-present-and-resolve.md'
+reviewFindingsFile: '{story_dir}/review-findings.json'
+---
+
+  <step n="3" goal="Execute adversarial review">
+    <critical>VALIDATE EVERY CLAIM - Check git reality vs story claims</critical>
+    <critical>Every issue MUST be captured using the structured findings contract below</critical>
+
+    <action>Initialize findings artifacts:
+      - Set {{review_findings}} = [] (in-memory array)
+      - Set {{review_findings_file}} = {reviewFindingsFile}
+      - Set {{review_findings_schema}} = "id,severity,type,summary,detail,file_line,proof,suggested_fix,reviewer,timestamp"
+      - Each finding record MUST contain:
+        id, severity, type, summary, detail, file_line, proof, suggested_fix, reviewer, timestamp
+      - `file_line` is the required `file:line` locator field and MUST use `path/to/file:line` format
+      - `reviewer` value MUST be `senior-dev-review`
+      - `timestamp` MUST use system ISO datetime
+    </action>
+
+    <!-- Git vs Story Discrepancies -->
+    <action>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)
+      For every discrepancy, append a finding object to {{review_findings}}.
+    </action>
+
+    <!-- Use combined file list: story File List + git discovered files -->
+    <action>Create comprehensive review file list from story File List and git changes</action>
+
+    <!-- AC Validation -->
+    <action>For EACH Acceptance Criterion:
+      1. Read the AC requirement
+      2. Search implementation files for evidence
+      3. Determine: IMPLEMENTED, PARTIAL, or MISSING using this algorithm:
+        - Parse each AC into explicit clauses (single requirement statements).
+        - Evaluate each clause independently, then derive overall AC status from clause outcomes.
+        - IMPLEMENTED:
+          - EVERY clause has direct code evidence tied to the story execution path, and
+          - Evidence includes at least one strong corroborator for AC behavior (automated test, integration test, or reproducible runtime proof), and
+          - Weak evidence (docs/comments/README) is only supplemental.
+        - PARTIAL:
+          - One or more clauses have direct evidence, but at least one clause lacks direct evidence, OR
+          - Coverage is only indirect (helper/generic utility not proven wired), OR
+          - Evidence is mostly weak and not corroborated by code/tests.
+        - MISSING:
+          - No clause has credible direct implementation evidence, and
+          - No test/runtime proof demonstrates AC behavior.
+      4. Evidence-type rules:
+        - Strong evidence: implementation code plus validating tests/runtime proof.
+        - Medium evidence: implementation code without validating tests.
+        - Weak evidence: comments, README/docs, design notes, screenshots, or unverifiable logs.
+        - Weak evidence alone cannot qualify an AC as IMPLEMENTED.
+      5. Indirect evidence rules:
+        - Helper functions/utilities count as indirect until explicit call sites or integration coverage prove the AC path.
+        - Generic capability not wired to this story remains PARTIAL.
+      6. Severity mapping for AC gaps:
+        - MISSING + security/data-loss/compliance/core user flow risk -> HIGH.
+        - MISSING + non-core behavior or secondary UX/documentation requirement -> MEDIUM.
+        - PARTIAL + security/data-integrity/compliance risk -> HIGH.
+        - PARTIAL + degraded core behavior -> MEDIUM.
+        - PARTIAL + optional/non-critical behavior gap with safe fallback -> LOW.
+      7. Classification examples:
+        - IMPLEMENTED example: AC requires validation + error response, and code path plus passing test covers all clauses.
+        - PARTIAL example: helper exists and one clause passes, but integration path for another clause is unproven.
+        - MISSING example: AC text exists, but no matching code path or tests are found.
+      8. If AC is PARTIAL or MISSING, append a finding object to {{review_findings}} with status, severity, and clause-level proof.
+    </action>
+
+    <action>When creating findings from any action above, populate fields using this mapping:
+      - id:
+        - Git discrepancy: `GIT-DIFF-{{index}}`
+        - AC gap: `AC-{{ac_id}}-{{status}}-{{index}}`
+        - Task mismatch: `TASK-{{task_id}}-MISMATCH-{{index}}`
+        - Code-quality issue: `CQ-{{category}}-{{index}}`
+      - severity:
+        - Use explicit severity rule from the originating action block
+      - type:
+        - `story-sync` for git/story discrepancies
+        - `acceptance-criteria` for AC gaps
+        - `task-audit` for task completion mismatches
+        - `code-quality` for quality/security/performance/test issues
+      - summary:
+        - One-line, user-facing issue statement
+      - detail:
+        - Include violated expectation plus observed behavior
+      - file_line:
+        - `path/to/file:line` evidence anchor (use most relevant file and line)
+      - proof:
+        - Concrete evidence snippet (code, test output, or git command result)
+      - suggested_fix:
+        - Actionable implementation guidance
+      - reviewer:
+        - `senior-dev-review`
+      - timestamp:
+        - System ISO datetime at finding creation time
+    </action>
+
+    <!-- Task Completion Audit -->
+    <action>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)
+      5. Append finding object to {{review_findings}} when mismatch is found
+    </action>
+
+    <!-- Code Quality Deep Dive -->
+    <action>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?
+      6. For each issue, append finding object to {{review_findings}}
+    </action>
+
+    <check if="total_issues_found lt 3">
+      <critical>NOT LOOKING HARD ENOUGH - Find more problems!</critical>
+      <action>Re-examine code for:
+        - Edge cases and null handling
+        - Architecture violations
+        - Documentation gaps
+        - Integration issues
+        - Dependency problems
+        - Git commit message quality (if applicable)
+      </action>
+      <action>Find at least 3 more specific, actionable issues</action>
+    </check>
+
+    <action>Persist findings contract for downstream step:
+      - Save {{review_findings}} as JSON array to {{review_findings_file}}
+      - Ensure JSON is valid and each finding includes all required fields
+      - Set {{findings_contract}} = "JSON array at {{review_findings_file}} with schema {{review_findings_schema}}"
+      - Step 4 MUST load findings from {{review_findings_file}} and validate against {{review_findings_schema}} before presenting or resolving
+    </action>
+
+    <action>Example finding record (must match real records):
+      {
+        "id": "AC-003-MISSING-001",
+        "severity": "HIGH",
+        "type": "acceptance-criteria",
+        "summary": "AC-3 missing null-check in API handler",
+        "detail": "Endpoint accepts null payload despite AC requiring rejection with 400.",
+        "file_line": "src/api/handler.ts:87",
+        "proof": "No guard before dereference; test suite lacks AC-3 rejection test.",
+        "suggested_fix": "Add null guard + 400 response and add regression test in test/api/handler.test.ts.",
+        "reviewer": "senior-dev-review",
+        "timestamp": "2026-02-08T00:00:00.000Z"
+      }
+    </action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-04-present-and-resolve.md`.

src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md

@@ -0,0 +1,83 @@
+---
+name: 'step-04-present-and-resolve'
+description: 'Present findings and either apply fixes or create follow-up action items'
+nextStepFile: './step-05-update-status.md'
+reviewFindingsFile: '{story_dir}/review-findings.json'
+---
+
+  <step n="4" goal="Present findings and fix them">
+    <action>Resolve findings artifact input:
+      - Use {{review_findings_file}} from step 3 when present
+      - Otherwise fallback to {reviewFindingsFile}
+      - Set {{review_findings_schema}} = "id,severity,type,summary,detail,file_line,proof,suggested_fix,reviewer,timestamp" if not already set
+    </action>
+    <action>Load structured findings JSON array from {{review_findings_file}}</action>
+    <action>Validate findings schema for each entry:
+      id, severity, type, summary, detail, file_line, proof, suggested_fix, reviewer, timestamp
+    </action>
+    <action>Validation contract:
+      - `file_line` is the required `file:line` locator in `path/to/file:line` format
+      - Reject non-array JSON, missing required keys, or invalid file_line formatting
+      - If findings file missing/unreadable/malformed: HALT with explicit error and return to step 3 generation
+    </action>
+    <action>Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)</action>
+    <action>Set {{fixed_count}} = 0</action>
+    <action>Set {{action_count}} = 0</action>
+
+    <output>**Code Review Findings, {user_name}**
+
+      **Story:** {{story_file}}
+      **Git vs Story Discrepancies:** {{git_discrepancy_count}} found
+      **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low
+
+      ## 🔴 CRITICAL ISSUES
+      - Tasks marked [x] but not actually implemented
+      - Acceptance Criteria not implemented
+      - Story claims files changed but no git evidence
+      - Security vulnerabilities
+
+      ## 🟡 MEDIUM ISSUES
+      - Files changed but not documented in story File List
+      - Uncommitted changes not tracked
+      - Performance problems
+      - Poor test coverage/quality
+      - Code maintainability issues
+
+      ## 🟢 LOW ISSUES
+      - Code style improvements
+      - Documentation gaps
+      - Git commit message quality
+    </output>
+
+    <ask>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:</ask>
+
+    <check if="user chooses 1">
+      <action>Fix all HIGH and MEDIUM issues in the code</action>
+      <action>Add/update tests as needed</action>
+      <action>Update File List in story if files changed</action>
+      <action>Update story Dev Agent Record with fixes applied</action>
+      <action>Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed</action>
+      <action>Set {{action_count}} = 0</action>
+    </check>
+
+    <check if="user chooses 2">
+      <action>Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks</action>
+      <action>For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`</action>
+      <action>Set {{action_count}} = number of action items created</action>
+      <action>Set {{fixed_count}} = 0</action>
+    </check>
+
+    <check if="user chooses 3">
+      <action>Show detailed explanation with code examples</action>
+      <action>Return to fix decision</action>
+    </check>
+  </step>
+
+## Next
+- Read fully and follow: `./step-05-update-status.md`.

src/bmm/workflows/4-implementation/code-review/steps/step-05-update-status.md

@@ -0,0 +1,62 @@
+---
+name: 'step-05-update-status'
+description: 'Update story/sprint status and report review completion'
+---
+
+  <step n="5" goal="Update story status and sync sprint tracking">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md</invoke-task>
+
+    <!-- Determine new status based on review outcome -->
+    <check if="all HIGH and MEDIUM issues fixed AND all ACs implemented">
+      <action>Set {{new_status}} = "done"</action>
+      <action>Update story Status field to "done"</action>
+    </check>
+    <check if="HIGH or MEDIUM issues remain OR ACs not fully implemented">
+      <action>Set {{new_status}} = "in-progress"</action>
+      <action>Update story Status field to "in-progress"</action>
+    </check>
+    <action>Save story file</action>
+
+    <!-- Determine sprint tracking status -->
+    <check if="{sprint_status} file exists">
+      <action>Set {{current_sprint_status}} = "enabled"</action>
+    </check>
+    <check if="{sprint_status} file does NOT exist">
+      <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
+    </check>
+
+    <!-- Sync sprint-status.yaml when story status changes (only if sprint tracking enabled) -->
+    <check if="{{current_sprint_status}} != 'no-sprint-tracking'">
+      <action>Load the FULL file: {sprint_status}</action>
+      <action>Find development_status key matching {{story_key}}</action>
+
+      <check if="{{new_status}} == 'done'">
+        <action>Update development_status[{{story_key}}] = "done"</action>
+        <action>Save file, preserving ALL comments and structure</action>
+        <output>✅ Sprint status synced: {{story_key}} → done</output>
+      </check>
+
+      <check if="{{new_status}} == 'in-progress'">
+        <action>Update development_status[{{story_key}}] = "in-progress"</action>
+        <action>Save file, preserving ALL comments and structure</action>
+        <output>🔄 Sprint status synced: {{story_key}} → in-progress</output>
+      </check>
+
+      <check if="story key not found in sprint status">
+        <output>⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml</output>
+      </check>
+    </check>
+
+    <check if="{{current_sprint_status}} == 'no-sprint-tracking'">
+      <output>ℹ️ Story status updated (no sprint tracking configured)</output>
+    </check>
+
+    <output>**✅ Review Complete!**
+
+      **Story Status:** {{new_status}}
+      **Issues Fixed:** {{fixed_count}}
+      **Action Items Created:** {{action_count}}
+
+      {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}}
+    </output>
+  </step>

src/bmm/workflows/4-implementation/code-review/workflow.md

@@ -0,0 +1,57 @@
+---
+name: code-review
+description: "Perform an adversarial senior developer code review with concrete findings across quality, tests, architecture, security, and performance"
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+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 and story requirements for review context"
+    whole: "{planning_artifacts}/*epic*.md"
+    sharded: "{planning_artifacts}/*epic*/*.md"
+    load_strategy: "FULL_LOAD"
+---
+
+# Code Review Workflow
+
+## Goal
+Run a rigorous review that validates story claims against code reality, surfaces actionable findings, and synchronizes story/sprint status.
+
+## Workflow Architecture
+- Uses step-file execution for predictable, auditable review flow.
+- Read one step file fully, execute it, then continue to the next step.
+- Do not load later steps before the current step completes.
+
+## Initialization
+- Load config from `{project-root}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`
+  - `communication_language`
+  - `document_output_language`
+  - `user_skill_level`
+  - `planning_artifacts`
+  - `implementation_artifacts`
+  - `story_dir` = `{implementation_artifacts}`
+  - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+  - `project_context` = `**/project-context.md`
+  - `date` (system-generated)
+  - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/code-review`
+
+## Critical Rules
+- Communicate in `{communication_language}`.
+- Review implementation evidence, not assumptions.
+- Verify acceptance criteria and completed tasks against actual files.
+- Prioritize concrete, actionable findings with severity and evidence.
+- Exclude generated/config-only folders from source-code review scope (`_bmad/`, `_bmad-output/`, `.cursor/`, `.windsurf/`, `.claude/`).
+
+## Execution
+Read fully and follow: `steps/step-01-load-story-and-changes.md`.

src/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -1,48 +0,0 @@
-# Review Story Workflow
-name: code-review
-description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval."
-author: "BMad"
-
-# 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"
-output_folder: "{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
-
-variables:
-  # Project context
-  project_context: "**/project-context.md"
-  story_dir: "{implementation_artifacts}"
-
-# 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"

src/bmm/workflows/4-implementation/correct-course/checklist.md

@@ -1,6 +1,6 @@
 # Change Navigation Checklist
 
-<critical>This checklist is executed as part of: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>This checklist is executed as part of: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md</critical>
 <critical>Work through each section systematically with the user, recording findings and impacts</critical>
 
 <checklist>

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

@@ -1,7 +1,7 @@
 # Correct Course - Sprint Change Management Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md</critical>
 <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 

src/bmm/workflows/4-implementation/correct-course/workflow.md

@@ -0,0 +1,70 @@
+---
+name: correct-course
+description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+input_file_patterns:
+  prd:
+    description: "Product requirements for impact analysis"
+    whole: "{planning_artifacts}/*prd*.md"
+    sharded: "{planning_artifacts}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
+  epics:
+    description: "All epics to analyze change impact"
+    whole: "{planning_artifacts}/*epic*.md"
+    sharded: "{planning_artifacts}/*epic*/*.md"
+    load_strategy: "FULL_LOAD"
+  architecture:
+    description: "System architecture and decisions"
+    whole: "{planning_artifacts}/*architecture*.md"
+    sharded: "{planning_artifacts}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  ux_design:
+    description: "UX design specification (if UI impacts)"
+    whole: "{planning_artifacts}/*ux*.md"
+    sharded: "{planning_artifacts}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
+  tech_spec:
+    description: "Technical specification"
+    whole: "{planning_artifacts}/*tech-spec*.md"
+    load_strategy: "FULL_LOAD"
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{project_knowledge}/index.md"
+    load_strategy: "INDEX_GUIDED"
+---
+
+## Initialization
+- Load config from `{project-root}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`
+  - `communication_language`
+  - `document_output_language`
+  - `user_skill_level`
+  - `planning_artifacts`
+  - `implementation_artifacts`
+  - `project_knowledge`
+  - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+  - `date` (system-generated)
+  - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/correct-course`
+  - `source_path` = `{project-root}/src/bmm/workflows/4-implementation/correct-course`
+  - Note: `installed_path` targets the installed runtime tree under `_bmad/...`; `source_path` is the repository authoring path.
+  - `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md`
+
+<workflow>
+  <critical>Communicate all responses in {communication_language} and generate all documents in {document_output_language}</critical>
+
+  <step n="1" goal="Analyze changes and propose corrective actions">
+    <action>Resolve workflow content path:
+      - If `{installed_path}/instructions.md` exists and is readable, set {{workflow_path}} = `{installed_path}`
+      - Else if `{source_path}/instructions.md` exists and is readable, set {{workflow_path}} = `{source_path}`
+      - Else emit an error listing both paths and HALT
+    </action>
+    <action>Read and follow instructions at: {{workflow_path}}/instructions.md</action>
+  </step>
+
+  <step n="2" goal="Validate proposal quality">
+    <action>If {{workflow_path}} is not set from step 1, repeat path resolution using checklist.md</action>
+    <invoke-task>Validate against checklist at {{workflow_path}}/checklist.md using {project-root}/_bmad/core/tasks/validate-workflow.md</invoke-task>
+  </step>
+</workflow>

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

@@ -1,56 +0,0 @@
-# Correct Course - Sprint Change Management Workflow
-name: "correct-course"
-description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
-author: "BMad Method"
-
-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
-implementation_artifacts: "{config_source}:implementation_artifacts"
-planning_artifacts: "{config_source}:planning_artifacts"
-project_knowledge: "{config_source}:project_knowledge"
-output_folder: "{implementation_artifacts}"
-sprint_status: "{implementation_artifacts}/sprint-status.yaml"
-
-# Smart input file references - handles both whole docs and sharded docs
-# Priority: Whole document first, then sharded version
-# Strategy: Load project context for impact analysis
-input_file_patterns:
-  prd:
-    description: "Product requirements for impact analysis"
-    whole: "{planning_artifacts}/*prd*.md"
-    sharded: "{planning_artifacts}/*prd*/*.md"
-    load_strategy: "FULL_LOAD"
-  epics:
-    description: "All epics to analyze change impact"
-    whole: "{planning_artifacts}/*epic*.md"
-    sharded: "{planning_artifacts}/*epic*/*.md"
-    load_strategy: "FULL_LOAD"
-  architecture:
-    description: "System architecture and decisions"
-    whole: "{planning_artifacts}/*architecture*.md"
-    sharded: "{planning_artifacts}/*architecture*/*.md"
-    load_strategy: "FULL_LOAD"
-  ux_design:
-    description: "UX design specification (if UI impacts)"
-    whole: "{planning_artifacts}/*ux*.md"
-    sharded: "{planning_artifacts}/*ux*/*.md"
-    load_strategy: "FULL_LOAD"
-  tech_spec:
-    description: "Technical specification"
-    whole: "{planning_artifacts}/*tech-spec*.md"
-    load_strategy: "FULL_LOAD"
-  document_project:
-    description: "Brownfield project documentation (optional)"
-    sharded: "{project_knowledge}/index.md"
-    load_strategy: "INDEX_GUIDED"
-
-installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course"
-template: false
-instructions: "{installed_path}/instructions.md"
-validation: "{installed_path}/checklist.md"
-checklist: "{installed_path}/checklist.md"
-default_output_file: "{planning_artifacts}/sprint-change-proposal-{date}.md"

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

@@ -33,25 +33,25 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de
 
 ### **When Running from Create-Story Workflow:**
 
-- The `{project-root}/_bmad/core/tasks/validate-workflow.xml` framework will automatically:
+- The `{project-root}/_bmad/core/tasks/validate-workflow.md` 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 (story_dir, output_folder, epics_file, etc.)
+- **Workflow variables**: From workflow.md (story_dir, output_folder, epics_file, etc.)
 - **Source documents**: Epics, architecture, etc. (discovered or provided)
-- **Validation framework**: `validate-workflow.xml` (handles checklist execution)
+- **Validation framework**: `validate-workflow.md` (handles checklist execution)
 
 ---
 
@@ -61,9 +61,9 @@ 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/validate-workflow.xml`
+3. **Load validation framework**: `{project-root}/_bmad/core/tasks/validate-workflow.md`
 4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
 5. **Resolve all workflow variables**: story_dir, output_folder, epics_file, architecture_file, etc.
 6. **Understand current status**: What story implementation guidance is currently provided?

src/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -1,6 +1,6 @@
 <workflow>
-  <critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml</critical>
-  <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+  <critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md</critical>
+  <critical>You MUST have already loaded and processed: {installed_path}/workflow.md</critical>
   <critical>Communicate all responses in {communication_language} and generate all documents in {document_output_language}</critical>
 
   <critical>🔥 CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or
@@ -310,7 +310,7 @@
   </step>
 
   <step n="6" goal="Update sprint status and finalize">
-    <invoke-task>Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using {project-root}/_bmad/core/tasks/validate-workflow.md</invoke-task>
     <action>Save story document unconditionally</action>
 
     <!-- Update sprint status -->

src/bmm/workflows/4-implementation/create-story/workflow.md

@@ -0,0 +1,334 @@
+---
+name: create-story
+description: "Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking"
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+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"
+  architecture:
+    description: "Architecture (fallback - epics file should have relevant sections)"
+    whole: "{planning_artifacts}/*architecture*.md"
+    sharded: "{planning_artifacts}/*architecture*/*.md"
+    load_strategy: "SELECTIVE_LOAD"
+  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"
+  epics:
+    description: "Enhanced epics+stories file with BDD and source hints"
+    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"
+---
+
+## Initialization
+- Load config from `{project-root}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`, `communication_language`, `document_output_language`
+  - `planning_artifacts`, `implementation_artifacts`
+  - `story_dir`, `default_output_file`
+  - `sprint_status`, `epics_file`, `prd_file`, `architecture_file`, `ux_file`
+  - `project_context`
+  - `date` (system-generated)
+  - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/create-story`
+
+<workflow>
+  <critical>Communicate all responses in {communication_language} and generate all documents in {document_output_language}</critical>
+
+  <critical>🔥 CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or
+    disasters! 🔥</critical>
+  <critical>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</critical>
+  <critical>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</critical>
+  <critical>🚨 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!</critical>
+  <critical>🔬 UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly
+    analyze different artifacts simultaneously and thoroughly</critical>
+  <critical>❓ SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is
+    written</critical>
+  <critical>🎯 ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents</critical>
+
+  <step n="1" goal="Determine target story">
+    <check if="{{story_path}} is provided by user or user provided the epic and story number such as 2-4 or 1.6 or epic 1 story 5">
+      <action>Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth"</action>
+      <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action>
+      <action>GOTO step 2</action>
+    </check>
+
+    <action>Check if {{sprint_status}} file exists for auto discover</action>
+    <check if="sprint status file does NOT exist">
+      <output>🚫 No sprint status file found and no story specified</output>
+      <output>
+        **Required Options:**
+        1. Run `sprint-planning` to initialize sprint tracking (recommended)
+        2. Provide specific epic-story number to create (e.g., "1-2-user-auth")
+        3. Provide path to story documents if sprint status doesn't exist yet
+      </output>
+      <ask>Choose option [1], provide epic-story number, path to story docs, or [q] to quit:</ask>
+
+      <check if="user chooses 'q'">
+        <action>HALT - No work needed</action>
+      </check>
+
+      <check if="user chooses '1'">
+        <output>Run sprint-planning workflow first to create sprint-status.yaml</output>
+        <action>HALT - User needs to run sprint-planning</action>
+      </check>
+
+      <check if="user provides epic-story number">
+        <action>Parse user input: extract epic_num, story_num, story_title</action>
+        <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action>
+        <action>GOTO step 2</action>
+      </check>
+
+      <check if="user provides story docs path">
+        <action>Use user-provided path for story documents</action>
+        <action>GOTO step 2</action>
+      </check>
+    </check>
+
+    <!-- Auto-discover from sprint status only if no user input -->
+    <check if="no user input provided">
+      <critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{sprint_status}}</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely</action>
+
+      <action>Find the FIRST story (by reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "backlog"
+      </action>
+
+      <check if="no backlog story found">
+        <output>📋 No backlog stories found in sprint-status.yaml
+
+          All stories are either already created, in progress, or done.
+
+          **Options:**
+          1. Run sprint-planning to refresh story tracking
+          2. Load PM agent and run correct-course to add more stories
+          3. Check if current sprint is complete and run retrospective
+        </output>
+        <action>HALT</action>
+      </check>
+
+      <action>Extract from found story key (e.g., "1-2-user-authentication"):
+        - epic_num: first number before dash (e.g., "1")
+        - story_num: second number after first dash (e.g., "2")
+        - story_title: remainder after second dash (e.g., "user-authentication")
+      </action>
+      <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
+      <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
+
+      <!-- Mark epic as in-progress if this is first story -->
+      <action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action>
+      <check if="this is first story in epic {{epic_num}}">
+        <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
+        <action>If epic status is "backlog" → update to "in-progress"</action>
+        <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
+        <action>If epic status is "in-progress" → no change needed</action>
+        <check if="epic status is 'done'">
+          <output>🚫 ERROR: Cannot create story in completed epic</output>
+          <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
+          <output>If you need to add more work, either:</output>
+          <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
+          <output>2. Create a new epic for additional work</output>
+          <action>HALT - Cannot proceed</action>
+        </check>
+        <check if="epic status is not one of: backlog, contexted, in-progress, done">
+          <output>🚫 ERROR: Invalid epic status '{{epic_status}}'</output>
+          <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
+          <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
+          <action>HALT - Cannot proceed</action>
+        </check>
+        <output>📊 Epic {{epic_num}} status updated to in-progress</output>
+      </check>
+
+      <action>GOTO step 2</action>
+    </check>
+  </step>
+
+  <step n="2" goal="Load and analyze core artifacts">
+    <critical>🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer mistakes!</critical>
+
+    <!-- Load all available content through discovery protocol -->
+    <invoke-protocol
+      name="discover_inputs" />
+    <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content},
+    {project_context}</note>
+
+    <!-- Analyze epics file for story foundation -->
+    <action>From {epics_content}, extract Epic {{epic_num}} complete context:</action> **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 specific story requirements -->
+    <action>Extract our story ({{epic_num}}-{{story_num}}) details:</action> **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 <!-- Previous story analysis for context continuity -->
+    <check if="story_num > 1">
+      <action>Set {{previous_story_num}} = {{story_num}} - 1</action>
+      <action>Load previous story file: {{story_dir}}/{{epic_num}}-{{previous_story_num}}-*.md</action>
+      <action>Extract 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
+      </action>
+      <action>Extract all learnings that could impact current story implementation</action>
+    </check>
+
+    <!-- Git intelligence for previous work patterns -->
+    <check
+      if="previous story exists AND git repository detected">
+      <action>Get last 5 commit titles to understand recent work patterns</action>
+      <action>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
+      </action>
+      <action>Extract actionable insights for current story implementation</action>
+    </check>
+  </step>
+
+  <step n="3" goal="Architecture analysis for developer guardrails">
+    <critical>🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow!</critical> **ARCHITECTURE DOCUMENT ANALYSIS:** <action>Systematically
+    analyze architecture content for story-relevant requirements:</action>
+
+    <!-- Load architecture - single file or sharded -->
+    <check if="architecture file is single file">
+      <action>Load complete {architecture_content}</action>
+    </check>
+    <check if="architecture is sharded to folder">
+      <action>Load architecture index and scan all architecture files</action>
+    </check> **CRITICAL ARCHITECTURE EXTRACTION:** <action>For
+    each architecture section, determine if relevant to this story:</action> - **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 <action>Extract any story-specific requirements that the
+    developer MUST follow</action>
+    <action>Identify any architectural decisions that override previous patterns</action>
+  </step>
+
+  <step n="4" goal="Web research for latest technical specifics">
+    <critical>🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations!</critical> **WEB INTELLIGENCE:** <action>Identify specific
+    technical areas that require latest version knowledge:</action>
+
+    <!-- Check for libraries/frameworks mentioned in architecture -->
+    <action>From architecture analysis, identify specific libraries, APIs, or
+    frameworks</action>
+    <action>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
+    </action>
+    **EXTERNAL CONTEXT INCLUSION:** <action>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
+    </action>
+  </step>
+
+  <step n="5" goal="Create comprehensive story file">
+    <critical>📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide!</critical>
+
+    <action>Initialize from template.md:
+    {default_output_file}</action>
+    <template-output file="{default_output_file}">story_header</template-output>
+
+    <!-- Story foundation from epics analysis -->
+    <template-output
+      file="{default_output_file}">story_requirements</template-output>
+
+    <!-- Developer context section - MOST IMPORTANT PART -->
+    <template-output file="{default_output_file}">
+    developer_context_section</template-output> **DEV AGENT GUARDRAILS:** <template-output file="{default_output_file}">
+    technical_requirements</template-output>
+    <template-output file="{default_output_file}">architecture_compliance</template-output>
+    <template-output
+      file="{default_output_file}">library_framework_requirements</template-output>
+    <template-output file="{default_output_file}">
+    file_structure_requirements</template-output>
+    <template-output file="{default_output_file}">testing_requirements</template-output>
+
+    <!-- Previous story intelligence -->
+    <check
+      if="previous story learnings available">
+      <template-output file="{default_output_file}">previous_story_intelligence</template-output>
+    </check>
+
+    <!-- Git intelligence -->
+    <check
+      if="git analysis completed">
+      <template-output file="{default_output_file}">git_intelligence_summary</template-output>
+    </check>
+
+    <!-- Latest technical specifics -->
+    <check if="web research completed">
+      <template-output file="{default_output_file}">latest_tech_information</template-output>
+    </check>
+
+    <!-- Project context reference -->
+    <template-output
+      file="{default_output_file}">project_context_reference</template-output>
+
+    <!-- Final status update -->
+    <template-output file="{default_output_file}">
+    story_completion_status</template-output>
+
+    <!-- CRITICAL: Set status to ready-for-dev -->
+    <action>Set story Status to: "ready-for-dev"</action>
+    <action>Add completion note: "Ultimate
+    context engine analysis completed - comprehensive developer guide created"</action>
+  </step>
+
+  <step n="6" goal="Update sprint status and finalize">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using {project-root}/_bmad/core/tasks/validate-workflow.md</invoke-task>
+    <action>Save story document unconditionally</action>
+
+    <!-- Update sprint status -->
+    <check if="sprint status file exists">
+      <action>Update {{sprint_status}}</action>
+      <action>Load the FULL file and read all development_status entries</action>
+      <action>Find development_status key matching {{story_key}}</action>
+      <action>Verify current status is "backlog" (expected previous state)</action>
+      <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+    </check>
+
+    <action>Report completion</action>
+    <output>**🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!**
+
+      **Story Details:**
+      - Story ID: {{story_id}}
+      - Story Key: {{story_key}}
+      - File: {{story_file}}
+      - Status: ready-for-dev
+
+      **Next Steps:**
+      1. Review the comprehensive story in {{story_file}}
+      2. Run dev agents `dev-story` for optimized implementation
+      3. Run `code-review` when complete (auto-marks done)
+      4. Optional: Run TEA `*automate` after `dev-story` to generate guardrail tests
+
+      **The developer now has everything needed for flawless implementation!**
+    </output>
+  </step>
+
+</workflow>

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

@@ -1,57 +0,0 @@
-name: create-story
-description: "Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking"
-author: "BMad"
-
-# Critical variables from config
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-user_name: "{config_source}:user_name"
-communication_language: "{config_source}:communication_language"
-date: system-generated
-planning_artifacts: "{config_source}:planning_artifacts"
-implementation_artifacts: "{config_source}:implementation_artifacts"
-output_folder: "{implementation_artifacts}"
-story_dir: "{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
-variables:
-  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: "**/project-context.md"
-
-default_output_file: "{story_dir}/{{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

src/bmm/workflows/4-implementation/dev-story/instructions.xml

@@ -1,410 +0,0 @@
-<workflow>
-  <critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml</critical>
-  <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-  <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
-  <critical>Generate all documents in {document_output_language}</critical>
-  <critical>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List,
-    Change Log, and Status</critical>
-  <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
-  <critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution
-    until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives
-    other instruction.</critical>
-  <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
-  <critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
-
-  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
-    <check if="{{story_path}} is provided">
-      <action>Use {{story_path}} directly</action>
-      <action>Read COMPLETE story file</action>
-      <action>Extract story_key from filename or metadata</action>
-      <goto anchor="task_check" />
-    </check>
-
-    <!-- Sprint-based story discovery -->
-    <check if="{{sprint_status}} file exists">
-      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
-      <action>Load the FULL file: {{sprint_status}}</action>
-      <action>Read ALL lines from beginning to end - do not skip any content</action>
-      <action>Parse the development_status section completely to understand story order</action>
-
-      <action>Find the FIRST story (by reading in order from top to bottom) where:
-        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
-        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
-        - Status value equals "ready-for-dev"
-      </action>
-
-      <check if="no ready-for-dev or in-progress story found">
-        <output>📋 No ready-for-dev stories found in sprint-status.yaml
-
-          **Current Sprint Status:** {{sprint_status_summary}}
-
-          **What would you like to do?**
-          1. Run `create-story` to create next story from epics with comprehensive context
-          2. Run `*validate-create-story` to improve existing stories before development (recommended quality check)
-          3. Specify a particular story file to develop (provide full path)
-          4. Check {{sprint_status}} file to see current sprint status
-
-          💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality
-          check.
-        </output>
-        <ask>Choose option [1], [2], [3], or [4], or specify story file path:</ask>
-
-        <check if="user chooses '1'">
-          <action>HALT - Run create-story to create next story</action>
-        </check>
-
-        <check if="user chooses '2'">
-          <action>HALT - Run validate-create-story to improve existing stories</action>
-        </check>
-
-        <check if="user chooses '3'">
-          <ask>Provide the story file path to develop:</ask>
-          <action>Store user-provided story path as {{story_path}}</action>
-          <goto anchor="task_check" />
-        </check>
-
-        <check if="user chooses '4'">
-          <output>Loading {{sprint_status}} for detailed status review...</output>
-          <action>Display detailed sprint status analysis</action>
-          <action>HALT - User can review sprint status and provide story path</action>
-        </check>
-
-        <check if="user provides story file path">
-          <action>Store user-provided story path as {{story_path}}</action>
-          <goto anchor="task_check" />
-        </check>
-      </check>
-    </check>
-
-    <!-- Non-sprint story discovery -->
-    <check if="{{sprint_status}} file does NOT exist">
-      <action>Search {story_dir} for stories directly</action>
-      <action>Find stories with "ready-for-dev" status in files</action>
-      <action>Look for story files matching pattern: *-*-*.md</action>
-      <action>Read each candidate story file to check Status section</action>
-
-      <check if="no ready-for-dev stories found in story files">
-        <output>📋 No ready-for-dev stories found
-
-          **Available Options:**
-          1. Run `create-story` to create next story from epics with comprehensive context
-          2. Run `*validate-create-story` to improve existing stories
-          3. Specify which story to develop
-        </output>
-        <ask>What would you like to do? Choose option [1], [2], or [3]:</ask>
-
-        <check if="user chooses '1'">
-          <action>HALT - Run create-story to create next story</action>
-        </check>
-
-        <check if="user chooses '2'">
-          <action>HALT - Run validate-create-story to improve existing stories</action>
-        </check>
-
-        <check if="user chooses '3'">
-          <ask>It's unclear what story you want developed. Please provide the full path to the story file:</ask>
-          <action>Store user-provided story path as {{story_path}}</action>
-          <action>Continue with provided story file</action>
-        </check>
-      </check>
-
-      <check if="ready-for-dev story found in files">
-        <action>Use discovered story file and extract story_key</action>
-      </check>
-    </check>
-
-    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
-    <action>Find matching story file in {story_dir} using story_key pattern: {{story_key}}.md</action>
-    <action>Read COMPLETE story file from discovered path</action>
-
-    <anchor id="task_check" />
-
-    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
-
-    <action>Load comprehensive context from story file's Dev Notes section</action>
-    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
-    <action>Use enhanced story context to inform implementation decisions and approaches</action>
-
-    <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
-
-    <action if="no incomplete tasks">
-      <goto step="6">Completion sequence</goto>
-    </action>
-    <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
-    <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
-  </step>
-
-  <step n="2" goal="Load project context and story information">
-    <critical>Load all available context to inform implementation</critical>
-
-    <action>Load {project_context} for coding standards and project-wide patterns (if exists)</action>
-    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
-    <action>Load comprehensive context from story file's Dev Notes section</action>
-    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
-    <action>Use enhanced story context to inform implementation decisions and approaches</action>
-    <output>✅ **Context Loaded**
-      Story and project context available for implementation
-    </output>
-  </step>
-
-  <step n="3" goal="Detect review continuation and extract review context">
-    <critical>Determine if this is a fresh start or continuation after code review</critical>
-
-    <action>Check if "Senior Developer Review (AI)" section exists in the story file</action>
-    <action>Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks</action>
-
-    <check if="Senior Developer Review section exists">
-      <action>Set review_continuation = true</action>
-      <action>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)
-      </action>
-      <action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
-      <action>Store list of unchecked review items as {{pending_review_items}}</action>
-
-      <output>⏯️ **Resuming Story After Code Review** ({{review_date}})
-
-        **Review Outcome:** {{review_outcome}}
-        **Action Items:** {{unchecked_review_count}} remaining to address
-        **Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low
-
-        **Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks.
-      </output>
-    </check>
-
-    <check if="Senior Developer Review section does NOT exist">
-      <action>Set review_continuation = false</action>
-      <action>Set {{pending_review_items}} = empty</action>
-
-      <output>🚀 **Starting Fresh Implementation**
-
-        Story: {{story_key}}
-        Story Status: {{current_status}}
-        First incomplete task: {{first_task_description}}
-      </output>
-    </check>
-  </step>
-
-  <step n="4" goal="Mark story in-progress" tag="sprint-status">
-    <check if="{{sprint_status}} file exists">
-      <action>Load the FULL file: {{sprint_status}}</action>
-      <action>Read all development_status entries to find {{story_key}}</action>
-      <action>Get current status value for development_status[{{story_key}}]</action>
-
-      <check if="current status == 'ready-for-dev' OR review_continuation == true">
-        <action>Update the story in the sprint status report to = "in-progress"</action>
-        <output>🚀 Starting work on story {{story_key}}
-          Status updated: ready-for-dev → in-progress
-        </output>
-      </check>
-
-      <check if="current status == 'in-progress'">
-        <output>⏯️ Resuming work on story {{story_key}}
-          Story is already marked in-progress
-        </output>
-      </check>
-
-      <check if="current status is neither ready-for-dev nor in-progress">
-        <output>⚠️ Unexpected story status: {{current_status}}
-          Expected ready-for-dev or in-progress. Continuing anyway...
-        </output>
-      </check>
-
-      <action>Store {{current_sprint_status}} for later use</action>
-    </check>
-
-    <check if="{{sprint_status}} file does NOT exist">
-      <output>ℹ️ No sprint status file exists - story progress will be tracked in story file only</output>
-      <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
-    </check>
-  </step>
-
-  <step n="5" goal="Implement task following red-green-refactor cycle">
-    <critical>FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION</critical>
-
-    <action>Review the current task/subtask from the story file - this is your authoritative implementation guide</action>
-    <action>Plan implementation following red-green-refactor cycle</action>
-
-    <!-- RED PHASE -->
-    <action>Write FAILING tests first for the task/subtask functionality</action>
-    <action>Confirm tests fail before implementation - this validates test correctness</action>
-
-    <!-- GREEN PHASE -->
-    <action>Implement MINIMAL code to make tests pass</action>
-    <action>Run tests to confirm they now pass</action>
-    <action>Handle error conditions and edge cases as specified in task/subtask</action>
-
-    <!-- REFACTOR PHASE -->
-    <action>Improve code structure while keeping tests green</action>
-    <action>Ensure code follows architecture patterns and coding standards from Dev Notes</action>
-
-    <action>Document technical approach and decisions in Dev Agent Record → Implementation Plan</action>
-
-    <action if="new dependencies required beyond story specifications">HALT: "Additional dependencies need user approval"</action>
-    <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
-    <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
-
-    <critical>NEVER implement anything not mapped to a specific task/subtask in the story file</critical>
-    <critical>NEVER proceed to next task until current task/subtask is complete AND tests pass</critical>
-    <critical>Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition</critical>
-    <critical>Do NOT propose to pause for review until Step 9 completion gates are satisfied</critical>
-  </step>
-
-  <step n="6" goal="Author comprehensive tests">
-    <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
-    <action>Add integration tests for component interactions specified in story requirements</action>
-    <action>Include end-to-end tests for critical user flows when story requirements demand them</action>
-    <action>Cover edge cases and error handling scenarios identified in story Dev Notes</action>
-  </step>
-
-  <step n="7" goal="Run validations and tests">
-    <action>Determine how to run tests for this repo (infer test framework from project structure)</action>
-    <action>Run all existing tests to ensure no regressions</action>
-    <action>Run the new tests to verify implementation correctness</action>
-    <action>Run linting and code quality checks if configured in project</action>
-    <action>Validate implementation meets ALL story acceptance criteria; enforce quantitative thresholds explicitly</action>
-    <action if="regression tests fail">STOP and fix before continuing - identify breaking changes immediately</action>
-    <action if="new tests fail">STOP and fix before continuing - ensure implementation correctness</action>
-  </step>
-
-  <step n="8" goal="Validate and mark task complete ONLY when fully done">
-    <critical>NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING</critical>
-
-    <!-- VALIDATION GATES -->
-    <action>Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100%</action>
-    <action>Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features</action>
-    <action>Validate that ALL acceptance criteria related to this task are satisfied</action>
-    <action>Run full test suite to ensure NO regressions introduced</action>
-
-    <!-- REVIEW FOLLOW-UP HANDLING -->
-    <check if="task is review follow-up (has [AI-Review] prefix)">
-      <action>Extract review item details (severity, description, related AC/file)</action>
-      <action>Add to resolution tracking list: {{resolved_review_items}}</action>
-
-      <!-- Mark task in Review Follow-ups section -->
-      <action>Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section</action>
-
-      <!-- CRITICAL: Also mark corresponding action item in review section -->
-      <action>Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description</action>
-      <action>Mark that action item checkbox [x] as resolved</action>
-
-      <action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}"</action>
-    </check>
-
-    <!-- ONLY MARK COMPLETE IF ALL VALIDATION PASS -->
-    <check if="ALL validation gates pass AND tests ACTUALLY exist and pass">
-      <action>ONLY THEN mark the task (and subtasks) checkbox with [x]</action>
-      <action>Update File List section with ALL new, modified, or deleted files (paths relative to repo root)</action>
-      <action>Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested</action>
-    </check>
-
-    <check if="ANY validation fails">
-      <action>DO NOT mark task complete - fix issues first</action>
-      <action>HALT if unable to fix validation failures</action>
-    </check>
-
-    <check if="review_continuation == true and {{resolved_review_items}} is not empty">
-      <action>Count total resolved review items in this session</action>
-      <action>Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"</action>
-    </check>
-
-    <action>Save the story file</action>
-    <action>Determine if more incomplete tasks remain</action>
-    <action if="more tasks remain">
-      <goto step="5">Next task</goto>
-    </action>
-    <action if="no tasks remain">
-      <goto step="9">Completion</goto>
-    </action>
-  </step>
-
-  <step n="9" goal="Story completion and mark for review" tag="sprint-status">
-    <action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
-    <action>Run the full regression suite (do not skip)</action>
-    <action>Confirm File List includes every changed file</action>
-    <action>Execute enhanced definition-of-done validation</action>
-    <action>Update the story Status to: "review"</action>
-
-    <!-- Enhanced Definition of Done Validation -->
-    <action>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
-    </action>
-
-    <!-- Mark story ready for review - sprint status conditional -->
-    <check if="{sprint_status} file exists AND {{current_sprint_status}} != 'no-sprint-tracking'">
-      <action>Load the FULL file: {sprint_status}</action>
-      <action>Find development_status key matching {{story_key}}</action>
-      <action>Verify current status is "in-progress" (expected previous state)</action>
-      <action>Update development_status[{{story_key}}] = "review"</action>
-      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
-      <output>✅ Story status updated to "review" in sprint-status.yaml</output>
-    </check>
-
-    <check if="{sprint_status} file does NOT exist OR {{current_sprint_status}} == 'no-sprint-tracking'">
-      <output>ℹ️ Story status updated to "review" in story file (no sprint tracking configured)</output>
-    </check>
-
-    <check if="story key not found in sprint status">
-      <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
-
-        Story status is set to "review" in file, but sprint-status.yaml may be out of sync.
-      </output>
-    </check>
-
-    <!-- Final validation gates -->
-    <action if="any task is incomplete">HALT - Complete remaining tasks before marking ready for review</action>
-    <action if="regression failures exist">HALT - Fix regression issues before completing</action>
-    <action if="File List is incomplete">HALT - Update File List with all changed files</action>
-    <action if="definition-of-done validation fails">HALT - Address DoD failures before completing</action>
-  </step>
-
-  <step n="10" goal="Completion communication and user support">
-    <action>Execute the enhanced definition-of-done checklist using the validation framework</action>
-    <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
-
-    <action>Communicate to {user_name} that story implementation is complete and ready for review</action>
-    <action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
-    <action>Provide the story file path and current status (now "review")</action>
-
-    <action>Based on {user_skill_level}, ask if user needs any explanations about:
-      - What was implemented and how it works
-      - Why certain technical decisions were made
-      - How to test or verify the changes
-      - Any patterns, libraries, or approaches used
-      - Anything else they'd like clarified
-    </action>
-
-    <check if="user asks for explanations">
-      <action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
-      <action>Use examples and references to specific code when helpful</action>
-    </check>
-
-    <action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
-    <action>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
-    </action>
-
-    <output>💡 **Tip:** For best results, run `code-review` using a **different** LLM than the one that implemented this story.</output>
-    <check if="{sprint_status} file exists">
-      <action>Suggest checking {sprint_status} to see project progress</action>
-    </check>
-    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
-  </step>
-
-</workflow>

src/bmm/workflows/4-implementation/dev-story/steps/step-01-find-story.md

@@ -0,0 +1,130 @@
+---
+name: 'step-01-find-story'
+description: 'Find the next ready story (or accept explicit input), load it completely, and identify the next actionable task'
+nextStepFile: './step-02-load-context.md'
+---
+
+  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file</action>
+      <action>Extract story_key from filename or metadata</action>
+      <goto anchor="task_check" />
+    </check>
+
+    <!-- Sprint-based story discovery -->
+    <check if="{{sprint_status}} file exists">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{sprint_status}}</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely to understand story order</action>
+
+      <action>Find the FIRST story (by reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "ready-for-dev"
+      </action>
+
+      <check if="no ready-for-dev or in-progress story found">
+        <output>📋 No ready-for-dev stories found in sprint-status.yaml
+
+          **Current Sprint Status:** {{sprint_status_summary}}
+
+          **What would you like to do?**
+          1. Run `create-story` to create next story from epics with comprehensive context
+          2. Run `*validate-create-story` to improve existing stories before development (recommended quality check)
+          3. Specify a particular story file to develop (provide full path)
+          4. Check {{sprint_status}} file to see current sprint status
+
+          💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality
+          check.
+        </output>
+        <ask>Choose option [1], [2], [3], or [4], or specify story file path:</ask>
+
+        <check if="user chooses '1'">
+          <action>HALT - Run create-story to create next story</action>
+        </check>
+
+        <check if="user chooses '2'">
+          <action>HALT - Run validate-create-story to improve existing stories</action>
+        </check>
+
+        <check if="user chooses '3'">
+          <ask>Provide the story file path to develop:</ask>
+          <action>Store user-provided story path as {{story_path}}</action>
+          <goto anchor="task_check" />
+        </check>
+
+        <check if="user chooses '4'">
+          <output>Loading {{sprint_status}} for detailed status review...</output>
+          <action>Display detailed sprint status analysis</action>
+          <action>HALT - User can review sprint status and provide story path</action>
+        </check>
+
+        <check if="user provides story file path">
+          <action>Store user-provided story path as {{story_path}}</action>
+          <goto anchor="task_check" />
+        </check>
+      </check>
+    </check>
+
+    <!-- Non-sprint story discovery -->
+    <check if="{{sprint_status}} file does NOT exist">
+      <action>Search {story_dir} for stories directly</action>
+      <action>Find stories with "ready-for-dev" status in files</action>
+      <action>Look for story files matching pattern: *-*-*.md</action>
+      <action>Read each candidate story file to check Status section</action>
+
+      <check if="no ready-for-dev stories found in story files">
+        <output>📋 No ready-for-dev stories found
+
+          **Available Options:**
+          1. Run `create-story` to create next story from epics with comprehensive context
+          2. Run `*validate-create-story` to improve existing stories
+          3. Specify which story to develop
+        </output>
+        <ask>What would you like to do? Choose option [1], [2], or [3]:</ask>
+
+        <check if="user chooses '1'">
+          <action>HALT - Run create-story to create next story</action>
+        </check>
+
+        <check if="user chooses '2'">
+          <action>HALT - Run validate-create-story to improve existing stories</action>
+        </check>
+
+        <check if="user chooses '3'">
+          <ask>It's unclear what story you want developed. Please provide the full path to the story file:</ask>
+          <action>Store user-provided story path as {{story_path}}</action>
+          <action>Continue with provided story file</action>
+        </check>
+      </check>
+
+      <check if="ready-for-dev story found in files">
+        <action>Use discovered story file and extract story_key</action>
+      </check>
+    </check>
+
+    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
+    <action>Find matching story file in {story_dir} using story_key pattern: {{story_key}}.md</action>
+    <action>Read COMPLETE story file from discovered path</action>
+
+    <anchor id="task_check" />
+
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+
+    <action>Load comprehensive context from story file's Dev Notes section</action>
+    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Use enhanced story context to inform implementation decisions and approaches</action>
+
+    <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
+
+    <action if="no incomplete tasks">
+      <goto step="6">Completion sequence</goto>
+    </action>
+    <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
+    <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-02-load-context.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md

@@ -0,0 +1,38 @@
+---
+name: 'step-02-load-context'
+description: 'Load project and story context needed for implementation decisions'
+nextStepFile: './step-03-detect-review-continuation.md'
+---
+
+  <step n="2" goal="Load project context and story information">
+    <critical>Load all available context to inform implementation</critical>
+
+    <action>Load {project_context} for coding standards and project-wide patterns (if exists)</action>
+    <action>Validate story source before parsing:
+      - Verify story file exists and is readable
+      - If missing/unreadable: emit explicit error and HALT
+    </action>
+    <action>Parse and validate required sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Status
+      - If section missing, empty, or malformed: emit explicit error with section name and HALT
+      - Dev Notes is CRITICAL and MUST be present with non-empty actionable content
+    </action>
+    <action>Parse and validate optional section: Change Log
+      - If missing/empty: create warning and continue with safe default ("No prior change log entries")
+    </action>
+    <action>Validate structure before extraction:
+      - Story: identifiable title + narrative structure
+      - Acceptance Criteria: parseable list/numbered clauses
+      - Tasks/Subtasks: checkbox task format with stable task boundaries
+      - Dev Agent Record/File List/Status: parseable heading + body content
+      - If malformed structure prevents reliable parsing: emit explicit error and HALT
+    </action>
+    <action>Load comprehensive context from story file's Dev Notes section ONLY after validation passes</action>
+    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Use enhanced story context to inform implementation decisions and approaches</action>
+    <output>✅ **Context Loaded**
+      Story and project context available for implementation
+    </output>
+  </step>
+
+## Next
+- Read fully and follow: `./step-03-detect-review-continuation.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-03-detect-review-continuation.md

@@ -0,0 +1,48 @@
+---
+name: 'step-03-detect-review-continuation'
+description: 'Determine whether this run resumes from prior code review and gather pending follow-ups'
+nextStepFile: './step-04-mark-in-progress.md'
+---
+
+  <step n="3" goal="Detect review continuation and extract review context">
+    <critical>Determine if this is a fresh start or continuation after code review</critical>
+
+    <action>Check if "Senior Developer Review (AI)" section exists in the story file</action>
+    <action>Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks</action>
+
+    <check if="Senior Developer Review section exists">
+      <action>Set review_continuation = true</action>
+      <action>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)
+      </action>
+      <action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
+      <action>Store list of unchecked review items as {{pending_review_items}}</action>
+
+      <output>⏯️ **Resuming Story After Code Review** ({{review_date}})
+
+        **Review Outcome:** {{review_outcome}}
+        **Action Items:** {{unchecked_review_count}} remaining to address
+        **Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low
+
+        **Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks.
+      </output>
+    </check>
+
+    <check if="Senior Developer Review section does NOT exist">
+      <action>Set review_continuation = false</action>
+      <action>Set {{pending_review_items}} = empty</action>
+
+      <output>🚀 **Starting Fresh Implementation**
+
+        Story: {{story_key}}
+        Story Status: {{current_status}}
+        First incomplete task: {{first_task_description}}
+      </output>
+    </check>
+  </step>
+
+## Next
+- Read fully and follow: `./step-04-mark-in-progress.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-04-mark-in-progress.md

@@ -0,0 +1,42 @@
+---
+name: 'step-04-mark-in-progress'
+description: 'Synchronize in-progress status with sprint tracking when available'
+nextStepFile: './step-05-implement-task.md'
+---
+
+  <step n="4" goal="Mark story in-progress" tag="sprint-status">
+    <check if="{{sprint_status}} file exists">
+      <action>Load the FULL file: {{sprint_status}}</action>
+      <action>Read all development_status entries to find {{story_key}}</action>
+      <action>Get current status value for development_status[{{story_key}}]</action>
+
+      <check if="current status == 'ready-for-dev' OR review_continuation == true">
+        <action>Update the story in the sprint status report to = "in-progress"</action>
+        <output>🚀 Starting work on story {{story_key}}
+          Status updated: ready-for-dev → in-progress
+        </output>
+      </check>
+
+      <check if="current status == 'in-progress'">
+        <output>⏯️ Resuming work on story {{story_key}}
+          Story is already marked in-progress
+        </output>
+      </check>
+
+      <check if="current status is neither ready-for-dev nor in-progress">
+        <output>⚠️ Unexpected story status: {{current_status}}
+          Expected ready-for-dev or in-progress. Continuing anyway...
+        </output>
+      </check>
+
+      <action>Store {{current_sprint_status}} for later use</action>
+    </check>
+
+    <check if="{{sprint_status}} file does NOT exist">
+      <output>ℹ️ No sprint status file exists - story progress will be tracked in story file only</output>
+      <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
+    </check>
+  </step>
+
+## Next
+- Read fully and follow: `./step-05-implement-task.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-05-implement-task.md

@@ -0,0 +1,39 @@
+---
+name: 'step-05-implement-task'
+description: 'Implement the current task using red-green-refactor and story constraints'
+nextStepFile: './step-06-author-tests.md'
+---
+
+  <step n="5" goal="Implement task following red-green-refactor cycle">
+    <critical>FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION</critical>
+
+    <action>Review the current task/subtask from the story file - this is your authoritative implementation guide</action>
+    <action>Plan implementation following red-green-refactor cycle</action>
+
+    <!-- RED PHASE -->
+    <action>Write FAILING tests first for the task/subtask functionality</action>
+    <action>Confirm tests fail before implementation - this validates test correctness</action>
+
+    <!-- GREEN PHASE -->
+    <action>Implement MINIMAL code to make tests pass</action>
+    <action>Run tests to confirm they now pass</action>
+    <action>Handle error conditions and edge cases as specified in task/subtask</action>
+
+    <!-- REFACTOR PHASE -->
+    <action>Improve code structure while keeping tests green</action>
+    <action>Ensure code follows architecture patterns and coding standards from Dev Notes</action>
+
+    <action>Document technical approach and decisions in Dev Agent Record → Implementation Plan</action>
+
+    <action if="new dependencies required beyond story specifications">HALT: "Additional dependencies need user approval"</action>
+    <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
+    <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
+
+    <critical>NEVER implement anything not mapped to a specific task/subtask in the story file</critical>
+    <critical>NEVER proceed to next task until current task/subtask is complete AND tests pass</critical>
+    <critical>Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition</critical>
+    <critical>Do NOT propose to pause for review until Step 9 completion gates are satisfied</critical>
+  </step>
+
+## Next
+- Read fully and follow: `./step-06-author-tests.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-06-author-tests.md

@@ -0,0 +1,15 @@
+---
+name: 'step-06-author-tests'
+description: 'Author comprehensive unit/integration/e2e coverage required by the story'
+nextStepFile: './step-07-run-validations.md'
+---
+
+  <step n="6" goal="Author comprehensive tests">
+    <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
+    <action>Add integration tests for component interactions specified in story requirements</action>
+    <action>Include end-to-end tests for critical user flows when story requirements demand them</action>
+    <action>Cover edge cases and error handling scenarios identified in story Dev Notes</action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-07-run-validations.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-07-run-validations.md

@@ -0,0 +1,18 @@
+---
+name: 'step-07-run-validations'
+description: 'Run repository test and validation commands, then stop on regressions'
+nextStepFile: './step-08-mark-task-complete.md'
+---
+
+  <step n="7" goal="Run validations and tests">
+    <action>Determine how to run tests for this repo (infer test framework from project structure)</action>
+    <action>Run all existing tests to ensure no regressions</action>
+    <action>Run the new tests to verify implementation correctness</action>
+    <action>Run linting and code quality checks if configured in project</action>
+    <action>Validate implementation meets ALL story acceptance criteria; enforce quantitative thresholds explicitly</action>
+    <action if="regression tests fail">STOP and fix before continuing - identify breaking changes immediately</action>
+    <action if="new tests fail">STOP and fix before continuing - ensure implementation correctness</action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-08-mark-task-complete.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md

@@ -0,0 +1,119 @@
+---
+name: 'step-08-mark-task-complete'
+description: 'Mark work complete only after strict validation gates are satisfied'
+nextStepFile: './step-09-mark-review-ready.md'
+---
+
+  <step n="8" goal="Validate and mark task complete ONLY when fully done">
+    <critical>NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING</critical>
+
+    <action>Initialize review-tracking variables before checks:
+      - If {{resolved_review_items}} is undefined: set {{resolved_review_items}} = []
+      - If {{unresolved_review_items}} is undefined: set {{unresolved_review_items}} = []
+      - Set {{review_continuation}} = false
+      - If current {{task_title}} starts with "[AI-Review]", set {{review_continuation}} = true
+      - Else scan {{original_task_list}}; if any item starts with "[AI-Review]", set {{review_continuation}} = true
+      - Set {{date}} from system-generated timestamp formatted for project change log entries
+      - Set {{resolved_count}} = length({{resolved_review_items}})
+      - Set {{review_match_threshold}} = 0.60
+      - Define normalize(text): lowercase, trim, remove "[AI-Review]" prefix and punctuation, collapse whitespace
+      - Define token_set(text): unique whitespace-separated normalized tokens
+    </action>
+
+    <!-- VALIDATION GATES -->
+    <action>Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100%</action>
+    <action>Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features</action>
+    <action>Validate that ALL acceptance criteria related to this task are satisfied</action>
+    <action>Run full test suite to ensure NO regressions introduced</action>
+
+    <!-- REVIEW FOLLOW-UP HANDLING -->
+    <check if="task is review follow-up (has [AI-Review] prefix)">
+      <action>Extract review item details (severity, description, related AC/file)</action>
+      <action>Load all items from "Senior Developer Review (AI) → Action Items" as candidate list {{review_action_items}}</action>
+      <action>Set {{task_text_norm}} = normalize(current review follow-up task description)</action>
+      <action>Initialize {{best_match}} = null, {{best_score}} = 0, {{best_shared_tokens}} = 0, {{tie_candidates}} = []</action>
+      <action>For each candidate action item:
+        1. Set {{candidate_text_norm}} = normalize(candidate text)
+        2. If {{task_text_norm}} == {{candidate_text_norm}} OR either contains the other:
+           - set {{candidate_score}} = 1.0 and mark as strong match
+        3. Else:
+           - compute Jaccard score = |token_set(task) ∩ token_set(candidate)| / |token_set(task) ∪ token_set(candidate)|
+           - set {{candidate_score}} to computed score
+        4. Track shared-token count for tie-breaking
+        5. Keep highest score candidate; if same score, keep candidate with more shared tokens
+        6. If score and shared-token count both tie, add candidate to {{tie_candidates}}
+      </action>
+      <action>Set {{match_found}} = true only if {{best_score}} >= {{review_match_threshold}}</action>
+
+      <!-- Mark task in Review Follow-ups section (always, regardless of action-item match result) -->
+      <action>Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section</action>
+
+      <check if="{{match_found}} == true">
+        <action>Mark matched action item checkbox [x] in "Senior Developer Review (AI) → Action Items"</action>
+        <action>Append structured entry to {{resolved_review_items}}:
+          - task: current review follow-up task
+          - matched_action_item: {{best_match}}
+          - match_score: {{best_score}}
+          - resolved_at: {{date}}
+          - status: "matched"
+        </action>
+        <check if="{{tie_candidates}} is not empty">
+          <action>Log ambiguity warning with tied candidates and selected best_match</action>
+        </check>
+        <action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}} (matched action item, score {{best_score}})"</action>
+      </check>
+
+      <check if="{{match_found}} == false">
+        <action>Log warning: no candidate met threshold {{review_match_threshold}} for task "{{task_text_norm}}"</action>
+        <action>Append structured entry to {{resolved_review_items}}:
+          - task: current review follow-up task
+          - matched_action_item: null
+          - match_score: {{best_score}}
+          - resolved_at: {{date}}
+          - status: "unmatched"
+        </action>
+        <action>Append structured entry to {{unresolved_review_items}}:
+          - task: current review follow-up task
+          - reason: "No corresponding action item met fuzzy-match threshold"
+          - best_candidate: {{best_match}}
+          - best_score: {{best_score}}
+          - recorded_at: {{date}}
+        </action>
+        <action>Add resolution note in Dev Agent Record that no corresponding action item was found, while follow-up checkbox was still marked complete</action>
+      </check>
+    </check>
+
+    <!-- ONLY MARK COMPLETE IF ALL VALIDATION PASS -->
+    <check if="ALL validation gates pass AND tests ACTUALLY exist and pass">
+      <action>ONLY THEN mark the task (and subtasks) checkbox with [x]</action>
+      <action>Update File List section with ALL new, modified, or deleted files (paths relative to repo root)</action>
+      <action>Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested</action>
+    </check>
+
+    <check if="ANY validation fails">
+      <action>DO NOT mark task complete - fix issues first</action>
+      <action>If unable to fix validation failures, invoke HALT protocol from dev-story/workflow.md with:
+        - reason_code: DEV-STORY-STEP-08-VALIDATION-FAIL
+        - step_id: step-08-mark-task-complete
+        - message: "Task completion validation failed and remediation was unsuccessful."
+        - required_action: "Fix failing validations/tests, then resume."
+      </action>
+    </check>
+
+    <check if="review_continuation == true and {{resolved_review_items}} is not empty">
+      <action>Set {{resolved_count}} = length({{resolved_review_items}})</action>
+      <action>Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"</action>
+    </check>
+
+    <action>Save the story file</action>
+    <action>Determine if more incomplete tasks remain</action>
+    <action if="more tasks remain">
+      <goto step="5">Next task</goto>
+    </action>
+    <action if="no tasks remain">
+      <goto step="9">Completion</goto>
+    </action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-09-mark-review-ready.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md

@@ -0,0 +1,67 @@
+---
+name: 'step-09-mark-review-ready'
+description: 'Finalize story, enforce definition-of-done, and set review status'
+nextStepFile: './step-10-closeout.md'
+---
+
+  <step n="9" goal="Story completion and mark for review" tag="sprint-status">
+    <action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
+    <action>Run the full regression suite (do not skip)</action>
+    <action>Confirm File List includes every changed file</action>
+    <action>Execute enhanced definition-of-done validation</action>
+    <action>Update the story Status to: "review"</action>
+    <action>Initialize sprint tracking state deterministically before any sprint-status check:
+      - Set {{current_sprint_status}} = "no-sprint-tracking"
+      - Set {{sprint_tracking_enabled}} = false
+      - If {sprint_status} exists and is readable:
+        - Load the FULL file: {sprint_status}
+        - If file content indicates tracking disabled OR development_status section is missing, keep "no-sprint-tracking"
+        - Else set {{current_sprint_status}} = "enabled" and {{sprint_tracking_enabled}} = true
+      - If file missing/unreadable, keep defaults and continue with story-only status update
+    </action>
+
+    <!-- Enhanced Definition of Done Validation -->
+    <action>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
+    </action>
+
+    <!-- Mark story ready for review - sprint status conditional -->
+    <check if="{{sprint_tracking_enabled}} == true">
+      <action>Find development_status key matching {{story_key}}</action>
+      <check if="story key found in sprint status">
+        <action>Verify current status is "in-progress" (expected previous state)</action>
+        <action>Update development_status[{{story_key}}] = "review"</action>
+        <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+        <output>✅ Story status updated to "review" in sprint-status.yaml</output>
+      </check>
+      <check if="story key not found in sprint status">
+        <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
+
+          Story status is set to "review" in file, but sprint-status.yaml may be out of sync.
+        </output>
+      </check>
+    </check>
+
+    <check if="{{sprint_tracking_enabled}} == false">
+      <output>ℹ️ Story status updated to "review" in story file (no sprint tracking configured)</output>
+    </check>
+
+    <!-- Final validation gates -->
+    <action if="any task is incomplete">Invoke HALT protocol (reason_code: DEV-STORY-STEP-09-INCOMPLETE-TASKS, step_id: step-09-mark-review-ready, message: "Incomplete tasks remain before review-ready transition.", required_action: "Complete all tasks/subtasks and rerun validations.")</action>
+    <action if="regression failures exist">Invoke HALT protocol (reason_code: DEV-STORY-STEP-09-REGRESSION-FAIL, step_id: step-09-mark-review-ready, message: "Regression suite has failures.", required_action: "Fix failing tests and rerun full regression suite.")</action>
+    <action if="File List is incomplete">Invoke HALT protocol (reason_code: DEV-STORY-STEP-09-FILE-LIST-INCOMPLETE, step_id: step-09-mark-review-ready, message: "File List does not include all changed files.", required_action: "Update File List with all added/modified/deleted paths.")</action>
+    <action if="definition-of-done validation fails">Invoke HALT protocol (reason_code: DEV-STORY-STEP-09-DOD-FAIL, step_id: step-09-mark-review-ready, message: "Definition-of-done checks failed.", required_action: "Address DoD failures and rerun validation.")</action>
+  </step>
+
+## Next
+- Read fully and follow: `./step-10-closeout.md`.

src/bmm/workflows/4-implementation/dev-story/steps/step-10-closeout.md

@@ -0,0 +1,41 @@
+---
+name: 'step-10-closeout'
+description: 'Summarize completion, answer user questions, and recommend next steps'
+---
+
+  <step n="10" goal="Completion communication and user support">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md</invoke-task>
+    <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
+
+    <action>Communicate to {user_name} that story implementation is complete and ready for review</action>
+    <action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
+    <action>Provide the story file path and current status (now "review")</action>
+
+    <action>Based on {user_skill_level}, ask if user needs any explanations about:
+      - What was implemented and how it works
+      - Why certain technical decisions were made
+      - How to test or verify the changes
+      - Any patterns, libraries, or approaches used
+      - Anything else they'd like clarified
+    </action>
+
+    <check if="user asks for explanations">
+      <action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
+      <action>Use examples and references to specific code when helpful</action>
+    </check>
+
+    <action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
+    <action>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
+    </action>
+
+    <output>💡 **Tip:** For best results, run `code-review` using a **different** LLM than the one that implemented this story.</output>
+    <check if="{sprint_status} file exists">
+      <action>Suggest checking {sprint_status} to see project progress</action>
+    </check>
+    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
+  </step>

src/bmm/workflows/4-implementation/dev-story/workflow.md

@@ -0,0 +1,80 @@
+---
+name: dev-story
+description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria"
+projectRoot: '{project-root}'
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+---
+
+# Dev Story Workflow
+
+## Goal
+Implement a ready story end-to-end with strict validation gates, accurate progress tracking, and high-quality test coverage.
+
+## Workflow Architecture
+- Uses step-file execution to keep context focused and deterministic.
+- Read one step file fully, execute it, then move to the next step file.
+- Do not pre-load future step files.
+
+## Initialization
+- Resolve `projectRoot`:
+  - Prefer `{project-root}` when provided by runtime.
+  - If unavailable, resolve repo root from current working directory (locate-repo-root helper / process cwd) and set `projectRoot`.
+  - Validate that `{projectRoot}/_bmad/bmm/config.yaml` exists and is readable before continuing.
+- Load config from `{projectRoot}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`
+  - `communication_language`
+  - `document_output_language`
+  - `user_skill_level`
+  - `implementation_artifacts`
+  - `story_dir` = `{implementation_artifacts}`
+  - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+  - `story_file` (if provided)
+  - `project_context` = `**/project-context.md`
+  - `date` (system-generated)
+  - `installed_path` = `{projectRoot}/_bmad/bmm/workflows/4-implementation/dev-story`
+
+## Critical Rules
+- Communicate in `{communication_language}` and tailor explanations to `{user_skill_level}`.
+- Generate any documents in `{document_output_language}`.
+- Only update allowed story sections:
+  - Tasks/Subtasks checkboxes
+  - Dev Agent Record (Debug Log, Completion Notes)
+  - File List
+  - Change Log
+  - Status
+- Execute steps in order and do not skip validation gates.
+- Continue until the story is complete unless the HALT protocol below is triggered.
+
+## HALT Protocol (Normative)
+- Scope:
+  - Every `HALT` instruction in this workflow and all `steps/*.md` files MUST use this protocol.
+- Operational definition:
+  - HALT is a deterministic hard-stop event raised when execution cannot safely continue.
+  - A HALT event MUST include:
+    - `reason_code` (stable machine-readable code)
+    - `step_id` (current step file + step number)
+    - `message` (human-readable failure summary)
+    - `required_action` (what user/operator must do before resume)
+- Trigger criteria:
+  - Required inputs/files are missing, unreadable, or malformed.
+  - Validation gates fail and cannot be remediated in the current step.
+  - Test/regression failures persist after attempted fixes.
+  - Story state is inconsistent (for example malformed task structure preventing safe updates).
+- HALT behavior:
+  - Stop execution immediately and skip all downstream steps.
+  - Persist workflow checkpoint: current step id, resolved variables, and pending task context.
+  - Persist only already-applied safe edits; do not apply new partial completion marks after HALT.
+  - Emit logger event exactly in this format:
+    - `HALT[{reason_code}] step={step_id} story={story_key|unknown} detail=\"{message}\"`
+  - Emit user-facing prompt exactly in this format:
+    - `Workflow HALTED at {step_id} ({reason_code}): {message}. Required action: {required_action}. Reply RESUME after remediation.`
+- Resume semantics:
+  - Manual resume only (no automatic retry loop).
+  - Resume is checkpoint-based: restart from the halted step after user confirms remediation.
+  - Re-run the failed validation/input check before executing further actions.
+  - If the same HALT condition repeats, stop again with updated evidence.
+
+## Execution
+Read fully and follow: `steps/step-01-find-story.md`.

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

@@ -1,23 +0,0 @@
-name: dev-story
-description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria"
-author: "BMad"
-
-# Critical variables from config
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
-user_name: "{config_source}:user_name"
-communication_language: "{config_source}:communication_language"
-user_skill_level: "{config_source}:user_skill_level"
-document_output_language: "{config_source}:document_output_language"
-story_dir: "{config_source}:implementation_artifacts"
-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"

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

@@ -1,7 +1,7 @@
 # Retrospective - Epic Completion Review Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.md</critical>
 <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>

src/bmm/workflows/4-implementation/retrospective/workflow.md

@@ -0,0 +1,56 @@
+---
+name: retrospective
+description: "Run after epic completion to review overall success, extract lessons learned, and surface impact on upcoming work"
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+agent_manifest: '{project-root}/_bmad/_config/agent-manifest.csv'
+input_file_patterns:
+  epics:
+    description: "The completed epic for retrospective"
+    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"
+  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: "{planning_artifacts}/*architecture*.md"
+    sharded: "{planning_artifacts}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  prd:
+    description: "Product requirements for context"
+    whole: "{planning_artifacts}/*prd*.md"
+    sharded: "{planning_artifacts}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{planning_artifacts}/*.md"
+    load_strategy: "INDEX_GUIDED"
+---
+
+## Initialization
+- Load config from `{project-root}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`
+  - `communication_language`
+  - `document_output_language`
+  - `user_skill_level`
+  - `planning_artifacts`
+  - `implementation_artifacts`
+  - `agent_manifest` = `{project-root}/_bmad/_config/agent-manifest.csv`
+  - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml`
+  - `story_directory` = `{implementation_artifacts}`
+  - `retrospectives_folder` = `{implementation_artifacts}`
+  - `date` (system-generated)
+  - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/retrospective`
+
+<workflow>
+  <critical>Communicate all responses in {communication_language} and generate all documents in {document_output_language}</critical>
+
+  <step n="1" goal="Run retrospective">
+    <action>Read and follow instructions at: {installed_path}/instructions.md</action>
+  </step>
+</workflow>

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

@@ -1,55 +0,0 @@
-# Retrospective - Epic Completion Review Workflow
-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"
-output_folder: "{config_source}:implementation_artifacts}"
-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"
-
-installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective"
-template: false
-instructions: "{installed_path}/instructions.md"
-
-required_inputs:
-  - 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: "{planning_artifacts}/*epic*.md"
-    sharded_index: "{planning_artifacts}/*epic*/index.md"
-    sharded_single: "{planning_artifacts}/*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: "{planning_artifacts}/*architecture*.md"
-    sharded: "{planning_artifacts}/*architecture*/*.md"
-    load_strategy: "FULL_LOAD"
-  prd:
-    description: "Product requirements for context"
-    whole: "{planning_artifacts}/*prd*.md"
-    sharded: "{planning_artifacts}/*prd*/*.md"
-    load_strategy: "FULL_LOAD"
-  document_project:
-    description: "Brownfield project documentation (optional)"
-    sharded: "{planning_artifacts}/*.md"
-    load_strategy: "INDEX_GUIDED"
-
-# Required files
-sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
-story_directory: "{implementation_artifacts}"
-retrospectives_folder: "{implementation_artifacts}"

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

@@ -1,7 +1,7 @@
 # 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.md</critical>
+<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md</critical>
 
 ## 📚 Document Discovery - Full Epic Loading
 

src/bmm/workflows/4-implementation/sprint-planning/workflow.md

@@ -0,0 +1,41 @@
+---
+name: sprint-planning
+description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle"
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+epics_location: "{planning_artifacts}"
+epics_pattern: "epic*.md"
+input_file_patterns:
+  epics:
+    description: "All epics with user stories"
+    whole: "{epics_location}/{epics_pattern}"
+    sharded: "{epics_location}/epic*/*.md"
+    load_strategy: "FULL_LOAD"
+---
+
+## Initialization
+- Load config from `{project-root}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`
+  - `communication_language`
+  - `implementation_artifacts`
+  - `planning_artifacts`
+  - `project_name`
+  - `date` (system-generated)
+  - `epics_location` = `{planning_artifacts}`
+  - `epics_pattern` = `epic*.md`
+  - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning`
+  - `status_file` = `{implementation_artifacts}/sprint-status.yaml`
+  - `default_output_file` = `{status_file}`
+
+<workflow>
+  <critical>Communicate all responses in {communication_language}</critical>
+
+  <step n="1" goal="Plan sprint tracking file">
+    <action>Read and follow instructions at: {installed_path}/instructions.md</action>
+  </step>
+
+  <step n="2" goal="Validate sprint status output">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md</invoke-task>
+  </step>
+</workflow>

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

@@ -1,51 +0,0 @@
-name: sprint-planning
-description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle"
-author: "BMad"
-
-# Critical variables from config
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-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"
-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"
-
-  # Tracking system configuration
-  tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
-  project_key: "NOKEY" # Placeholder for tracker integrations; file-system uses a no-op key
-  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: "{planning_artifacts}" # Directory containing epic*.md files
-  epics_pattern: "epic*.md" # Pattern to find epic files
-
-  # Output configuration
-  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}"

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

@@ -1,7 +1,7 @@
 # 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>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-status/workflow.md</critical>
 <critical>Modes: interactive (default), validate, data</critical>
 <critical>⚠️ ABSOLUTELY NO TIME ESTIMATES. Do NOT mention hours, days, weeks, or timelines.</critical>
 

src/bmm/workflows/4-implementation/sprint-status/workflow.md

@@ -0,0 +1,26 @@
+---
+name: sprint-status
+description: "Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow"
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+---
+
+## Initialization
+- Load config from `{project-root}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`
+  - `communication_language`
+  - `document_output_language`
+  - `implementation_artifacts`
+  - `planning_artifacts`
+  - `date` (system-generated)
+  - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml`
+  - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/sprint-status`
+
+<workflow>
+  <critical>Communicate all responses in {communication_language} and generate all documents in {document_output_language}</critical>
+
+  <step n="1" goal="Summarize sprint progress and route next action">
+    <action>Read and follow instructions at: {installed_path}/instructions.md</action>
+  </step>
+</workflow>

src/bmm/workflows/4-implementation/sprint-status/workflow.yaml

@@ -1,30 +0,0 @@
-# Sprint Status - Implementation Tracker
-name: sprint-status
-description: "Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow."
-author: "BMad"
-
-# Critical variables from config
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
-user_name: "{config_source}:user_name"
-communication_language: "{config_source}:communication_language"
-document_output_language: "{config_source}:document_output_language"
-date: system-generated
-implementation_artifacts: "{config_source}:implementation_artifacts"
-planning_artifacts: "{config_source}:planning_artifacts"
-
-# Workflow components
-installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-status"
-instructions: "{installed_path}/instructions.md"
-
-# Inputs
-variables:
-  sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
-  tracking_system: "file-system"
-
-# Smart input file references
-input_file_patterns:
-  sprint_status:
-    description: "Sprint status file generated by sprint-planning"
-    whole: "{implementation_artifacts}/sprint-status.yaml"
-    load_strategy: "FULL_LOAD"

src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

@@ -41,7 +41,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 - `quick_spec_workflow` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md`
 - `party_mode_exec` = `{project-root}/_bmad/core/workflows/party-mode/workflow.md`
-- `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml`
+- `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md`
 
 ---
 

src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md

@@ -4,7 +4,7 @@ description: Conversational spec engineering - ask questions, investigate code,
 main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 # Checkpoint handler paths
-advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
 party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 quick_dev_workflow: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md'
 ---

src/bmm/workflows/document-project/instructions.md

@@ -1,7 +1,7 @@
 # Document Project Workflow Router
 
-<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/document-project/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/document-project/workflow.md</critical>
 <critical>Communicate all responses in {communication_language}</critical>
 
 <workflow>
@@ -10,13 +10,45 @@
 
 <step n="1" goal="Validate workflow and get project info">
 
-<invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
+<action>Initialize status defaults:
+  - Set status_exists = false
+  - Set status_file_found = false
+  - Set standalone_mode = true
+  - Set warning = ""
+  - Set status_load_error_reason = ""
+  - Set suggestion = ""
+  - Set next_workflow = ""
+  - Set next_agent = ""
+  - Set status_file_path = ""
+  - Set field_type = ""
+  - Set workflow_mode = ""
+  - Set scan_level = ""
+  - Set subworkflow_success = false
+  - Set status_update_success = false
+  - Set cached_project_types = ""
+</action>
+
+<action>Attempt to load workflow status directly from `{output_folder}/bmm-workflow-status.yaml`:
+  - If file exists, is readable, and parses correctly:
+    - Set status_exists = true
+    - Set status_file_found = true
+    - Set standalone_mode = false
+    - Set status_file_path = `{output_folder}/bmm-workflow-status.yaml`
+    - Extract field_type, warning, suggestion, next_workflow, next_agent if present
+  - If file is missing, unreadable, or malformed:
+    - Keep defaults and continue in standalone mode
+    - Set status_load_error_reason from the caught file/parse error (e.g., missing file, permission denied, YAML parse error)
+    - Set warning = "Unable to load workflow status from {output_folder}/bmm-workflow-status.yaml: {{status_load_error_reason}}"
+    - Output warning and continue in standalone mode
+</action>
 
 <check if="status_exists == false">
+  <check if="suggestion != ''">
     <output>{{suggestion}}</output>
+  </check>
+  <check if="warning != ''">
+    <output>{{warning}}</output>
+  </check>
   <output>Note: Documentation workflow can run standalone. Continuing without progress tracking.</output>
   <action>Set standalone_mode = true</action>
   <action>Set status_file_found = false</action>
@@ -35,18 +67,20 @@
     </check>
   </check>
 
-  <!-- Now validate sequencing -->
-  <invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-    <param>mode: validate</param>
-    <param>calling_workflow: document-project</param>
-  </invoke-workflow>
+  <!-- Validate sequencing from loaded status fields -->
+  <action>Validate sequencing locally from loaded status fields:
+    - If warning is empty, continue
+    - If warning contains guidance, require explicit user confirmation before continuing
+  </action>
 
   <check if="warning != ''">
     <output>{{warning}}</output>
     <output>Note: This may be auto-invoked by prd for brownfield documentation.</output>
     <ask>Continue with documentation? (y/n)</ask>
     <check if="n">
+      <check if="suggestion != ''">
         <output>{{suggestion}}</output>
+      </check>
       <action>Exit workflow</action>
     </check>
   </check>
@@ -58,11 +92,44 @@
 <critical>SMART LOADING STRATEGY: Check state file FIRST before loading any CSV files</critical>
 
 <action>Check for existing state file at: {output_folder}/project-scan-report.json</action>
+<action>Set resume_mode = false</action>
 
 <check if="project-scan-report.json exists">
   <action>Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification</action>
+  <action>Validate last_updated from state file:
+    - If last_updated is missing or invalid, set state_age_hours = 999 and mark state as stale
+    - Otherwise parse last_updated into validated_last_updated
+  </action>
   <action>Extract cached project_type_id(s) from state file if present</action>
-  <action>Calculate age of state file (current time - last_updated)</action>
+  <action>Calculate state_age_hours:
+    - If validated_last_updated exists, compute current time - validated_last_updated
+    - Otherwise keep state_age_hours = 999
+  </action>
+
+<check if="state_age_hours >= 24">
+  <action>Display: "Found old state file (>24 hours). Starting fresh scan."</action>
+  <action>Attempt to create archive directory: {output_folder}/.archive/</action>
+  <check if="archive directory creation failed">
+    <output>Failed to create archive directory at {output_folder}/.archive/. Keeping existing state and exiting to avoid data loss.</output>
+    <action>Set resume_mode = true</action>
+    <action>Exit workflow</action>
+  </check>
+  <action>Attempt to archive old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+  <check if="archive move failed">
+    <output>Failed to archive old state file. Keeping existing state and exiting to avoid data loss.</output>
+    <action>Set resume_mode = true</action>
+    <action>Exit workflow</action>
+  </check>
+  <action>Set resume_mode = false</action>
+  <action>Set workflow_mode = ""</action>
+  <action>Set scan_level = ""</action>
+  <action>Set cached_project_types = ""</action>
+  <action>Set current_step = ""</action>
+  <action>Set subworkflow_success = false</action>
+  <action>Continue to Step 3</action>
+</check>
+
+<check if="state_age_hours < 24">
 
 <ask>I found an in-progress workflow state from {{last_updated}}.
 
@@ -85,32 +152,72 @@ Your choice [1/2/3]:
 
   <check if="user selects 1">
     <action>Set resume_mode = true</action>
-    <action>Set workflow_mode = {{mode}}</action>
+    <action>Validate persisted mode before assigning workflow_mode:
+      - If mode is one of [deep_dive, initial_scan, full_rescan], set workflow_mode = {{mode}}
+      - Otherwise set workflow_mode = "full_rescan", set resume_mode = false, and continue as fresh scan
+    </action>
+    <action>Set subworkflow_success = false</action>
     <action>Load findings summaries from state file</action>
     <action>Load cached project_type_id(s) from state file</action>
 
     <critical>CONDITIONAL CSV LOADING FOR RESUME:</critical>
+    <check if="cached_project_types == ''">
+      <output>No cached project types found. Falling back to full CSV load.</output>
+      <action>Load project-types.csv and architecture_registry.csv</action>
+      <action>Load documentation_requirements_csv for active project classification</action>
+    </check>
+    <check if="cached_project_types != ''">
     <action>For each cached project_type_id, load ONLY the corresponding row from: {documentation_requirements_csv}</action>
     <action>Skip loading project-types.csv and architecture_registry.csv (not needed on resume)</action>
     <action>Store loaded doc requirements for use in remaining steps</action>
+    </check>
 
     <action>Display: "Resuming {{workflow_mode}} from {{current_step}} with cached project type(s): {{cached_project_types}}"</action>
 
     <check if="workflow_mode == deep_dive">
       <action>Read fully and follow: {installed_path}/workflows/deep-dive-instructions.md with resume context</action>
+      <action>Set subworkflow_success = true only if delegated workflow completed without HALT/error</action>
+      <check if="subworkflow_success != true">
+        <output>Sub-workflow failed or was aborted during resume deep-dive mode. Exiting without marking completion.</output>
+        <action>Exit workflow</action>
+      </check>
+      <action>After sub-workflow completes, continue to Step 4</action>
     </check>
 
     <check if="workflow_mode == initial_scan OR workflow_mode == full_rescan">
       <action>Read fully and follow: {installed_path}/workflows/full-scan-instructions.md with resume context</action>
+      <action>Set subworkflow_success = true only if delegated workflow completed without HALT/error</action>
+      <check if="subworkflow_success != true">
+        <output>Sub-workflow failed or was aborted during resume full-scan mode. Exiting without marking completion.</output>
+        <action>Exit workflow</action>
+      </check>
+      <action>After sub-workflow completes, continue to Step 4</action>
+    </check>
+
+    <check if="workflow_mode != deep_dive AND workflow_mode != initial_scan AND workflow_mode != full_rescan">
+      <output>Invalid resume workflow mode '{{workflow_mode}}'. Exiting without marking completion.</output>
+      <action>Exit workflow</action>
     </check>
 
   </check>
 
   <check if="user selects 2">
-    <action>Create archive directory: {output_folder}/.archive/</action>
-    <action>Move old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Attempt to create archive directory: {output_folder}/.archive/</action>
+    <check if="archive directory creation failed">
+      <output>Failed to create archive directory. Keeping existing state and exiting to avoid data loss.</output>
+      <action>Set resume_mode = true</action>
+      <action>Exit workflow</action>
+    </check>
+    <action>Attempt to move old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <check if="archive move failed">
+      <output>Failed to archive old state file. Keeping existing state and exiting to avoid data loss.</output>
+      <action>Set resume_mode = true</action>
+      <action>Exit workflow</action>
+    </check>
     <action>Set resume_mode = false</action>
-    <action>Continue to Step 0.5</action>
+    <action>Reset workflow_mode, scan_level, cached_project_types, current_step to defaults</action>
+    <action>Set subworkflow_success = false</action>
+    <action>Continue to Step 3</action>
   </check>
 
   <check if="user selects 3">
@@ -118,11 +225,17 @@ Your choice [1/2/3]:
     <action>Exit workflow</action>
   </check>
 
-  <check if="state file age >= 24 hours">
-    <action>Display: "Found old state file (>24 hours). Starting fresh scan."</action>
-    <action>Archive old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+  <check if="user input is not 1, 2, or 3">
+    <output>Invalid selection. Expected 1, 2, or 3. Exiting workflow without changes.</output>
+    <action>Exit workflow</action>
+  </check>
+
+</check>
+</check>
+
+<check if="project-scan-report.json does not exist">
   <action>Set resume_mode = false</action>
-    <action>Continue to Step 0.5</action>
+  <action>Continue to Step 3</action>
 </check>
 
 </step>
@@ -147,8 +260,14 @@ Your choice [1/2/3]:
 
   <check if="user selects 1">
     <action>Set workflow_mode = "full_rescan"</action>
+    <action>Set scan_level = "standard"</action>
     <action>Display: "Starting full project rescan..."</action>
     <action>Read fully and follow: {installed_path}/workflows/full-scan-instructions.md</action>
+    <action>Set subworkflow_success = true only if delegated workflow completed without HALT/error</action>
+    <check if="subworkflow_success != true">
+      <output>Sub-workflow failed or was aborted during full rescan. Exiting without marking completion.</output>
+      <action>Exit workflow</action>
+    </check>
     <action>After sub-workflow completes, continue to Step 4</action>
   </check>
 
@@ -157,6 +276,11 @@ Your choice [1/2/3]:
     <action>Set scan_level = "exhaustive"</action>
     <action>Display: "Starting deep-dive documentation mode..."</action>
     <action>Read fully and follow: {installed_path}/workflows/deep-dive-instructions.md</action>
+    <action>Set subworkflow_success = true only if delegated workflow completed without HALT/error</action>
+    <check if="subworkflow_success != true">
+      <output>Sub-workflow failed or was aborted during deep-dive mode. Exiting without marking completion.</output>
+      <action>Exit workflow</action>
+    </check>
     <action>After sub-workflow completes, continue to Step 4</action>
   </check>
 
@@ -164,12 +288,23 @@ Your choice [1/2/3]:
     <action>Display message: "Keeping existing documentation. Exiting workflow."</action>
     <action>Exit workflow</action>
   </check>
+
+  <check if="user input is not 1, 2, or 3">
+    <output>Invalid selection. Expected 1, 2, or 3. Exiting workflow without changes.</output>
+    <action>Exit workflow</action>
+  </check>
 </check>
 
 <check if="index.md does not exist">
   <action>Set workflow_mode = "initial_scan"</action>
+  <action>Set scan_level = "initial"</action>
   <action>Display: "No existing documentation found. Starting initial project scan..."</action>
   <action>Read fully and follow: {installed_path}/workflows/full-scan-instructions.md</action>
+  <action>Set subworkflow_success = true only if delegated workflow completed without HALT/error</action>
+  <check if="subworkflow_success != true">
+    <output>Sub-workflow failed or was aborted during initial scan. Exiting without marking completion.</output>
+    <action>Exit workflow</action>
+  </check>
   <action>After sub-workflow completes, continue to Step 4</action>
 </check>
 
@@ -177,16 +312,25 @@ Your choice [1/2/3]:
 
 <step n="4" goal="Update status and complete">
 
-<check if="status_file_found == true">
-  <invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: document-project</param>
-  </invoke-workflow>
+<check if="resume_mode == true AND subworkflow_success != true">
+  <output>Resume flow did not complete a delegated sub-workflow successfully. Exiting without completion update.</output>
+  <action>Exit workflow</action>
+</check>
 
-  <check if="success == true">
+<check if="status_file_found == true">
+  <action>Attempt status update in {{status_file_path}}:
+    - Mark workflow `document-project` as completed
+    - Persist updated timestamp and completion metadata
+    - Set status_update_success = true on success
+    - If write fails, set status_update_success = false and capture status_update_error
+  </action>
+
+  <check if="status_update_success == true">
     <output>Status updated!</output>
   </check>
+  <check if="status_update_success != true">
+    <output>⚠️ Status update skipped: {{status_update_error}}</output>
+  </check>
 </check>
 
 <output>**✅ Document Project Workflow Complete, {user_name}!**
@@ -196,26 +340,27 @@ Your choice [1/2/3]:
 - Mode: {{workflow_mode}}
 - Scan Level: {{scan_level}}
 - Output: {output_folder}/index.md and related files
-
-{{#if status_file_found}}
-**Status Updated:**
-
-- Progress tracking updated
-
-**Next Steps:**
-
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
-
-Check status anytime with: `workflow-status`
-{{else}}
-**Next Steps:**
-Since no workflow is in progress:
-
-- Refer to the BMM workflow guide if unsure what to do next
-- Or run `workflow-init` to create a workflow path and get guided next steps
-  {{/if}}
 </output>
 
+<check if="status_file_found == true AND status_update_success == true">
+  <output>**Status Updated:** Progress tracking updated.
+
+**Next Steps:**
+- Run `bmad-help` if you need recommended next workflows.</output>
+  <check if="next_workflow != '' AND next_agent != ''">
+    <output>- **Next required:** {{next_workflow}} ({{next_agent}} agent)</output>
+  </check>
+  <check if="next_workflow == '' OR next_agent == ''">
+    <output>- **Next required:** not specified</output>
+  </check>
+</check>
+
+<check if="status_file_found == false OR status_update_success != true">
+  <output>**Next Steps:**
+- Refer to the BMM workflow guide if unsure what to do next
+- Run `bmad-help` to get guided workflow recommendations</output>
+</check>
+
 </step>
 
 </workflow>

src/bmm/workflows/document-project/workflow.md

@@ -0,0 +1,30 @@
+---
+name: document-project
+description: "Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development"
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: false
+---
+
+## Initialization
+- Load config from `{project-root}/_bmad/bmm/config.yaml`.
+- Resolve variables:
+  - `user_name`
+  - `communication_language`
+  - `document_output_language`
+  - `user_skill_level`
+  - `project_knowledge`
+  - `date` (system-generated)
+  - `installed_path` = `{project-root}/_bmad/bmm/workflows/document-project`
+  - `documentation_requirements_csv` = `{installed_path}/documentation-requirements.csv`
+
+<workflow>
+  <critical>Communicate all responses in {communication_language} and generate all documents in {document_output_language}</critical>
+
+  <step n="1" goal="Document existing project">
+    <action>Read and follow instructions at: {installed_path}/instructions.md</action>
+  </step>
+
+  <step n="2" goal="Validate outputs">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md</invoke-task>
+  </step>
+</workflow>

src/bmm/workflows/document-project/workflow.yaml

@@ -1,22 +0,0 @@
-# Document Project Workflow Configuration
-name: "document-project"
-version: "1.2.0"
-description: "Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development"
-author: "BMad"
-
-# Critical variables
-config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:project_knowledge"
-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
-
-# Module path and component files
-installed_path: "{project-root}/_bmad/bmm/workflows/document-project"
-instructions: "{installed_path}/instructions.md"
-validation: "{installed_path}/checklist.md"
-
-# Required data files - CRITICAL for project type detection and documentation requirements
-documentation_requirements_csv: "{installed_path}/documentation-requirements.csv"

src/bmm/workflows/document-project/workflows/deep-dive.yaml

@@ -3,11 +3,11 @@ name: "document-project-deep-dive"
 description: "Exhaustive deep-dive documentation of specific project areas"
 author: "BMad"
 
-# This is a sub-workflow called by document-project/workflow.yaml
-parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml"
+# This is a sub-workflow called by document-project/workflow.md
+parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md"
 
 # Critical variables inherited from parent
-config_source: "{project-root}/_bmad/bmb/config.yaml"
+config_source: "{project-root}/_bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 date: system-generated

src/bmm/workflows/document-project/workflows/full-scan.yaml

@@ -3,11 +3,11 @@ name: "document-project-full-scan"
 description: "Complete project documentation workflow (initial scan or full rescan)"
 author: "BMad"
 
-# This is a sub-workflow called by document-project/workflow.yaml
-parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml"
+# This is a sub-workflow called by document-project/workflow.md
+parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md"
 
 # Critical variables inherited from parent
-config_source: "{project-root}/_bmad/bmb/config.yaml"
+config_source: "{project-root}/_bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 date: system-generated