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

BoMB updates

Browse Source
This commit is contained in:
Brian Madison
2025-10-04 00:22:59 -05:00
parent 9e8c7f3503
commit 5ee4cf535c
326 changed files with 39464 additions and 402 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
bmad/bmm/workflows/4-implementation/correct-course/README.md Normal file
View File

@@ -0,0 +1,73 @@
---
last-redoc-date: 2025-10-01
---
# Correct Course Workflow
The correct-course workflow is v6's adaptive response mechanism for stories that encounter issues during development or review, enabling intelligent course correction without restarting from scratch. Run by the Scrum Master (SM) or Team Lead, this workflow analyzes why a story is blocked or has issues, determines whether the story scope needs adjustment, requirements need clarification, technical approach needs revision, or the story needs to be split or reconsidered. This represents the agile principle of embracing change even late in the development cycle, but doing so in a structured way that captures learning and maintains project coherence.
Unlike simply abandoning failed work or blindly pushing forward, correct-course provides a systematic approach to diagnosing issues and determining appropriate remediation. The workflow examines the original story specification, what was actually implemented, what issues arose during development or review, and the broader epic context to recommend the best path forward. This might involve clarifying requirements, adjusting acceptance criteria, revising technical approach, splitting the story into smaller pieces, or even determining the story should be deprioritized.
The critical value of this workflow is that it prevents thrashing—endless cycles of implementation and rework without clear direction. By stepping back to analyze what went wrong and charting a clear path forward, the correct-course workflow enables teams to learn from difficulties and adapt intelligently rather than stubbornly proceeding with a flawed approach.
## Usage
```bash
# Analyze issues and recommend course correction
bmad run correct-course
```
The workflow should be run when:
- Review identifies critical issues requiring rethinking
- Developer encounters blocking issues during implementation
- Acceptance criteria prove infeasible or unclear
- Technical approach needs significant revision
- Story scope needs adjustment based on discoveries
## Inputs
**Required Context:**
- **Story Document**: Original story specification
- **Implementation Attempts**: Code changes and approaches tried
- **Review Feedback**: Issues and concerns identified
- **Epic Context**: Overall epic goals and current progress
- **Technical Constraints**: Architecture decisions and limitations discovered
**Analysis Focus:**
- Root cause of issues or blockages
- Feasibility of current story scope
- Clarity of requirements and acceptance criteria
- Appropriateness of technical approach
- Whether story should be split or revised
## Outputs
**Primary Deliverable:**
- **Course Correction Report** (`[story-id]-correction.md`): Analysis and recommendations including:
- Issue root cause analysis
- Impact assessment on epic and project
- Recommended corrective actions with rationale
- Revised story specification if applicable
- Updated acceptance criteria if needed
- Technical approach adjustments
- Timeline and effort implications
**Possible Outcomes:**
1. **Clarify Requirements**: Update story with clearer acceptance criteria
2. **Revise Scope**: Adjust story scope to be more achievable
3. **Split Story**: Break into multiple smaller stories
4. **Change Approach**: Recommend different technical approach
5. **Deprioritize**: Determine story should be deferred or cancelled
6. **Unblock**: Identify and address blocking dependencies
**Artifacts:**
- Updated story document if revision needed
- New story documents if splitting story
- Updated epic backlog reflecting changes
- Lessons learned for retrospective

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.xml</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"

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

@@ -0,0 +1,129 @@
---
last-redoc-date: 2025-10-01
---
# Create Story Workflow
The create-story workflow is the entry point for v6's just-in-time story generation approach, run exclusively by the Scrum Master (SM) agent. Unlike batch processing methodologies, this workflow generates exactly ONE story at a time based on the current epic backlog state, ensuring stories are created only when needed and with the most current context. The SM analyzes the epic's progress, identifies what needs to be built next based on epics.md enumeration, and generates a complete story specification including acceptance criteria, technical approach, and implementation guidance pulled directly from tech specs, PRD, and architecture documentation.
This workflow represents a fundamental shift from traditional upfront planning to adaptive story generation. By creating stories one at a time and enforcing strict verification against epics.md, the SM ensures that only planned and approved stories are created. The workflow operates in non-interactive "#yolo" mode by default, minimizing prompts while maintaining quality through rigorous source document grounding. It will HALT if epics.md doesn't explicitly enumerate the next story, forcing proper planning through the correct-course workflow rather than allowing ad-hoc story creation.
The workflow's intelligent document discovery system automatically finds the relevant tech spec for the current epic (using pattern `tech-spec-epic-{epic_num}-*.md`), loads all architecture documents from both docs/ and output folders, and synthesizes requirements from multiple sources in priority order. After story creation, it can optionally trigger the story-context workflow to generate just-in-time technical expertise for the developer.
## Usage
```bash
# SM initiates story creation for the next piece of work
bmad sm *create-story
```
The SM runs this workflow when:
- The current sprint has capacity for new work
- The previous story status is "Done" or "Approved"
- The team is ready for the next planned story in the epic
- Story preparation is needed before development
## Inputs
**Required Context Files:**
- **epics.md**: MANDATORY - Must explicitly enumerate the next story or workflow halts
- **tech-spec-epic-{N}-\*.md**: Epic-specific technical specification (auto-discovered)
- **PRD.md**: Product requirements document (fallback for requirements)
- **Architecture Documents**: Automatically discovered from docs/ and output folders:
- 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
**Workflow Variables:**
- `story_dir`: From config `dev_story_location` - where stories are saved
- `epic_num`: Current epic number (auto-detected from existing stories)
- `story_num`: Next story number (incremented from last completed story)
- `auto_run_context`: Default true - runs story-context workflow after creation
- `non_interactive`: Default true - operates in "#yolo" mode with minimal prompts
## Outputs
**Primary Deliverable:**
- **Story Document** (`{story_dir}/story-{epic_num}.{story_num}.md`): Complete story specification including:
- User story statement (role, action, benefit)
- Acceptance criteria extracted from tech spec or epics.md
- Tasks and subtasks mapped to ACs
- Testing requirements per testing strategy
- Dev notes with source citations
- Status: "Draft" (requires approval before development)
**Validation Safeguards:**
- **Epic Enumeration Check**: If epics.md doesn't list the next story, workflow HALTS with:
```
"No planned next story found in epics.md for epic {epic_num}.
Please load either PM or SM agent and run *correct-course to add/modify epic stories."
```
- **Status Check**: Won't create new story if current story isn't Done/Approved
- **Document Grounding**: All requirements traced to source documents (no invention)
## Key Features
**Strict Planning Enforcement**: The workflow will NOT create stories that aren't explicitly planned in epics.md. This prevents scope creep and ensures all work is properly approved through the planning process.
**Intelligent Document Discovery**: Automatically finds the latest tech spec for the epic using glob patterns, discovers all architecture documents across multiple directories, and builds a prioritized document set for requirement extraction.
**Source Document Grounding**: Every requirement, acceptance criterion, and technical constraint is traced to a specific source document. The workflow explicitly forbids inventing domain facts not present in source materials.
**Non-Interactive by Default**: Operates in "#yolo" mode to minimize interruptions, only prompting when absolutely necessary (like missing critical configuration). This enables smooth automated story preparation.
**Automatic Context Generation**: When `auto_run_context` is true (default), automatically triggers the story-context workflow to generate developer expertise injection for the newly created story.
## Integration with v6 Flow
The create-story workflow is step 1 in the v6 implementation cycle:
1. **SM: create-story** ← You are here
2. SM: story-context (adds JIT technical expertise)
3. DEV: dev-story (implements with generated context)
4. DEV/SR: review-story (validates completion)
5. If needed: correct-course (adjusts direction)
6. After epic: retrospective (captures learnings)
This workflow establishes the "what" that needs to be built, strictly based on planned epics. The story-context workflow will later add the "how" through just-in-time technical expertise injection.
## Document Priority Order
The workflow uses this priority for extracting requirements:
1. **tech_spec_file**: Epic-scoped technical specification (highest priority)
2. **epics_file**: Acceptance criteria and story breakdown
3. **prd_file**: Business requirements and constraints
4. **Architecture docs**: Constraints, patterns, and technical guidance
## Workflow Behavior
**Story Number Management:**
- Automatically detects next story number from existing files
- Won't skip numbers or create duplicates
- Maintains epic.story numbering convention
**Update vs Create:**
- If latest story status != Done/Approved: Updates existing story
- If latest story status == Done/Approved: Creates next story (if enumerated in epics.md)
**Epic Advancement:**
- In non-interactive mode: Stays within current epic
- Interactive mode: Can prompt for new epic number
## Troubleshooting
**"No planned next story found in epics.md"**: The next story isn't enumerated in epics.md. Run SM or PM agent's `*correct-course` to properly plan and add the story to the epic.
**Missing story_dir Configuration**: Ensure `dev_story_location` is set in bmad/bmm/config.yaml
**Tech Spec Not Found**: The workflow looks for `tech-spec-epic-{N}-*.md` pattern. Ensure tech specs follow this naming convention.
**Architecture Documents Missing**: While not fatal, missing architecture docs reduce story context quality. Ensure key docs exist in docs/ or output folder.

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.xml</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.xml</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

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

@@ -0,0 +1,206 @@
# Dev Story Workflow
The dev-story workflow is where v6's just-in-time context approach delivers its primary value, enabling the Developer (DEV) agent to implement stories with expert-level guidance injected directly into their context. This workflow is run EXCLUSIVELY by the DEV agent and operates on a single story that has been prepared by the SM through create-story and enhanced with story-context. The DEV loads both the story specification and the dynamically-generated story context XML, then proceeds through implementation with the combined knowledge of requirements and domain-specific expertise.
The workflow operates with two critical inputs: the story file (created by SM's create-story) containing acceptance criteria, tasks, and requirements; and the story-context XML (generated by SM's story-context) providing just-in-time expertise injection tailored to the story's technical needs. This dual-input approach ensures the developer has both the "what" (from the story) and the "how" (from the context) needed for successful implementation. The workflow iterates through tasks sequentially, implementing code, writing tests, and updating the story document's allowed sections until all tasks are complete.
A critical aspect of v6 flow is that dev-story may be run multiple times for the same story. Initially run to implement the story, it may be run again after review-story identifies issues that need correction. The workflow intelligently resumes from incomplete tasks, making it ideal for both initial implementation and post-review fixes. The DEV agent maintains strict boundaries on what can be modified in the story file—only Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, and Status may be updated, preserving the story's requirements integrity.
## Usage
```bash
# Developer implements the story with injected context
bmad dev *develop
# Or if returning to fix review issues
bmad dev *develop # Will resume from incomplete tasks
```
The DEV runs this workflow:
- After SM completes both create-story and story-context
- When a story status is "Draft" or "Approved" (ready for development)
- After review-story identifies issues requiring fixes
- To resume work on a partially completed story
## Inputs
**Required Files:**
- **Story Document** (`{story_dir}/story-{epic}.{story}.md`): Complete specification including:
- User story statement
- Acceptance criteria (immutable during dev)
- Tasks and subtasks (checkable during implementation)
- Dev Notes section (for context and guidance)
- Status field (Draft → In Progress → Ready for Review)
- **Story Context XML** (`{story_dir}/story-{epic}.{story}-context.xml`): Domain expertise including:
- Technical patterns and best practices
- Gotchas and common pitfalls
- Testing strategies
- Relevant code references
- Architecture constraints
**Configuration:**
- `dev_story_location`: Directory containing story files (from bmm/config.yaml)
- `story_selection_limit`: Number of recent stories to show (default: 10)
- `run_tests_command`: Test command (default: auto-detected)
- `strict`: Whether to halt on test failures (default: true)
## Outputs
**Code Implementation:**
- Production code satisfying acceptance criteria
- Unit, integration, and E2E tests as appropriate
- Documentation updates
- Migration scripts if needed
**Story File Updates (allowed sections only):**
- **Tasks/Subtasks**: Checkboxes marked complete as work progresses
- **Dev Agent Record**: Debug log and completion notes
- **File List**: All files created or modified
- **Change Log**: Summary of implementation changes
- **Status**: Updated to "Ready for Review" when complete
**Validation:**
- All tests passing (existing + new)
- Acceptance criteria verified
- Code quality checks passed
- No regression in existing functionality
## Key Features
**Story-Context Integration**: The workflow loads and leverages the story-context XML throughout implementation, providing expert guidance without cluttering the main conversation. This ensures best practices are followed while maintaining developer autonomy.
**Task-by-Task Iteration**: Implements one task at a time, marking completion before moving to the next. This granular approach enables progress tracking and clean resumption if interrupted or after review feedback.
**Strict File Boundaries**: Only specific sections of the story file may be modified, preserving requirement integrity. The story's acceptance criteria, main description, and other planning sections remain immutable during development.
**Test-Driven Approach**: For each task, the workflow emphasizes writing tests that verify acceptance criteria before or alongside implementation, ensuring requirements are actually met.
**Resumable Implementation**: If the workflow is run again on a story with incomplete tasks (e.g., after review-story finds issues), it intelligently resumes from where it left off rather than starting over.
## Integration with v6 Flow
The dev-story workflow is step 3 in the v6 implementation cycle:
1. SM: create-story (generates the story specification)
2. SM: story-context (adds JIT technical expertise)
3. **DEV: dev-story** ← You are here (initial implementation)
4. DEV/SR: review-story (validates completion)
5. If issues found: **DEV: dev-story** ← May return here for fixes
6. After epic: retrospective (captures learnings)
This workflow may be executed multiple times for the same story as part of the review-fix cycle. Each execution picks up from incomplete tasks, making it efficient for iterative improvement.
## Workflow Process
### Phase 1: Story Selection
- If `story_path` provided: Use that story directly
- Otherwise: List recent stories from `dev_story_location`
- Parse story structure and validate format
- Load corresponding story-context XML
### Phase 2: Task Implementation Loop
For each incomplete task:
1. **Plan**: Log approach in Dev Agent Record
2. **Implement**: Write code following story-context guidance
3. **Test**: Create tests verifying acceptance criteria
4. **Validate**: Run tests and quality checks
5. **Update**: Mark task complete, update File List
### Phase 3: Completion
- Verify all tasks completed
- Run full test suite
- Update Status to "Ready for Review"
- Add completion notes to Dev Agent Record
## Story File Structure
The workflow expects stories with this structure:
```markdown
# Story {epic}.{story}: {Title}
**Status**: Draft|In Progress|Ready for Review|Done
**Epic**: {epic_number}
**Estimated Effort**: {estimate}
## Story
As a {role}, I want to {action} so that {benefit}
## Acceptance Criteria
- [ ] AC1...
- [ ] AC2...
## Tasks and Subtasks
- [ ] Task 1
- [ ] Subtask 1.1
- [ ] Task 2
## Dev Notes
{Context and guidance from story creation}
## Dev Agent Record
### Debug Log
{Implementation notes added during development}
### Completion Notes
{Summary added when complete}
## File List
{Files created/modified}
## Change Log
{Implementation summary}
```
## Best Practices
**Load Context First**: Always ensure the story-context XML is loaded at the start. This provides the expert guidance needed throughout implementation.
**Follow Task Order**: Implement tasks in the order listed. Dependencies are typically structured in the task sequence.
**Test Each Task**: Don't wait until the end to write tests. Test each task as you complete it to ensure it meets acceptance criteria.
**Update Incrementally**: Update the story file after each task completion rather than batching updates at the end.
**Respect Boundaries**: Never modify acceptance criteria or story description. If they seem wrong, that's a review-story or correct-course issue, not a dev-story fix.
**Use Context Guidance**: Actively reference the story-context for patterns, gotchas, and best practices. It's there to help you succeed.
## Troubleshooting
**Story Not Found**: Ensure story exists in `dev_story_location` and follows naming pattern `story-{epic}.{story}.md`
**Context XML Missing**: The story-context workflow must be run first. Check for `story-{epic}.{story}-context.xml`
**Tests Failing**: If strict mode is on, the workflow halts. Fix tests before continuing or set strict=false for development iteration.
**Can't Modify Story Section**: Remember only Tasks, Dev Agent Record, File List, Change Log, and Status can be modified. Other sections are immutable.
**Resuming After Review**: If review-story found issues, the workflow automatically picks up from incomplete tasks when run again.
## Related Workflows
- **create-story**: Creates the story specification (run by SM)
- **story-context**: Generates the context XML (run by SM)
- **review-story**: Validates implementation (run by SR/DEV)
- **correct-course**: Handles major issues or scope changes (run by SM)

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.xml</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.xml</action>
<action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
<action>Communicate that the story is Ready for Review</action>
</step>
</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

77
bmad/bmm/workflows/4-implementation/retrospective/README.md Normal file
View File

@@ -0,0 +1,77 @@
---
last-redoc-date: 2025-10-01
---
# Retrospective Workflow
The retrospective workflow is v6's learning capture mechanism, run by the Scrum Master (SM) after epic completion to systematically harvest insights, patterns, and improvements discovered during implementation. Unlike traditional retrospectives that focus primarily on process and team dynamics, this workflow performs deep technical and methodological analysis of the entire epic journey—from story creation through implementation to review—identifying what worked well, what could improve, and what patterns emerged. The retrospective produces actionable intelligence that informs future epics, improves workflow templates, and evolves the team's shared knowledge.
This workflow represents a critical feedback loop in the v6 methodology. Each epic is an experiment in adaptive software development, and the retrospective is where we analyze the results of that experiment. The SM examines completed stories, review feedback, course corrections made, story-context effectiveness, technical decisions, and team collaboration patterns to extract transferable learning. This learning manifests as updates to workflow templates, new story-context patterns, refined estimation approaches, and documented best practices.
The retrospective is not just a compliance ritual but a genuine opportunity for continuous improvement. By systematically analyzing what happened during the epic, the team builds institutional knowledge that makes each subsequent epic smoother, faster, and higher quality. The insights captured here directly improve future story creation, context generation, development efficiency, and review effectiveness.
## Usage
```bash
# Conduct retrospective after epic completion
bmad run retrospective
```
The SM should run this workflow:
- After all stories in an epic are completed
- Before starting the next major epic
- When significant learning has accumulated
- As preparation for improving future epic execution
## Inputs
**Required Context:**
- **Epic Document**: Complete epic specification and goals
- **All Story Documents**: Every story created for the epic
- **Review Reports**: All review feedback and findings
- **Course Corrections**: Any correct-course actions taken
- **Story Contexts**: Generated expert guidance for each story
- **Implementation Artifacts**: Code commits, test results, deployment records
**Analysis Targets:**
- Story creation accuracy and sizing
- Story-context effectiveness and relevance
- Implementation challenges and solutions
- Review findings and patterns
- Technical decisions and outcomes
- Estimation accuracy
- Team collaboration and communication
- Workflow effectiveness
## Outputs
**Primary Deliverable:**
- **Retrospective Report** (`[epic-id]-retrospective.xml`): Comprehensive analysis including:
- Executive summary of epic outcomes
- Story-by-story analysis of what was learned
- Technical insights and architecture learnings
- Story-context effectiveness assessment
- Process improvements identified
- Patterns discovered (good and bad)
- Recommendations for future epics
- Metrics and statistics (velocity, cycle time, etc.)
**Actionable Outputs:**
- **Template Updates**: Improvements to workflow templates based on learning
- **Pattern Library**: New story-context patterns for common scenarios
- **Best Practices**: Documented approaches that worked well
- **Gotchas**: Issues to avoid in future work
- **Estimation Refinements**: Better story sizing guidance
- **Process Changes**: Workflow adjustments for next epic
**Artifacts:**
- Epic marked as complete with retrospective attached
- Knowledge base updated with new patterns
- Workflow templates updated if needed
- Team learning captured for onboarding

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.xml</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.xml</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.xml</invoke-task>
<action>Report workflow completion.</action>
</step> <step n="1" goal="Locate story and verify review status">
<action>If {{story_path}} was provided → use it. Else auto-discover from {{story_dir}} by listing files matching pattern: "story-*.md" (recursive), sort by last modified (newest first), present top {{story_selection_limit}}.</action>
<ask optional="true" if="{{non_interactive}} == false">Select a story (1-{{story_selection_limit}}) or enter a path:</ask>
<action>Resolve {{story_path}} and read the COMPLETE file.</action>
<action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available.</action>
<action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log.</action>
<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.xml</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.xml</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.xml</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