bmad-method 5.1.2 → 6.0.0-alpha.0

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

@@ -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>

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

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

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

@@ -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"

package/src/modules/bmm/workflows/4-implementation/create-story/README.md

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

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

@@ -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