ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v4-v6 upgrade improvement and warning about file auto backup

Browse Source
This commit is contained in:
Brian Madison
2025-09-30 19:42:12 -05:00
parent df0c3e4bae
commit e7fcc56cc3
314 changed files with 38192 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
bmad/bmm/workflows/4-implementation/correct-course/checklist.md Normal file
View File

@@ -0,0 +1,279 @@
# Change Navigation Checklist
<critical>This checklist is executed as part of: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
<critical>Work through each section systematically with the user, recording findings and impacts</critical>
<checklist>
<section n="1" title="Understand the Trigger and Context">
<check-item id="1.1">
<prompt>Identify the triggering story that revealed this issue</prompt>
<action>Document story ID and brief description</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="1.2">
<prompt>Define the core problem precisely</prompt>
<action>Categorize issue type:</action>
- Technical limitation discovered during implementation
- New requirement emerged from stakeholders
- Misunderstanding of original requirements
- Strategic pivot or market change
- Failed approach requiring different solution
<action>Write clear problem statement</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="1.3">
<prompt>Assess initial impact and gather supporting evidence</prompt>
<action>Collect concrete examples, error messages, stakeholder feedback, or technical constraints</action>
<action>Document evidence for later reference</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<halt-condition>
<check>If trigger is unclear: "Cannot proceed without understanding what caused the need for change"</check>
<check>If no evidence provided: "Need concrete evidence or examples of the issue before analyzing impact"</check>
</halt-condition>
</section>
<section n="2" title="Epic Impact Assessment">
<check-item id="2.1">
<prompt>Evaluate current epic containing the trigger story</prompt>
<action>Can this epic still be completed as originally planned?</action>
<action>If no, what modifications are needed?</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="2.2">
<prompt>Determine required epic-level changes</prompt>
<action>Check each scenario:</action>
- Modify existing epic scope or acceptance criteria
- Add new epic to address the issue
- Remove or defer epic that's no longer viable
- Completely redefine epic based on new understanding
<action>Document specific epic changes needed</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="2.3">
<prompt>Review all remaining planned epics for required changes</prompt>
<action>Check each future epic for impact</action>
<action>Identify dependencies that may be affected</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="2.4">
<prompt>Check if issue invalidates future epics or necessitates new ones</prompt>
<action>Does this change make any planned epics obsolete?</action>
<action>Are new epics needed to address gaps created by this change?</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="2.5">
<prompt>Consider if epic order or priority should change</prompt>
<action>Should epics be resequenced based on this issue?</action>
<action>Do priorities need adjustment?</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
</section>
<section n="3" title="Artifact Conflict and Impact Analysis">
<check-item id="3.1">
<prompt>Check PRD for conflicts</prompt>
<action>Does issue conflict with core PRD goals or objectives?</action>
<action>Do requirements need modification, addition, or removal?</action>
<action>Is the defined MVP still achievable or does scope need adjustment?</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="3.2">
<prompt>Review Architecture document for conflicts</prompt>
<action>Check each area for impact:</action>
- System components and their interactions
- Architectural patterns and design decisions
- Technology stack choices
- Data models and schemas
- API designs and contracts
- Integration points
<action>Document specific architecture sections requiring updates</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="3.3">
<prompt>Examine UI/UX specifications for conflicts</prompt>
<action>Check for impact on:</action>
- User interface components
- User flows and journeys
- Wireframes or mockups
- Interaction patterns
- Accessibility considerations
<action>Note specific UI/UX sections needing revision</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="3.4">
<prompt>Consider impact on other artifacts</prompt>
<action>Review additional artifacts for impact:</action>
- Deployment scripts
- Infrastructure as Code (IaC)
- Monitoring and observability setup
- Testing strategies
- Documentation
- CI/CD pipelines
<action>Document any secondary artifacts requiring updates</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
</section>
<section n="4" title="Path Forward Evaluation">
<check-item id="4.1">
<prompt>Evaluate Option 1: Direct Adjustment</prompt>
<action>Can the issue be addressed by modifying existing stories?</action>
<action>Can new stories be added within the current epic structure?</action>
<action>Would this approach maintain project timeline and scope?</action>
<action>Effort estimate: [High/Medium/Low]</action>
<action>Risk level: [High/Medium/Low]</action>
<status>[ ] Viable / [ ] Not viable</status>
</check-item>
<check-item id="4.2">
<prompt>Evaluate Option 2: Potential Rollback</prompt>
<action>Would reverting recently completed stories simplify addressing this issue?</action>
<action>Which stories would need to be rolled back?</action>
<action>Is the rollback effort justified by the simplification gained?</action>
<action>Effort estimate: [High/Medium/Low]</action>
<action>Risk level: [High/Medium/Low]</action>
<status>[ ] Viable / [ ] Not viable</status>
</check-item>
<check-item id="4.3">
<prompt>Evaluate Option 3: PRD MVP Review</prompt>
<action>Is the original PRD MVP still achievable with this issue?</action>
<action>Does MVP scope need to be reduced or redefined?</action>
<action>Do core goals need modification based on new constraints?</action>
<action>What would be deferred to post-MVP if scope is reduced?</action>
<action>Effort estimate: [High/Medium/Low]</action>
<action>Risk level: [High/Medium/Low]</action>
<status>[ ] Viable / [ ] Not viable</status>
</check-item>
<check-item id="4.4">
<prompt>Select recommended path forward</prompt>
<action>Based on analysis of all options, choose the best path</action>
<action>Provide clear rationale considering:</action>
- Implementation effort and timeline impact
- Technical risk and complexity
- Impact on team morale and momentum
- Long-term sustainability and maintainability
- Stakeholder expectations and business value
<action>Selected approach: [Option 1 / Option 2 / Option 3 / Hybrid]</action>
<action>Justification: [Document reasoning]</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
</section>
<section n="5" title="Sprint Change Proposal Components">
<check-item id="5.1">
<prompt>Create identified issue summary</prompt>
<action>Write clear, concise problem statement</action>
<action>Include context about discovery and impact</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="5.2">
<prompt>Document epic impact and artifact adjustment needs</prompt>
<action>Summarize findings from Epic Impact Assessment (Section 2)</action>
<action>Summarize findings from Artifact Conflict Analysis (Section 3)</action>
<action>Be specific about what changes are needed and why</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="5.3">
<prompt>Present recommended path forward with rationale</prompt>
<action>Include selected approach from Section 4</action>
<action>Provide complete justification for recommendation</action>
<action>Address trade-offs and alternatives considered</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="5.4">
<prompt>Define PRD MVP impact and high-level action plan</prompt>
<action>State clearly if MVP is affected</action>
<action>Outline major action items needed for implementation</action>
<action>Identify dependencies and sequencing</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="5.5">
<prompt>Establish agent handoff plan</prompt>
<action>Identify which roles/agents will execute the changes:</action>
- Development team (for implementation)
- Product Owner / Scrum Master (for backlog changes)
- Product Manager / Architect (for strategic changes)
<action>Define responsibilities for each role</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
</section>
<section n="6" title="Final Review and Handoff">
<check-item id="6.1">
<prompt>Review checklist completion</prompt>
<action>Verify all applicable sections have been addressed</action>
<action>Confirm all [Action-needed] items have been documented</action>
<action>Ensure analysis is comprehensive and actionable</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="6.2">
<prompt>Verify Sprint Change Proposal accuracy</prompt>
<action>Review complete proposal for consistency and clarity</action>
<action>Ensure all recommendations are well-supported by analysis</action>
<action>Check that proposal is actionable and specific</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="6.3">
<prompt>Obtain explicit user approval</prompt>
<action>Present complete proposal to user</action>
<action>Get clear yes/no approval for proceeding</action>
<action>Document approval and any conditions</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<check-item id="6.4">
<prompt>Confirm next steps and handoff plan</prompt>
<action>Review handoff responsibilities with user</action>
<action>Ensure all stakeholders understand their roles</action>
<action>Confirm timeline and success criteria</action>
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
</check-item>
<halt-condition>
<check>If any critical section cannot be completed: "Cannot proceed to proposal without complete impact analysis"</check>
<check>If user approval not obtained: "Must have explicit approval before implementing changes"</check>
<check>If handoff responsibilities unclear: "Must clearly define who will execute the proposed changes"</check>
</halt-condition>
</section>
</checklist>
<execution-notes>
<note>This checklist is for SIGNIFICANT changes affecting project direction</note>
<note>Work interactively with user - they make final decisions</note>
<note>Be factual, not blame-oriented when analyzing issues</note>
<note>Handle changes professionally as opportunities to improve the project</note>
<note>Maintain conversation context throughout - this is collaborative work</note>
</execution-notes>

190
bmad/bmm/workflows/4-implementation/correct-course/instructions.md Normal file
View File

@@ -0,0 +1,190 @@
# Correct Course - Sprint Change Management Instructions
<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.yaml</critical>
<workflow>
<step n="1" goal="Initialize Change Navigation">
<action>Confirm change trigger and gather user description of the issue</action>
<action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
<action>Verify access to required project documents:</action>
- PRD (Product Requirements Document)
- Current Epics and Stories
- Architecture documentation
- UI/UX specifications
<action>Ask user for mode preference:</action>
- **Incremental** (recommended): Refine each edit collaboratively
- **Batch**: Present all changes at once for review
<action>Store mode selection for use throughout workflow</action>
<check>If change trigger is unclear:</check>
<action>HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
<check>If core documents are unavailable:</check>
<action>HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
</step>
<step n="2" goal="Execute Change Analysis Checklist">
<action>Load and execute the systematic analysis from: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/checklist.md</action>
<action>Work through each checklist section interactively with the user</action>
<action>Record status for each checklist item:</action>
- [x] Done - Item completed successfully
- [N/A] Skip - Item not applicable to this change
- [!] Action-needed - Item requires attention or follow-up
<action>Maintain running notes of findings and impacts discovered</action>
<action>Present checklist progress after each major section</action>
<check>If checklist cannot be completed:</check>
<action>Identify blocking issues and work with user to resolve before continuing</action>
</step>
<step n="3" goal="Draft Specific Change Proposals">
<action>Based on checklist findings, create explicit edit proposals for each identified artifact</action>
<action>For Story changes:</action>
- Show old → new text format
- Include story ID and section being modified
- Provide rationale for each change
- Example format:
```
Story: [STORY-123] User Authentication
Section: Acceptance Criteria
OLD:
- User can log in with email/password
NEW:
- User can log in with email/password
- User can enable 2FA via authenticator app
Rationale: Security requirement identified during implementation
```
<action>For PRD modifications:</action>
- Specify exact sections to update
- Show current content and proposed changes
- Explain impact on MVP scope and requirements
<action>For Architecture changes:</action>
- Identify affected components, patterns, or technology choices
- Describe diagram updates needed
- Note any ripple effects on other components
<action>For UI/UX specification updates:</action>
- Reference specific screens or components
- Show wireframe or flow changes needed
- Connect changes to user experience impact
<check>If mode is Incremental:</check>
<action>Present each edit proposal individually</action>
<ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
<action>Iterate on each proposal based on user feedback</action>
<check>If mode is Batch:</check>
<action>Collect all edit proposals and present together at end of step</action>
</step>
<step n="4" goal="Generate Sprint Change Proposal">
<action>Compile comprehensive Sprint Change Proposal document with following sections:</action>
<action>Section 1: Issue Summary</action>
- Clear problem statement describing what triggered the change
- Context about when/how the issue was discovered
- Evidence or examples demonstrating the issue
<action>Section 2: Impact Analysis</action>
- Epic Impact: Which epics are affected and how
- Story Impact: Current and future stories requiring changes
- Artifact Conflicts: PRD, Architecture, UI/UX documents needing updates
- Technical Impact: Code, infrastructure, or deployment implications
<action>Section 3: Recommended Approach</action>
- Present chosen path forward from checklist evaluation:
- Direct Adjustment: Modify/add stories within existing plan
- Potential Rollback: Revert completed work to simplify resolution
- MVP Review: Reduce scope or modify goals
- Provide clear rationale for recommendation
- Include effort estimate, risk assessment, and timeline impact
<action>Section 4: Detailed Change Proposals</action>
- Include all refined edit proposals from Step 3
- Group by artifact type (Stories, PRD, Architecture, UI/UX)
- Ensure each change includes before/after and justification
<action>Section 5: Implementation Handoff</action>
- Categorize change scope:
- Minor: Direct implementation by dev team
- Moderate: Backlog reorganization needed (PO/SM)
- Major: Fundamental replan required (PM/Architect)
- Specify handoff recipients and their responsibilities
- Define success criteria for implementation
<action>Present complete Sprint Change Proposal to user</action>
<ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
</step>
<step n="5" goal="Finalize and Route for Implementation">
<action>Get explicit user approval for complete proposal</action>
<ask>Do you approve this Sprint Change Proposal for implementation? (yes/no/revise)</ask>
<check>If no or revise:</check>
<action>Gather specific feedback on what needs adjustment</action>
<action>Return to appropriate step to address concerns</action>
<goto step="3">If changes needed to edit proposals</goto>
<goto step="4">If changes needed to overall proposal structure</goto>
<check>If yes:</check>
<action>Finalize Sprint Change Proposal document</action>
<action>Determine change scope classification:</action>
- **Minor**: Can be implemented directly by development team
- **Moderate**: Requires backlog reorganization and PO/SM coordination
- **Major**: Needs fundamental replan with PM/Architect involvement
<action>Provide appropriate handoff based on scope:</action>
<check>If Minor scope:</check>
<action>Route to: Development team for direct implementation</action>
<action>Deliverables: Finalized edit proposals and implementation tasks</action>
<check>If Moderate scope:</check>
<action>Route to: Product Owner / Scrum Master agents</action>
<action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
<check>If Major scope:</check>
<action>Route to: Product Manager / Solution Architect</action>
<action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
<action>Confirm handoff completion and next steps with user</action>
<action>Document handoff in workflow execution log</action>
</step>
<step n="6" goal="Workflow Completion">
<action>Summarize workflow execution:</action>
- Issue addressed: {{change_trigger}}
- Change scope: {{scope_classification}}
- Artifacts modified: {{list_of_artifacts}}
- Routed to: {{handoff_recipients}}
<action>Confirm all deliverables produced:</action>
- Sprint Change Proposal document
- Specific edit proposals with before/after
- Implementation handoff plan
<action>Report workflow completion to user</action>
<action>Remind user of success criteria and next steps for implementation team</action>
</step>
</workflow>

35
bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml Normal file
View File

@@ -0,0 +1,35 @@
# 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"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
date: system-generated
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
template: false
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
mode: interactive
required_inputs:
- change_trigger: "Description of the issue or change that triggered this workflow"
- project_documents: "Access to PRD, Epics/Stories, Architecture, UI/UX specs"
output_artifacts:
- sprint_change_proposal: "Comprehensive proposal documenting issue, impact, and recommended changes"
- artifact_edits: "Specific before/after edits for affected documents"
- handoff_plan: "Clear routing for implementation based on change scope"
halt_conditions:
- "Change trigger unclear or undefined"
- "Core project documents unavailable"
- "Impact analysis incomplete"
- "User approval not obtained"
execution_modes:
- incremental: "Recommended - Refine each edit with user collaboration"
- batch: "Present all changes at once for review"

42
bmad/bmm/workflows/4-implementation/create-story/README.md Normal file
View File

@@ -0,0 +1,42 @@
# Create Story
## Purpose
Generate the next user story from epics/PRD and architecture context into your configured stories directory using a consistent structure.
## Highlights
- Auto-detects next story id based on existing files
- Pulls ACs from `epics.md` (or PRD) when available
- Saves to `{dev_story_location}` from `bmad/bmm/config.yaml`
- Optional: immediately runs Story Context workflow for the new story
- Spec-compliant with core workflow engine at `bmad/core/tasks/workflow.md`
- Defaults to non-interactive `#yolo` mode; only asks when strictly necessary
- Safeguard: Will NOT create a new story unless epics.md explicitly enumerates it; otherwise halts and instructs to run PM/SM `*correct-course`
## Invoke
- By path: `workflow {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml`
## Variables
- `story_dir`: from config `dev_story_location`
- `epics_file`: default `{output_folder}/epics.md`
- `prd_file`: default `{output_folder}/prd.md`
- `hla_file`: default `{output_folder}/high-level-architecture.md`
- `auto_run_context`: default `true`
- `tech_spec_file`: auto-discovered in `{project-root}/docs` with pattern `tech-spec-epic-<epic_num>-*.md` (latest by modified time)
- `execution_mode`: `#yolo` by default to minimize prompts
- `arch_docs_search_dirs`: `docs/` and `output_folder` are searched for architecture docs
- `arch_docs_file_names`: includes `tech-stack.md`, `unified-project-structure.md`, `coding-standards.md`, `testing-strategy.md`, `backend-architecture.md`, `frontend-architecture.md`, `data-models.md`, `database-schema.md`, `rest-api-spec.md`, `external-apis.md`
## Output
- New story markdown: `{story_dir}/story-<epic_num>.<story_num>.md`
- Status: `Draft`
- Guardrail: If `epics.md` lacks the next story under the current epic, the workflow halts with: "No planned next story found in epics.md for epic <epic_num>. Please load either PM (Product Manager) agent at `{project-root}/bmad/bmm/agents/pm.md` or SM (Scrum Master) agent at `{project-root}/bmad/bmm/agents/sm.md` and run `*correct-course` to add/modify epic stories, then rerun create-story."
## After Creation
- Approve the story when ready (Status → Approved)
- Then run the Dev agent `*develop` command (uses the Dev Story workflow)

39
bmad/bmm/workflows/4-implementation/create-story/checklist.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: 'Create Story Checklist'
validation-target: 'Newly generated story markdown file'
required-inputs:
- 'epics.md (preferred) or PRD'
optional-inputs:
- 'HLA document for architecture context'
validation-rules:
- 'Story structure matches sections: Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Change Log, Dev Agent Record'
- 'Dev Notes include Project Structure Notes and References subsections'
- 'All non-trivial technical notes include a source citation'
- 'Tasks include explicit testing subtasks based on testing strategy'
---
# Create Story Checklist
## Document Structure
- [ ] Title includes story id and title
- [ ] Status set to Draft
- [ ] Story section present with As a / I want / so that
- [ ] Acceptance Criteria is a numbered list
- [ ] Tasks/Subtasks present with checkboxes
- [ ] Dev Notes includes architecture/testing context
- [ ] Change Log table initialized
- [ ] Dev Agent Record sections present (Context Reference, Agent Model Used, Debug Log References, Completion Notes, File List)
## Content Quality
- [ ] Acceptance Criteria sourced from epics/PRD (or explicitly confirmed by user)
- [ ] Tasks reference AC numbers where applicable
- [ ] Dev Notes do not invent details; cite sources where possible
- [ ] File saved to stories directory from config (dev_story_location)
- [ ] If creating a new story number, epics.md explicitly enumerates this story under the target epic; otherwise generation HALTED with instruction to run PM/SM `*correct-course` (open `{project-root}/bmad/bmm/agents/pm.md` or `{project-root}/bmad/bmm/agents/sm.md` and execute `*correct-course`)
## Optional Post-Generation
- [ ] Story Context generation run (if auto_run_context)
- [ ] Context Reference recorded in story

81
bmad/bmm/workflows/4-implementation/create-story/instructions.md Normal file
View File

@@ -0,0 +1,81 @@
# Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
```xml
<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.yaml</critical>
<critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
<critical>Default execution mode: #yolo (minimal prompts). Only elicit if absolutely required and {{non_interactive}} == false.</critical>
<workflow>
<step n="1" goal="Load config and initialize">
<action>Resolve variables from config_source: story_dir (dev_story_location), output_folder, user_name, communication_language. If story_dir missing and {{non_interactive}} == false → ASK user to provide a stories directory and update variable. If {{non_interactive}} == true and missing, HALT with a clear message.</action>
<action>Create {{story_dir}} if it does not exist</action>
<action>Resolve installed component paths from workflow.yaml: template, instructions, validation</action>
<action>Resolve recommended inputs if present: epics_file, prd_file, hla_file</action>
</step>
<step n="2" goal="Discover and load source documents">
<action>If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time.</action>
<action>Build a prioritized document set for this epic:
1) tech_spec_file (epic-scoped)
2) epics_file (acceptance criteria and breakdown)
3) prd_file (business requirements and constraints)
4) hla_file (architecture constraints)
5) Architecture docs under docs/ and output_folder/: tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md, backend-architecture.md, frontend-architecture.md, data-models.md, database-schema.md, rest-api-spec.md, external-apis.md (include if present)
</action>
<action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
</step>
<step n="3" goal="Determine target story (do not prompt in #yolo)">
<action>List existing story markdown files in {{story_dir}} matching pattern: "story-<epic>.<story>.md"</action>
<check>If none found → Set {{epic_num}}=1 and {{story_num}}=1</check>
<check>If files found → Parse epic_num and story_num; pick the highest pair</check>
<action>Open the latest story (if exists) and read Status</action>
<check>If Status != Done/Approved and {{non_interactive}} == true → TARGET the latest story for update (do not create a new one)</check>
<check>If Status == Done/Approved → Candidate next story is {{epic_num}}.{{story_num+1}}</check>
<action>If creating a new story candidate: VERIFY planning in {{epics_file}}. Confirm that epic {{epic_num}} explicitly enumerates a next story matching {{story_num+1}} (or an equivalent next planned story entry). If epics.md is missing or does not enumerate another story for this epic, HALT with message:</action>
<action>"No planned next story found in epics.md for epic {{epic_num}}. Please load either PM (Product Manager) agent at {project-root}/bmad/bmm/agents/pm.md or SM (Scrum Master) agent at {project-root}/bmad/bmm/agents/sm.md and run `*correct-course` to add/modify epic stories, then rerun create-story."</action>
<check>If verification passes → Set {{story_num}} = {{story_num}} + 1</check>
<ask optional="true" if="{{non_interactive}} == false">If starting a new epic and {{non_interactive}} == false, ASK for {{epic_num}} and reset {{story_num}} to 1. In {{non_interactive}} == true, do NOT auto-advance epic; stay within current epic and continue incrementing story_num.</ask>
</step>
<step n="4" goal="Extract requirements and derive story statement">
<action>From tech_spec_file (preferred) or epics_file: extract epic {{epic_num}} title/summary, acceptance criteria for the next story, and any component references. If not present, fall back to PRD sections mapping to this epic/story.</action>
<action>From hla and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
<action>Derive a clear user story statement (role, action, benefit) grounded strictly in the above sources. If ambiguous and {{non_interactive}} == false → ASK user to clarify. If {{non_interactive}} == true → generate the best grounded statement WITHOUT inventing domain facts.</action>
<template-output file="{default_output_file}">requirements_context_summary</template-output>
</step>
<step n="5" goal="Project structure alignment and lessons learned">
<action>If a previous story exists, scan its "Dev Agent Record" for completion notes and known deviations; summarize any carry-overs relevant to this story.</action>
<action>If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts.</action>
<template-output file="{default_output_file}">structure_alignment_summary</template-output>
</step>
<step n="6" goal="Assemble acceptance criteria and tasks">
<action>Assemble acceptance criteria list from tech_spec or epics. If gaps exist, derive minimal, testable criteria from PRD verbatim phrasing (NO invention).</action>
<action>Create tasks/subtasks directly mapped to ACs. Include explicit testing subtasks per testing-strategy and existing tests framework. Cite architecture/source documents for any technical mandates.</action>
<template-output file="{default_output_file}">acceptance_criteria</template-output>
<template-output file="{default_output_file}">tasks_subtasks</template-output>
</step>
<step n="7" goal="Create or update story document">
<action>Resolve output path: {default_output_file} using current {{epic_num}} and {{story_num}}. If targeting an existing story for update, use its path.</action>
<action>Initialize from template.md if creating a new file; otherwise load existing file for edit.</action>
<action>Compute a concise story_title from epic/story context; if missing, synthesize from PRD feature name and epic number.</action>
<template-output file="{default_output_file}">story_header</template-output>
<template-output file="{default_output_file}">story_body</template-output>
<template-output file="{default_output_file}">dev_notes_with_citations</template-output>
<template-output file="{default_output_file}">change_log</template-output>
</step>
<step n="8" goal="Validate, save, and optionally generate context">
<invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.md</invoke-task>
<action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
<check>If {{auto_run_context}} == true → <invoke-workflow path="{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml">Pass {{story_path}} = {default_output_file}</invoke-workflow></check>
<action>Report created/updated story path</action>
</step>
</workflow>
```

57
bmad/bmm/workflows/4-implementation/create-story/template.md Normal file
View File

@@ -0,0 +1,57 @@
# Story {{epic_num}}.{{story_num}}: {{story_title}}
Status: Draft
## Story
As a {{role}},
I want {{action}},
so that {{benefit}}.
## Acceptance Criteria
1. [Add acceptance criteria from epics/PRD]
## Tasks / Subtasks
- [ ] Task 1 (AC: #)
- [ ] Subtask 1.1
- [ ] Task 2 (AC: #)
- [ ] Subtask 2.1
## Dev Notes
- Relevant architecture patterns and constraints
- Source tree components to touch
- Testing standards summary
### Project Structure Notes
- Alignment with unified project structure (paths, modules, naming)
- Detected conflicts or variances (with rationale)
### References
- Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
## Change Log
| Date | Version | Description | Author |
| -------- | ------- | ------------- | ------------- |
| {{date}} | 0.1 | Initial draft | {{user_name}} |
## Dev Agent Record
### Context Reference
<!-- Path(s) to story context XML/JSON will be added here by context workflow -->
### Agent Model Used
{{agent_model_name_version}}
### Debug Log References
### Completion Notes List
### File List

72
bmad/bmm/workflows/4-implementation/create-story/workflow.yaml Normal file
View File

@@ -0,0 +1,72 @@
name: create-story
description: "Create the next user story markdown from epics/PRD and architecture, using a standard template and saving to the stories folder"
author: "BMad"
# Critical variables from config
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
date: system-generated
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/create-story"
template: "{installed_path}/template.md"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# Variables and inputs
variables:
story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
prd_file: "{output_folder}/prd.md" # Fallback for requirements
hla_file: "{output_folder}/high-level-architecture.md" # Optional architecture context
tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
tech_spec_search_dir: "{project-root}/docs"
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
arch_docs_search_dirs: |
- "{project-root}/docs"
- "{output_folder}"
arch_docs_file_names: |
- tech-stack.md
- unified-project-structure.md
- coding-standards.md
- testing-strategy.md
- backend-architecture.md
- frontend-architecture.md
- data-models.md
- database-schema.md
- rest-api-spec.md
- external-apis.md
story_title: "" # Will be elicited if not derivable
epic_num: 1
story_num: 1
auto_run_context: true # Optionally run story-context after creation
non_interactive: true # Generate without elicitation; avoid interactive prompts
# Output configuration
default_output_file: "{story_dir}/story-{{epic_num}}.{{story_num}}.md"
required_tools:
- list_files
- file_info
- read_file
- write_file
- create_directory
- search_repo
- glob
recommended_inputs:
- epics: "Epic breakdown (epic-list.md)"
- prd: "PRD document"
- hla: "High-Level Architecture (optional)"
tags:
- story-generation
- planning
- bmad-v6
execution_hints:
interactive: false
autonomous: true
iterative: true

84
bmad/bmm/workflows/4-implementation/dev-story/README.md Normal file
View File

@@ -0,0 +1,84 @@
# Dev Story
## Purpose
Execute a single user story end-to-end: select the next incomplete task, implement it following repo standards, write tests, run validations, and update the story file — all in a v6 action workflow.
## Key Features
- Auto-discovers recent stories from config `dev_story_location`
- Presents a selectable list of latest stories
- Iterates task-by-task until the story is complete
- Enforces acceptance criteria and test coverage
- Restricts edits to approved sections of the story file
## How to Invoke
- By workflow name (if your runner supports it):
- `workflow dev-story`
- By path:
- `workflow {project-root}/bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml`
## Inputs and Variables
- `story_path` (optional): Explicit path to a story markdown file. If omitted, the workflow will auto-discover stories.
- `run_tests_command` (optional, default: `auto`): Command used to run tests. When `auto`, the runner should infer (e.g., `npm test`, `pnpm test`, `yarn test`, `pytest`, `go test`, etc.).
- `strict` (default: `true`): If `true`, halt on validation or test failures.
- `story_dir` (from config): Resolved from `{project-root}/bmad/bmm/config.yaml` key `dev_story_location`.
- `story_selection_limit` (default: `10`): Number of recent stories to show when selecting.
## Config
Ensure your BMM config defines the stories directory:
```yaml
# bmad/bmm/config.yaml
output_folder: ./outputs
user_name: Your Name
communication_language: en
# Directory where story markdown files live
dev_story_location: ./docs/stories
```
## Workflow Summary
1. Load story and select next task
- Use `story_path` if provided; otherwise list most recent stories from `dev_story_location`
- Parse Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Status
- Pick the first incomplete task
2. Plan and implement
- Log brief plan in Dev Agent Record → Debug Log
- Implement task and subtasks, handle edge cases
3. Write tests
- Add unit, integration, and E2E (as applicable)
4. Run validations and tests
- Run existing tests for regressions + new tests
- Lint/quality checks if configured; ensure ACs met
5. Mark task complete and update story
- Check [x] on task(s), update File List, add Completion Notes and Change Log
- Repeat from step 1 if tasks remain
6. Completion sequence
- Verify all tasks done, run full regression suite, update Status → "Ready for Review"
7. Validation and handoff (optional)
- Optionally run validation and finalize notes
## Allowed Story File Modifications
Only these sections may be changed by this workflow:
- Tasks/Subtasks checkboxes
- Dev Agent Record (Debug Log, Completion Notes)
- File List
- Change Log
- Status
## Files in This Workflow
- `workflow.yaml` — configuration and variables
- `instructions.md` — execution logic and steps
- `checklist.md` — validation checklist for completion
## Related Workflows
- `story-context` — Build dev context for a single story
- `story-context-batch` — Process multiple stories and update status

38
bmad/bmm/workflows/4-implementation/dev-story/checklist.md Normal file
View File

@@ -0,0 +1,38 @@
---
title: 'Dev Story Completion Checklist'
validation-target: 'Story markdown ({{story_path}})'
required-inputs:
- 'Story markdown file with Tasks/Subtasks, Acceptance Criteria'
optional-inputs:
- 'Test results output (if saved)'
- 'CI logs (if applicable)'
validation-rules:
- 'Only permitted sections in story were modified: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status'
---
# Dev Story Completion Checklist
## Tasks Completion
- [ ] All tasks and subtasks for this story are marked complete with [x]
- [ ] Implementation aligns with every Acceptance Criterion in the story
## Tests and Quality
- [ ] Unit tests added/updated for core functionality changed by this story
- [ ] Integration tests added/updated when component interactions are affected
- [ ] End-to-end tests created for critical user flows, if applicable
- [ ] All tests pass locally (no regressions introduced)
- [ ] Linting and static checks (if configured) pass
## Story File Updates
- [ ] File List section includes every new/modified/deleted file (paths relative to repo root)
- [ ] Dev Agent Record contains relevant Debug Log and/or Completion Notes for this work
- [ ] Change Log includes a brief summary of what changed
- [ ] Only permitted sections of the story file were modified
## Final Status
- [ ] Regression suite executed successfully
- [ ] Story Status is set to "Ready for Review"

87
bmad/bmm/workflows/4-implementation/dev-story/instructions.md Normal file
View File

@@ -0,0 +1,87 @@
# Develop Story - Workflow Instructions
```xml
<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.yaml</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>If {{run_until_complete}} == true, run non-interactively: do not pause between steps unless a HALT condition is reached or explicit user approval is required for unapproved dependencies.</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) or a HALT condition is triggered.</critical>
<critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
<workflow>
<step n="1" goal="Load story and select next task">
<action>If {{story_path}} was explicitly provided and is valid → use it. Otherwise, attempt auto-discovery.</action>
<action>Auto-discovery: Read {{story_dir}} from config (dev_story_location). If invalid/missing or contains no .md files, ASK user to provide either: (a) a story file path, or (b) a directory to scan.</action>
<action>If a directory is provided, list story markdown files recursively under that directory matching pattern: "story-*.md".</action>
<action>Sort candidates by last modified time (newest first) and take the top {{story_selection_limit}} items.</action>
<ask>Present the list with index, filename, and modified time. Ask: "Select a story (1-{{story_selection_limit}}) or enter a path:"</ask>
<action>Resolve the selected item into {{story_path}}</action>
<action>Read the COMPLETE story file from {{story_path}}</action>
<action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks (including subtasks), Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
<action>Identify the first incomplete task (unchecked [ ]) in Tasks/Subtasks; if subtasks exist, treat all subtasks as part of the selected task scope</action>
<check>If no incomplete tasks found → "All tasks completed - proceed to completion sequence" and <goto step="6">Continue</goto></check>
<check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
<check>If task requirements ambiguous → ASK user to clarify; if unresolved, HALT: "Task requirements must be clear before implementation"</check>
</step>
<step n="2" goal="Plan and implement task">
<action>Review acceptance criteria and dev notes for the selected task</action>
<action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
<action>Implement the task COMPLETELY including all subtasks, following architecture patterns and coding standards in this repo</action>
<action>Handle error conditions and edge cases appropriately</action>
<check>If unapproved dependencies are needed → ASK user for approval before adding</check>
<check>If 3 consecutive implementation failures occur → HALT and request guidance</check>
<check>If required configuration is missing → HALT: "Cannot proceed without necessary configuration files"</check>
<check>If {{run_until_complete}} == true → Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</check>
<check>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</check>
</step>
<step n="3" 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 where applicable</action>
<action>Include end-to-end tests for critical user flows if applicable</action>
<action>Cover edge cases and error handling scenarios noted in the plan</action>
</step>
<step n="4" goal="Run validations and tests">
<action>Determine how to run tests for this repo (infer or use {{run_tests_command}} if provided)</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</action>
<action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
<check>If regression tests fail → STOP and fix before continuing</check>
<check>If new tests fail → STOP and fix before continuing</check>
</step>
<step n="5" goal="Mark task complete and update story">
<action>ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds</action>
<action>Update File List section with any new, modified, or deleted files (paths relative to repo root)</action>
<action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
<action>Append a brief entry to Change Log describing the change</action>
<action>Save the story file</action>
<check>Determine if more incomplete tasks remain</check>
<check>If more tasks remain → <goto step="1">Next task</goto></check>
<check>If no tasks remain → <goto step="6">Completion</goto></check>
</step>
<step n="6" goal="Story completion sequence">
<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 story definition-of-done checklist, if the story includes one</action>
<action>Update the story Status to: Ready for Review</action>
<check>If any task is incomplete → Return to step 1 to complete remaining work (Do NOT finish with partial progress)</check>
<check>If regression failures exist → STOP and resolve before completing</check>
<check>If File List is incomplete → Update it before completing</check>
</step>
<step n="7" goal="Validation and handoff" optional="true">
<action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.md</action>
<action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
<action>Communicate that the story is Ready for Review</action>
</step>
</workflow>
```

53
bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml Normal file
View File

@@ -0,0 +1,53 @@
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"
date: system-generated
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/dev-story"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# This is an action workflow (no output template document)
template: false
# Variables (can be provided by caller)
variables:
story_path: ""
run_tests_command: "auto" # 'auto' = infer from repo, or override with explicit command
strict: true # if true, halt on validation failures
story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
story_selection_limit: 10
run_until_complete: true # Continue through all tasks without pausing except on HALT conditions
force_yolo: true # Hint executor to activate #yolo: skip optional prompts and elicitation
# Recommended inputs
recommended_inputs:
- story_markdown: "Path to the story markdown file (Tasks/Subtasks, Acceptance Criteria present)"
# Required tools (conceptual; executor should provide equivalents)
required_tools:
- read_file
- write_file
- search_repo
- run_tests
- list_files
- file_info
tags:
- development
- story-execution
- tests
- validation
- bmad-v6
execution_hints:
interactive: false # Minimize prompts; intended to run to completion
autonomous: true # Proceed without user input unless blocked
iterative: true

391
bmad/bmm/workflows/4-implementation/retrospective/instructions.md Normal file
View File

@@ -0,0 +1,391 @@
# Retrospective - Epic Completion Review Instructions
<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.yaml</critical>
<critical>
FACILITATION NOTES:
- Bob (Scrum Master) facilitates this retrospective
- Psychological safety is paramount - NO BLAME
- Focus on systems, processes, and learning
- Everyone contributes with specific examples preferred
- Action items must be achievable with clear ownership
- Two-part format: (1) Epic Review + (2) Next Epic Preparation
</critical>
<workflow>
<step n="1" goal="Epic Context Discovery">
<action>Identify the completed epic</action>
<ask>Which epic has just been completed? (Enter epic number, e.g., "003" or auto-detect from highest completed story)</ask>
<check>If auto-detecting:</check>
<action>Check {output_folder}/stories/ for highest numbered completed story</action>
<action>Extract epic number from story file (e.g., "Epic: 003" section)</action>
<action>Load the completed epic from: {output_folder}/prd/epic-{{epic_number}}.md</action>
<action>Extract epic details:</action>
- Epic title and goals
- Success criteria
- Planned stories and story points
- Estimated sprint duration
- Business objectives
<action>Find all stories for this epic in {output_folder}/stories/</action>
<action>For each story, extract:</action>
- Story number and title
- Completion status
- Story points (if tracked)
- Actual completion date
- Dev Agent Record notes
- TEA Results and testing outcomes
- PO Notes and acceptance
- Blockers encountered and resolution
- Technical debt incurred
<action>Calculate epic metrics:</action>
- Completed stories vs. total planned
- Actual story points delivered vs. planned
- Actual sprints taken vs. estimated
- Velocity (points per sprint)
- Blocker count and resolution time
- Technical debt items logged
<action>Review epic goals and compare actual outcomes vs. planned</action>
<action>Note any scope changes or descoped items</action>
<action>Document key architectural decisions made during epic</action>
<action>Identify technical debt incurred and why</action>
</step>
<step n="2" goal="Preview Next Epic">
<action>Identify the next epic in sequence</action>
<action>Load next epic from: {output_folder}/prd/epic-{{next_epic_number}}.md</action>
<action>Analyze next epic for:</action>
- Epic title and objectives
- Planned stories and complexity
- Dependencies on completed epic work
- New technical requirements or capabilities needed
- Potential risks or unknowns
<action>Identify dependencies on completed work:</action>
- What components from Epic {{completed_number}} does Epic {{next_number}} rely on?
- Are all prerequisites complete and stable?
- Any incomplete work that creates blocking dependencies?
<action>Note potential gaps or preparation needed:</action>
- Technical setup required (infrastructure, tools, libraries)
- Knowledge gaps to fill (research, training, spikes)
- Refactoring needed before starting next epic
- Documentation or specifications to create
<action>Check for technical prerequisites:</action>
- APIs or integrations that must be ready
- Data migrations or schema changes needed
- Testing infrastructure requirements
- Deployment or environment setup
</step>
<step n="3" goal="Initialize Retrospective with Context">
<action>Bob (Scrum Master) opens the retrospective with context</action>
<action>Present formatted retrospective header:</action>
```
🔄 TEAM RETROSPECTIVE - Epic {{epic_number}}: {{epic_title}}
Bob (Scrum Master) facilitating
═══════════════════════════════════════════════════════════
EPIC {{epic_number}} SUMMARY:
Delivery Metrics:
- Completed: {{completed_stories}}/{{total_stories}} stories ({{completion_percentage}}%)
- Velocity: {{actual_points}} story points (planned: {{planned_points}})
- Duration: {{actual_sprints}} sprints (planned: {{planned_sprints}})
- Average velocity: {{points_per_sprint}} points/sprint
Quality and Technical:
- Blockers encountered: {{blocker_count}}
- Technical debt items: {{debt_count}}
- Test coverage: {{coverage_info}}
- Production incidents: {{incident_count}}
Business Outcomes:
- Goals achieved: {{goals_met}}/{{total_goals}}
- Success criteria: {{criteria_status}}
- Stakeholder feedback: {{feedback_summary}}
═══════════════════════════════════════════════════════════
NEXT EPIC PREVIEW: Epic {{next_number}}: {{next_epic_title}}
Dependencies on Epic {{epic_number}}:
{{list_dependencies}}
Preparation Needed:
{{list_preparation_gaps}}
Technical Prerequisites:
{{list_technical_prereqs}}
═══════════════════════════════════════════════════════════
Team assembled for reflection:
{{list_agents_based_on_story_records}}
Focus Areas:
1. Learning from Epic {{epic_number}} execution
2. Preparing for Epic {{next_number}} success
```
<action>Load agent configurations from: {project-root}/bmad/\_cfg/agent-party.xml</action>
<action>Identify agents who participated in the completed epic based on story records</action>
<action>Ensure key roles present: Sarah (PO), Bob (SM), James (Dev), Murat (TEA), Winston (Architect), Mary (Analyst)</action>
</step>
<step n="4" goal="Epic Review Discussion">
<action>Bob facilitates Part 1: Reviewing the completed epic</action>
<action>Each agent shares in their unique voice, referencing actual story data</action>
<action>Maintain psychological safety - focus on learning, not blame</action>
<action>For each participating agent, present structured feedback:</action>
**{{Agent Name}} ({{Role}})**:
**What Went Well:**
- Successes from completed stories (cite specific examples)
- Effective practices or processes that worked
- Velocity achievements or quality wins
- Collaboration highlights
- Technical successes or good decisions
**What Could Improve:**
- Challenges from story records (cite specifics)
- Blockers that slowed progress and why
- Process friction or inefficiencies
- Technical debt incurred and rationale
- Communication or coordination issues
**Lessons Learned:**
- Key insights for future epics
- Patterns to repeat or avoid
- Skills or knowledge gained
- Process improvements to implement
<action>Agent personality guidance:</action>
- **Sarah (PO)**: Business value delivery, stakeholder management, requirements clarity
- **Bob (SM)**: Process effectiveness, team dynamics, blocker removal, velocity trends
- **James (Dev)**: Technical execution, code quality, development experience, tooling
- **Murat (TEA)**: Quality outcomes, testing effectiveness, defect prevention, coverage
- **Winston (Architect)**: Architectural decisions, technical strategy, long-term sustainability
- **Mary (Analyst)**: Requirements accuracy, specification quality, edge case handling
<action>Encourage specific examples from story records, metrics, and real outcomes</action>
<action>Bob synthesizes common themes as discussion progresses</action>
</step>
<step n="5" goal="Next Epic Preparation Discussion">
<action>Bob facilitates Part 2: Preparing for the next epic</action>
<action>Each agent addresses preparation needs from their domain</action>
<action>For each agent, present forward-looking analysis:</action>
**{{Agent Name}} ({{Role}})**:
**Dependencies Check:**
- What from Epic {{completed_number}} is needed for Epic {{next_number}}?
- Any incomplete work that could block us?
- Integration points or handoffs to verify?
**Preparation Needs:**
- Technical setup required before starting
- Knowledge gaps to fill (research, training, spikes)
- Refactoring or cleanup needed
- Documentation or specifications to create
- Tools or infrastructure to provision
**Risk Assessment:**
- Potential issues based on Epic {{completed_number}} experience
- Unknowns or uncertainties in Epic {{next_number}}
- Mitigation strategies to consider
- Early warning signs to watch for
<action>Focus on actionable preparation items</action>
<action>Identify dependencies between preparation tasks</action>
<action>Note any quick wins that could de-risk the next epic</action>
</step>
<step n="6" goal="Synthesize Action Items">
<action>Bob identifies patterns across all agent feedback</action>
<action>Synthesizes common themes into team agreements</action>
<action>Creates specific, achievable action items with clear ownership</action>
<action>Develops preparation sprint tasks if significant setup needed</action>
<action>Present comprehensive action plan:</action>
```
═══════════════════════════════════════════════════════════
📝 EPIC {{completed_number}} ACTION ITEMS:
Process Improvements:
1. {{action_item}} (Owner: {{agent}}, By: {{timeline}})
2. {{action_item}} (Owner: {{agent}}, By: {{timeline}})
3. {{action_item}} (Owner: {{agent}}, By: {{timeline}})
Technical Debt:
1. {{debt_item}} (Owner: {{agent}}, Priority: {{high/medium/low}})
2. {{debt_item}} (Owner: {{agent}}, Priority: {{high/medium/low}})
Documentation:
1. {{doc_need}} (Owner: {{agent}}, By: {{timeline}})
Team Agreements:
- {{agreement_1}}
- {{agreement_2}}
- {{agreement_3}}
═══════════════════════════════════════════════════════════
🚀 EPIC {{next_number}} PREPARATION SPRINT:
Technical Setup:
[ ] {{setup_task}} (Owner: {{agent}}, Est: {{hours/days}})
[ ] {{setup_task}} (Owner: {{agent}}, Est: {{hours/days}})
Knowledge Development:
[ ] {{research_task}} (Owner: {{agent}}, Est: {{hours/days}})
[ ] {{spike_task}} (Owner: {{agent}}, Est: {{hours/days}})
Cleanup/Refactoring:
[ ] {{refactor_task}} (Owner: {{agent}}, Est: {{hours/days}})
[ ] {{cleanup_task}} (Owner: {{agent}}, Est: {{hours/days}})
Documentation:
[ ] {{doc_task}} (Owner: {{agent}}, Est: {{hours/days}})
Total Estimated Effort: {{total_hours}} hours ({{total_days}} days)
═══════════════════════════════════════════════════════════
⚠️ CRITICAL PATH:
Blockers to Resolve Before Epic {{next_number}}:
1. {{critical_item}} (Owner: {{agent}}, Must complete by: {{date}})
2. {{critical_item}} (Owner: {{agent}}, Must complete by: {{date}})
Dependencies Timeline:
{{timeline_visualization_of_critical_dependencies}}
Risk Mitigation:
- {{risk}}: {{mitigation_strategy}}
- {{risk}}: {{mitigation_strategy}}
```
<action>Ensure every action item has clear owner and timeline</action>
<action>Prioritize preparation tasks by dependencies and criticality</action>
<action>Identify which tasks can run in parallel vs. sequential</action>
</step>
<step n="7" goal="Critical User Verification">
<action>Bob leads final verification checks before concluding retrospective</action>
<action>User must confirm readiness before next epic begins</action>
<ask>Let's verify Epic {{completed_number}} is truly complete. Please confirm each item:</ask>
**Testing Verification:**
<ask>Has full regression testing been completed for Epic {{completed_number}}? (yes/no/partial)</ask>
<check>If no or partial:</check>
<action>Add to Critical Path: Complete regression testing before Epic {{next_number}}</action>
**Deployment Status:**
<ask>Has Epic {{completed_number}} been deployed to production? (yes/no/scheduled)</ask>
<check>If no:</check>
<action>Add to Critical Path: Deploy Epic {{completed_number}} - scheduled for {{date}}</action>
**Business Validation:**
<ask>Have stakeholders reviewed and accepted Epic {{completed_number}} deliverables? (yes/no/pending)</ask>
<check>If no or pending:</check>
<action>Add to Critical Path: Obtain stakeholder acceptance before Epic {{next_number}}</action>
**Technical Health:**
<ask>Is the codebase in a stable, maintainable state after Epic {{completed_number}}? (yes/no/concerns)</ask>
<check>If no or concerns:</check>
<action>Document concerns: {{user_input}}</action>
<action>Add to Preparation Sprint: Address stability concerns</action>
**Blocker Resolution:**
<ask>Are there any unresolved blockers from Epic {{completed_number}} that will impact Epic {{next_number}}? (yes/no)</ask>
<check>If yes:</check>
<action>Document blockers: {{user_input}}</action>
<action>Add to Critical Path with highest priority</action>
<action>Bob summarizes verification results and any critical items added</action>
</step>
<step n="8" goal="Retrospective Closure">
<action>Bob closes the retrospective with summary and next steps</action>
<action>Present closure summary:</action>
```
═══════════════════════════════════════════════════════════
✅ RETROSPECTIVE COMPLETE
Epic {{completed_number}}: {{epic_title}} - REVIEWED
Key Takeaways:
- {{key_lesson_1}}
- {{key_lesson_2}}
- {{key_lesson_3}}
Action Items Committed: {{action_count}}
Preparation Tasks Defined: {{prep_task_count}}
Critical Path Items: {{critical_count}}
═══════════════════════════════════════════════════════════
🎯 NEXT STEPS:
1. Execute Preparation Sprint (Est: {{prep_days}} days)
2. Complete Critical Path items before Epic {{next_number}}
3. Review action items in next standup
4. Begin Epic {{next_number}} planning when preparation complete
═══════════════════════════════════════════════════════════
Bob: "Great work team! We learned a lot from Epic {{completed_number}}.
Let's use these insights to make Epic {{next_number}} even better.
See you at sprint planning once prep work is done!"
```
<action>Save retrospective summary to: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md</action>
<action>Confirm all action items have been captured</action>
<action>Remind user to schedule prep sprint if needed</action>
</step>
</workflow>
<facilitation-guidelines>
<guideline>Bob maintains psychological safety throughout - no blame or judgment</guideline>
<guideline>Focus on systems and processes, not individual performance</guideline>
<guideline>Encourage specific examples over general statements</guideline>
<guideline>Balance celebration of wins with honest assessment of challenges</guideline>
<guideline>Ensure every voice is heard - all agents contribute</guideline>
<guideline>Action items must be specific, achievable, and owned</guideline>
<guideline>Forward-looking mindset - how do we improve for next epic?</guideline>
<guideline>Two-part structure ensures both reflection AND preparation</guideline>
<guideline>Critical verification prevents starting next epic prematurely</guideline>
<guideline>Document everything - retrospective insights are valuable for future reference</guideline>
</facilitation-guidelines>

41
bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml Normal file
View File

@@ -0,0 +1,41 @@
# 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}:output_folder"
user_name: "{config_source}:user_name"
date: system-generated
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective"
template: false
instructions: "{installed_path}/instructions.md"
mode: interactive
trigger: "Run AFTER completing an epic"
required_inputs:
- completed_epic: "The epic that was just completed"
- stories_folder: "{output_folder}/stories/"
- epics_folder: "{output_folder}/prd/"
- agent_party_config: "{project-root}/bmad/_cfg/agent-party.xml"
output_artifacts:
- retrospective_summary: "Comprehensive review of what went well and what could improve"
- lessons_learned: "Key insights for future epics"
- action_items: "Specific improvements with ownership"
- next_epic_preparation: "Dependencies, gaps, and preparation tasks for next epic"
- critical_path: "Blockers or prerequisites that must be addressed"
facilitation:
facilitator: "Bob (Scrum Master)"
tone: "Psychological safety - no blame, focus on systems and processes"
format: "Two-part: (1) Review completed epic + (2) Preview next epic preparation"
validation_required:
- testing_complete: "Has full regression testing been completed?"
- deployment_status: "Has epic been deployed to production?"
- business_validation: "Have stakeholders reviewed and accepted deliverables?"
- technical_health: "Is codebase in stable, maintainable state?"
- blocker_resolution: "Any unresolved blockers that will impact next epic?"

72
bmad/bmm/workflows/4-implementation/review-story/README.md Normal file
View File

@@ -0,0 +1,72 @@
# Review Story (Senior Developer Review)
Perform an AI-driven Senior Developer Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.
## What It Does
- Auto-discovers the target story or accepts an explicit `story_path`
- Verifies the story is in a reviewable state (e.g., Ready for Review/Review)
- Loads Story Context (from Dev Agent Record → Context Reference or auto-discovery)
- Locates the epic Tech Spec and relevant architecture/standards docs
- Uses MCP servers for best-practices and security references; falls back to web search
- Reviews implementation vs Acceptance Criteria, Tech Spec, and repo standards
- Evaluates code quality, security, and test coverage
- Appends a "Senior Developer Review (AI)" section to the story with findings and action items
- Optionally updates story Status based on outcome
## How to Invoke
- By workflow name (if supported):
- `workflow review-story`
- By path:
- `workflow {project-root}/bmad/bmm/workflows/4-implementation/review-story/workflow.yaml`
## Inputs and Variables
- `story_path` (optional): Explicit path to a story file
- `story_dir` (from config): `{project-root}/bmad/bmm/config.yaml` → `dev_story_location`
- `allow_status_values`: Defaults include `Ready for Review`, `Review`
- `auto_discover_context` (default: true)
- `auto_discover_tech_spec` (default: true)
- `tech_spec_glob_template`: `tech-spec-epic-{{epic_num}}*.md`
- `arch_docs_search_dirs`: Defaults to `docs/` and `outputs/`
- `enable_mcp_doc_search` (default: true)
- `enable_web_fallback` (default: true)
- `update_status_on_result` (default: false)
## Story Updates
- Appends a section titled: `Senior Developer Review (AI)` at the end
- Adds a Change Log entry: "Senior Developer Review notes appended"
- If enabled, updates `Status` based on outcome
## Persistence and Backlog
To ensure review findings become actionable work, the workflow can persist action items to multiple targets (configurable):
- Story tasks: Inserts unchecked items under `Tasks / Subtasks` in a "Review Follow-ups (AI)" subsection so `dev-story` can pick them up next.
- Story review section: Keeps a full list under "Senior Developer Review (AI) → Action Items".
- Backlog file: Appends normalized rows to `docs/backlog.md` (created if missing) for cross-cutting or longer-term improvements.
- Epic follow-ups: If an epic Tech Spec is found, appends to its `Post-Review Follow-ups` section.
Configure via `workflow.yaml` variables:
- `persist_action_items` (default: true)
- `persist_targets`: `story_tasks`, `story_review_section`, `backlog_file`, `epic_followups`
- `backlog_file` (default: `{project-root}/docs/backlog.md`)
- `update_epic_followups` (default: true)
- `epic_followups_section_title` (default: `Post-Review Follow-ups`)
Routing guidance:
- Put must-fix items to ship the story into the story’s tasks.
- Put same-epic but non-blocking improvements into the epic Tech Spec follow-ups.
- Put cross-cutting, future, or refactor work into the backlog file.
## Related Workflows
- `dev-story` — Implements tasks/subtasks and can act on review action items
- `story-context` — Generates Story Context for a single story
- `tech-spec` — Generates epic Tech Spec documents
_Part of the BMAD Method v6 — Implementation Phase_

12
bmad/bmm/workflows/4-implementation/review-story/backlog_template.md Normal file
View File

@@ -0,0 +1,12 @@
# Engineering Backlog
This backlog collects cross-cutting or future action items that emerge from reviews and planning.
Routing guidance:
- Use this file for non-urgent optimizations, refactors, or follow-ups that span multiple stories/epics.
- Must-fix items to ship a story belong in that story’s `Tasks / Subtasks`.
- Same-epic improvements may also be captured under the epic Tech Spec `Post-Review Follow-ups` section.
| Date | Story | Epic | Type | Severity | Owner | Status | Notes |
| ---- | ----- | ---- | ---- | -------- | ----- | ------ | ----- |

22
bmad/bmm/workflows/4-implementation/review-story/checklist.md Normal file
View File

@@ -0,0 +1,22 @@
# Senior Developer Review - Validation Checklist
- [ ] Story file loaded from `{{story_path}}`
- [ ] Story Status verified as one of: {{allow_status_values}}
- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
- [ ] Story Context located or warning recorded
- [ ] Epic Tech Spec located or warning recorded
- [ ] Architecture/standards docs loaded (as available)
- [ ] Tech stack detected and documented
- [ ] MCP doc search performed (or web fallback) and references captured
- [ ] Acceptance Criteria cross-checked against implementation
- [ ] File List reviewed and validated for completeness
- [ ] Tests identified and mapped to ACs; gaps noted
- [ ] Code quality review performed on changed files
- [ ] Security review performed on changed files and dependencies
- [ ] Outcome decided (Approve/Changes Requested/Blocked)
- [ ] Review notes appended under "Senior Developer Review (AI)"
- [ ] Change Log updated with review entry
- [ ] Status updated according to settings (if enabled)
- [ ] Story saved successfully
_Reviewer: {{user_name}} on {{date}}_

176
bmad/bmm/workflows/4-implementation/review-story/instructions.md Normal file
View File

@@ -0,0 +1,176 @@
# Senior Developer Review - Workflow Instructions
```xml
<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.yaml</critical>
<critical>This workflow performs a Senior Developer Review on a story flagged Ready for Review, appends structured review notes, and can update the story status based on the outcome.</critical>
<critical>Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery of the target story fails, HALT with a clear message to provide 'story_path' or 'story_dir'.</critical>
<critical>Only modify the story file in these areas: Status (optional per settings), Dev Agent Record (Completion Notes), File List (if corrections are needed), Change Log, and the appended "Senior Developer Review (AI)" section at the end of the document.</critical>
<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
<workflow>
<step n="1" goal="Locate story and verify review status">
<action>If {{story_path}} was provided → use it. Else auto-discover from {{story_dir}} by listing files matching pattern: "story-*.md" (recursive), sort by last modified (newest first), present top {{story_selection_limit}}.</action>
<ask optional="true" if="{{non_interactive}} == false">Select a story (1-{{story_selection_limit}}) or enter a path:</ask>
<action>Resolve {{story_path}} and read the COMPLETE file.</action>
<action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available.</action>
<action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log.</action>
<check>If Status is not one of {{allow_status_values}} → HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent).</check>
<check>If story cannot be read → HALT.</check>
</step>
<step n="2" goal="Resolve context and specification inputs">
<action>Locate Story Context: Under Dev Agent Record → Context Reference, read referenced path(s). If missing and {{auto_discover_context}}: search {{output_folder}} for files named "story-context-{{epic_num}}.{{story_num}}*.xml"; pick the most recent.</action>
<check>If no context found → Continue but record a WARNING in review notes: "No Story Context found".</check>
<action>Locate Epic Tech Spec: If {{auto_discover_tech_spec}}, search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}); else use provided input.</action>
<check>If no tech spec found → Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}".</check>
<action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect any testing, coding standards, security, and architectural patterns.</action>
</step>
<step n="3" goal="Detect tech stack and establish best-practice reference set">
<action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
<action>If {{enable_mcp_doc_search}} and MCP servers are available → Use them to search for up-to-date best practices, security advisories, and framework-specific guidance relevant to the detected stack and the story's domain.</action>
<action>If MCP is unavailable or insufficient and {{enable_web_fallback}} → Perform targeted web searches and fetch authoritative references (framework docs, OWASP, language style guides). Prefer official documentation and widely-recognized standards.</action>
<action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
</step>
<step n="4" goal="Assess implementation against acceptance criteria and specs">
<action>From the story, read Acceptance Criteria and Tasks/Subtasks with their completion state.</action>
<action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
<action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
<action>For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly.</action>
<check>If critical architecture constraints are violated (e.g., layering, dependency rules) → flag as High severity finding.</check>
</step>
<step n="5" goal="Perform code quality and risk review">
<action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
<action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, unvalidated redirects, CORS misconfig, dependency vulnerabilities (based on manifests).</action>
<action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
<action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
</step>
<step n="6" goal="Decide review outcome and prepare notes">
<action>Determine outcome: Approve, Changes Requested, or Blocked.</action>
<action>Prepare a structured review report with sections: Summary, Outcome, Key Findings (by severity), Acceptance Criteria Coverage, Test Coverage and Gaps, Architectural Alignment, Security Notes, Best-Practices and References, Action Items.</action>
<action>For Action Items, use imperative phrasing and map each to related ACs or files. Include suggested owners if clear.</action>
</step>
<step n="7" goal="Append review to story and update metadata">
<action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
<action>Insert subsections:
- Reviewer: {{user_name}}
- Date: {{date}}
- Outcome: (Approve | Changes Requested | Blocked)
- Summary
- Key Findings
- Acceptance Criteria Coverage
- Test Coverage and Gaps
- Architectural Alignment
- Security Notes
- Best-Practices and References (with links)
- Action Items
</action>
<action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
<action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
<action>Save the story file.</action>
</step>
<step n="8" goal="Persist action items to tasks/backlog/epic">
<action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
<action if="{{persist_action_items}} == true and 'story_tasks' in {{persist_targets}}">
Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
</action>
<ask optional="true" if="{{non_interactive}} == false">Confirm adding follow-ups into story Tasks/Subtasks. Proceed?</ask>
<action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
</action>
<action if="{{persist_action_items}} == true and ('epic_followups' in {{persist_targets}} or {{update_epic_followups}} == true)">
If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}.
</action>
<action>Save modified files.</action>
<action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
</step>
<step n="9" goal="Validation and completion">
<invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.md</invoke-task>
<action>Report workflow completion.</action>
</step> <step n="1" goal="Locate story and verify review status">
<action>If {{story_path}} was provided → use it. Else auto-discover from {{story_dir}} by listing files matching pattern: "story-*.md" (recursive), sort by last modified (newest first), present top {{story_selection_limit}}.</action>
<ask optional="true" if="{{non_interactive}} == false">Select a story (1-{{story_selection_limit}}) or enter a path:</ask>
<action>Resolve {{story_path}} and read the COMPLETE file.</action>
<action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available.</action>
<action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log.</action>
<check>If Status is not one of {{allow_status_values}} → HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent).</check>
<check>If story cannot be read → HALT.</check>
</step>
<step n="2" goal="Resolve context and specification inputs">
<action>Locate Story Context: Under Dev Agent Record → Context Reference, read referenced path(s). If missing and {{auto_discover_context}}: search {{output_folder}} for files named "story-context-{{epic_num}}.{{story_num}}*.xml"; pick the most recent.</action>
<check>If no context found → Continue but record a WARNING in review notes: "No Story Context found".</check>
<action>Locate Epic Tech Spec: If {{auto_discover_tech_spec}}, search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}); else use provided input.</action>
<check>If no tech spec found → Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}".</check>
<action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect any testing, coding standards, security, and architectural patterns.</action>
</step>
<step n="3" goal="Detect tech stack and establish best-practice reference set">
<action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
<action>If {{enable_mcp_doc_search}} and MCP servers are available → Use them to search for up-to-date best practices, security advisories, and framework-specific guidance relevant to the detected stack and the story's domain.</action>
<action>If MCP is unavailable or insufficient and {{enable_web_fallback}} → Perform targeted web searches and fetch authoritative references (framework docs, OWASP, language style guides). Prefer official documentation and widely-recognized standards.</action>
<action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
</step>
<step n="4" goal="Assess implementation against acceptance criteria and specs">
<action>From the story, read Acceptance Criteria and Tasks/Subtasks with their completion state.</action>
<action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
<action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
<action>For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly.</action>
<check>If critical architecture constraints are violated (e.g., layering, dependency rules) → flag as High severity finding.</check>
</step>
<step n="5" goal="Perform code quality and risk review">
<action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
<action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, unvalidated redirects, CORS misconfig, dependency vulnerabilities (based on manifests).</action>
<action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
<action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
</step>
<step n="6" goal="Decide review outcome and prepare notes">
<action>Determine outcome: Approve, Changes Requested, or Blocked.</action>
<action>Prepare a structured review report with sections: Summary, Outcome, Key Findings (by severity), Acceptance Criteria Coverage, Test Coverage and Gaps, Architectural Alignment, Security Notes, Best-Practices and References, Action Items.</action>
<action>For Action Items, use imperative phrasing and map each to related ACs or files. Include suggested owners if clear.</action>
</step>
<step n="7" goal="Append review to story and update metadata">
<action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
<action>Insert subsections:
- Reviewer: {{user_name}}
- Date: {{date}}
- Outcome: (Approve | Changes Requested | Blocked)
- Summary
- Key Findings
- Acceptance Criteria Coverage
- Test Coverage and Gaps
- Architectural Alignment
- Security Notes
- Best-Practices and References (with links)
- Action Items
</action>
<action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
<action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
<action>Save the story file.</action>
</step>
<step n="8" goal="Follow-up options" optional="true">
<action>If action items are straightforward and within safety bounds, ASK whether to create corresponding unchecked items under "Tasks / Subtasks" so the `dev-story` workflow can implement them next. If approved, append them under an Action Items subsection.</action>
<action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
</step>
<step n="9" goal="Validation and completion">
<invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.md</invoke-task>
<action>Report workflow completion.</action>
</step>
</workflow>
```

99
bmad/bmm/workflows/4-implementation/review-story/workflow.yaml Normal file
View File

@@ -0,0 +1,99 @@
# Review Story Workflow
name: review-story
description: "Perform a Senior Developer Review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story."
author: "BMad"
# Critical variables from config
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
date: system-generated
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/review-story"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# This is an action workflow (no output template document)
template: false
# Variables (can be provided by caller)
variables:
story_path: "" # Explicit path to a story markdown file
story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
story_selection_limit: 10
allow_status_values: |
- Ready for Review
- Review
auto_discover_context: true
auto_discover_tech_spec: true
tech_spec_search_dir: "{project-root}/docs"
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
arch_docs_search_dirs: |
- "{project-root}/docs"
- "{output_folder}"
arch_docs_file_names: |
- prd.md
- epics.md
- high-level-architecture.md
- tech-stack.md
- unified-project-structure.md
- coding-standards.md
- testing-strategy.md
- security-guidelines.md
- backend-architecture.md
- frontend-architecture.md
- data-models.md
- database-schema.md
- rest-api-spec.md
- external-apis.md
enable_mcp_doc_search: true # Prefer enabled MCP servers for doc/best-practice lookup
enable_web_fallback: true # Fallback to web search/read-url if MCP not available
update_status_on_result: false # If true, update story Status based on review outcome
status_on_approve: "Done"
status_on_changes_requested: "InProgress"
# Persistence controls for review action items and notes
persist_action_items: true
# Valid targets: story_tasks, story_review_section, backlog_file, epic_followups
persist_targets: |
- story_review_section
- story_tasks
- backlog_file
- epic_followups
backlog_file: "{project-root}/docs/backlog.md"
update_epic_followups: true
epic_followups_section_title: "Post-Review Follow-ups"
create_github_issues: false
non_interactive: true
# Recommended inputs
recommended_inputs:
- story_markdown: "Path to the story markdown file flagged Ready for Review"
- tech_spec: "Epic technical specification document (auto-discovered if omitted)"
- story_context: "Story Context XML/JSON path (auto-discovered if omitted)"
# Required tools (conceptual; executor should provide equivalents)
required_tools:
- list_files
- file_info
- read_file
- write_file
- search_repo
- parse_markdown
- glob
- mcp_doc_search # Use available MCP servers to search docs/best-practices
- web_search # Fallback research
- read_url # Fetch references
tags:
- review
- code-review
- quality
- testing
- bmad-v6
execution_hints:
interactive: false # Minimize prompts; intended to run deterministically
autonomous: true # Proceed without user input unless blocked
iterative: true

234
bmad/bmm/workflows/4-implementation/story-context/README.md Normal file
View File

@@ -0,0 +1,234 @@
# Story Context Assembly Workflow
## Overview
Assembles a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story. Creates comprehensive development context for AI agents and developers working on specific stories.
## Key Features
- **Automated Context Discovery** - Scans documentation and codebase for relevant artifacts
- **XML Output Format** - Structured context optimized for LLM consumption
- **Dependency Detection** - Identifies frameworks, packages, and technical dependencies
- **Interface Mapping** - Locates existing APIs and interfaces to reuse
- **Testing Integration** - Includes testing standards and generates test ideas
- **Status Tracking** - Updates story status and maintains context references
## Usage
### Basic Invocation
```bash
workflow story-context
```
### With Specific Story
```bash
# Process specific story file
workflow story-context --input /path/to/story.md
# Using story path variable
workflow story-context --story_path "docs/stories/1.2.feature-name.md"
```
### Configuration
- **story_path**: Path to target story markdown file (defaults to latest.md)
- **auto_update_status**: Whether to automatically update story status (default: false)
## Workflow Structure
### Files Included
```
story-context/
├── workflow.yaml # Configuration and metadata
├── instructions.md # Step-by-step execution guide
├── context-template.xml # XML structure template
├── checklist.md # Validation criteria
└── README.md # This file
```
## Workflow Process
### Phase 1: Story Analysis (Steps 1-2)
- **Story Location**: Finds and loads target story markdown file
- **Content Parsing**: Extracts epic ID, story ID, title, acceptance criteria, and tasks
- **Template Initialization**: Creates initial XML context structure
- **User Story Extraction**: Parses "As a... I want... So that..." components
### Phase 2: Documentation Discovery (Step 3)
- **Keyword Analysis**: Identifies relevant terms from story content
- **Document Scanning**: Searches docs and module documentation
- **Authority Prioritization**: Prefers PRDs, architecture docs, and specs
- **Context Extraction**: Captures relevant sections with snippets
### Phase 3: Code Analysis (Step 4)
- **Symbol Search**: Finds relevant modules, functions, and components
- **Interface Identification**: Locates existing APIs and interfaces
- **Constraint Extraction**: Identifies development patterns and requirements
- **Reuse Opportunities**: Highlights existing code to leverage
### Phase 4: Dependency Analysis (Step 5)
- **Manifest Detection**: Scans for package.json, requirements.txt, go.mod, etc.
- **Framework Identification**: Identifies Unity, Node.js, Python, Go ecosystems
- **Version Tracking**: Captures dependency versions where available
- **Configuration Discovery**: Finds relevant project configurations
### Phase 5: Testing Context (Step 6)
- **Standards Extraction**: Identifies testing frameworks and patterns
- **Location Mapping**: Documents where tests should be placed
- **Test Ideas**: Generates initial test concepts for acceptance criteria
- **Framework Integration**: Links to existing test infrastructure
### Phase 6: Validation and Updates (Steps 7-8)
- **XML Validation**: Ensures proper structure and completeness
- **Status Updates**: Changes story status from Draft to ContextReadyDraft
- **Reference Tracking**: Adds context file reference to story document
- **Quality Assurance**: Validates against workflow checklist
## Output
### Generated Files
- **Primary output**: story-context-{epic_id}.{story_id}-{date}.xml
- **Story updates**: Modified original story file with context references
### Output Structure
```xml
<storyContext>
<story>
<basicInfo>
<epicId>...</epicId>
<storyId>...</storyId>
<title>...</title>
<status>...</status>
</basicInfo>
<userStory>
<asA>...</asA>
<iWant>...</iWant>
<soThat>...</soThat>
</userStory>
<acceptanceCriteria>
<criterion id="1">...</criterion>
</acceptanceCriteria>
<tasks>
<task>...</task>
</tasks>
</story>
<artifacts>
<docs>
<doc path="..." title="..." section="..." snippet="..."/>
</docs>
<code>
<file path="..." kind="..." symbol="..." lines="..." reason="..."/>
</code>
<dependencies>
<node>
<package name="..." version="..."/>
</node>
</dependencies>
</artifacts>
<interfaces>
<interface name="..." kind="..." signature="..." path="..."/>
</interfaces>
<constraints>
<constraint>...</constraint>
</constraints>
<tests>
<standards>...</standards>
<locations>
<location>...</location>
</locations>
<ideas>
<idea ac="1">...</idea>
</ideas>
</tests>
</storyContext>
```
## Requirements
- **Story File**: Valid story markdown with proper structure (epic.story.title.md format)
- **Repository Access**: Ability to scan documentation and source code
- **Documentation**: Project documentation in standard locations (docs/, src/, etc.)
## Best Practices
### Before Starting
1. **Ensure Story Quality**: Verify story has clear acceptance criteria and tasks
2. **Update Documentation**: Ensure relevant docs are current and discoverable
3. **Clean Repository**: Remove obsolete code that might confuse context assembly
### During Execution
1. **Review Extracted Context**: Verify that discovered artifacts are actually relevant
2. **Check Interface Accuracy**: Ensure identified APIs and interfaces are current
3. **Validate Dependencies**: Confirm dependency information matches project state
### After Completion
1. **Review XML Output**: Validate the generated context makes sense
2. **Test with Developer**: Have a developer review context usefulness
3. **Update Story Status**: Verify story status was properly updated
## Troubleshooting
### Common Issues
**Issue**: Context contains irrelevant or outdated information
- **Solution**: Review keyword extraction and document filtering logic
- **Check**: Ensure story title and acceptance criteria are specific and clear
**Issue**: Missing relevant code or interfaces
- **Solution**: Verify code search patterns and symbol extraction
- **Check**: Ensure relevant code follows project naming conventions
**Issue**: Dependency information is incomplete or wrong
- **Solution**: Check for multiple package manifests or unusual project structure
- **Check**: Verify dependency files are in expected locations and formats
## Customization
To customize this workflow:
1. **Modify Search Patterns**: Update instructions.md to adjust code and doc discovery
2. **Extend XML Schema**: Customize context-template.xml for additional context types
3. **Add Validation**: Extend checklist.md with project-specific quality criteria
4. **Configure Dependencies**: Adjust dependency detection for specific tech stacks
## Version History
- **v6.0.0** - XML-based context assembly with comprehensive artifact discovery
- Multi-ecosystem dependency detection
- Interface and constraint extraction
- Testing context integration
- Story status management
## Support
For issues or questions:
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
- Validate output using `checklist.md`
- Ensure story files follow expected markdown structure
- Check that repository structure supports automated discovery
---
_Part of the BMad Method v6 - BMM (Method) Module_

16
bmad/bmm/workflows/4-implementation/story-context/checklist.md Normal file
View File

@@ -0,0 +1,16 @@
# Story Context Assembly Checklist
```xml
<checklist id="bmad/bmm/workflows/4-implementation/story-context/checklist">
<item>Story fields (asA/iWant/soThat) captured</item>
<item>Acceptance criteria list matches story draft exactly (no invention)</item>
<item>Tasks/subtasks captured as task list</item>
<item>Relevant docs (5-15) included with path and snippets</item>
<item>Relevant code references included with reason and line hints</item>
<item>Interfaces/API contracts extracted if applicable</item>
<item>Constraints include applicable dev rules and patterns</item>
<item>Dependencies detected from manifests and frameworks</item>
<item>Testing standards and locations populated</item>
<item>XML structure follows story-context template format</item>
</checklist>
```

34
bmad/bmm/workflows/4-implementation/story-context/context-template.xml Normal file
View File

@@ -0,0 +1,34 @@
<story-context id="bmad/bmm/workflows/4-implementation/story-context/template" v="1.0">
<metadata>
<epicId>{{epic_id}}</epicId>
<storyId>{{story_id}}</storyId>
<title>{{story_title}}</title>
<status>{{story_status}}</status>
<generatedAt>{{date}}</generatedAt>
<generator>BMAD Story Context Workflow</generator>
<sourceStoryPath>{{story_path}}</sourceStoryPath>
</metadata>
<story>
<asA>{{as_a}}</asA>
<iWant>{{i_want}}</iWant>
<soThat>{{so_that}}</soThat>
<tasks>{{story_tasks}}</tasks>
</story>
<acceptanceCriteria>{{acceptance_criteria}}</acceptanceCriteria>
<artifacts>
<docs>{{docs_artifacts}}</docs>
<code>{{code_artifacts}}</code>
<dependencies>{{dependencies_artifacts}}</dependencies>
</artifacts>
<constraints>{{constraints}}</constraints>
<interfaces>{{interfaces}}</interfaces>
<tests>
<standards>{{test_standards}}</standards>
<locations>{{test_locations}}</locations>
<ideas>{{test_ideas}}</ideas>
</tests>
</story-context>

76
bmad/bmm/workflows/4-implementation/story-context/instructions.md Normal file
View File

@@ -0,0 +1,76 @@
<!-- BMAD BMM Story Context Assembly Instructions (v6) -->
```xml
<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.yaml</critical>
<critical>This workflow assembles a Story Context XML for a single user story by extracting ACs, tasks, relevant docs/code, interfaces, constraints, and testing guidance to support implementation.</critical>
<critical>Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery fails, HALT and request 'story_path' or 'story_dir'.</critical>
<workflow>
<step n="1" goal="Locate story and initialize output">
<action>If {{story_path}} provided and valid → use it; else auto-discover from {{story_dir}}.</action>
<action>Auto-discovery: read {{story_dir}} (dev_story_location). If invalid/missing or contains no .md files, ASK for a story file path or directory to scan.</action>
<action>If a directory is provided, list markdown files named "story-*.md" recursively; sort by last modified time; display top {{story_selection_limit}} with index, filename, path, modified time.</action>
<ask optional="true" if="{{non_interactive}} == false">"Select a story (1-{{story_selection_limit}}) or enter a path:"</ask>
<action>If {{non_interactive}} == true: choose the most recently modified story automatically. If none found, HALT with a clear message to provide 'story_path' or 'story_dir'. Else resolve selection into {{story_path}} and READ COMPLETE file.</action>
<action>Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content; parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes.</action>
<action>Extract user story fields (asA, iWant, soThat).</action>
<action>Initialize output by writing template to {default_output_file}.</action>
<template-output file="{default_output_file}">as_a</template-output>
<template-output file="{default_output_file}">i_want</template-output>
<template-output file="{default_output_file}">so_that</template-output>
</step>
<step n="2" goal="Collect relevant documentation">
<action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks<</action>
<action>Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
<template-output file="{default_output_file}">
Add artifacts.docs entries with {path, title, section, snippet} (NO invention)
</template-output>
</step>
<step n="3" goal="Analyze existing code, interfaces, and constraints">
<action>Search source tree for modules, files, and symbols matching story intent and AC keywords (controllers, services, components, tests).</action>
<action>Identify existing interfaces/APIs the story should reuse rather than recreate.</action>
<action>Extract development constraints from Dev Notes and architecture (patterns, layers, testing requirements).</action>
<template-output file="{default_output_file}">
Add artifacts.code entries with {path, kind, symbol, lines, reason}; include a brief reason explaining relevance to the story
Populate interfaces with any API/interface signatures that the developer must call (name, kind, signature, path)
Populate constraints with development rules extracted from Dev Notes and architecture (e.g., patterns, layers, testing requirements)
</template-output>
</step>
<step n="4" goal="Gather dependencies and frameworks">
<action>Detect dependency manifests and frameworks in the repo:
- Node: package.json (dependencies/devDependencies)
- Python: pyproject.toml/requirements.txt
- Go: go.mod
- Unity: Packages/manifest.json, Assets/, ProjectSettings/
- Other: list notable frameworks/configs found</action>
<template-output file="{default_output_file}">
Populate artifacts.dependencies with keys for detected ecosystems and their packages with version ranges where present
</template-output>
</step>
<step n="5" goal="Testing standards and ideas">
<action>From Dev Notes, architecture docs, testing docs, and existing tests, extract testing standards (frameworks, patterns, locations).</action>
<template-output file="{default_output_file}">
Populate tests.standards with a concise paragraph
Populate tests.locations with directories or glob patterns where tests live
Populate tests.ideas with initial test ideas mapped to acceptance criteria IDs
</template-output>
</step>
<step n="6" goal="Validate and save">
<action>Validate output XML structure and content.</action>
<invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.md</invoke-task>
</step>
<step n="7" goal="Update story status and context reference">
<action>Open {{story_path}}; if Status == 'Draft' then set to 'ContextReadyDraft'; otherwise leave unchanged.</action>
<action>Under 'Dev Agent Record' → 'Context Reference' (create if missing), add or update a list item for {default_output_file}.</action>
<action>Save the story file.</action>
</step>
</workflow>
```

56
bmad/bmm/workflows/4-implementation/story-context/workflow.yaml Normal file
View File

@@ -0,0 +1,56 @@
# Story Context Creation Workflow
name: story-context
description: "Assemble a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story"
author: "BMad"
# Critical variables
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
date: system-generated
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/story-context"
template: "{installed_path}/context-template.xml"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# Variables and inputs
variables:
story_path: "" # Explicit story path; auto-discovered if empty
auto_update_status: false
story_dir: "{config_source}:dev_story_location"
story_selection_limit: 10
tech_spec_search_dir: "{project-root}/docs"
tech_spec_glob_template: "tech-spec-epic-{{epic_id}}*.md"
non_interactive: true
# Output configuration
default_output_file: "{output_folder}/story-context-{{epic_id}}.{{story_id}}.xml"
# Recommended inputs
recommended_inputs:
- story_markdown: "Path to a story markdown file to build context for"
# Required tools
required_tools:
- list_files
- file_info
- read_file
- write_file
- create_directory
- glob
- search_repo
- parse_markdown
tags:
- context
- story
- planning
- bmad-v6
execution_hints:
interactive: false
autonomous: true
iterative: true