bmad-method 5.1.3 → 6.0.0-alpha.1

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>
+<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
+<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
+</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>
+<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
+<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
+<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
+</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,201 @@
+# Correct Course - Sprint Change Management Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<critical>DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates.</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>
+
+<action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
+
+<action if="core documents are unavailable">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: {checklist}</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>
+
+<action if="checklist cannot be completed">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">
+  <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>
+
+<action if="mode is Batch">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>
+<action>Write Sprint Change Proposal document to {default_output_file}</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">
+  <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>
+
+<check if="yes the proposal is approved by the user">
+  <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>
+
+<check if="Minor scope">
+  <action>Route to: Development team for direct implementation</action>
+  <action>Deliverables: Finalized edit proposals and implementation tasks</action>
+</check>
+
+<check if="Moderate scope">
+  <action>Route to: Product Owner / Scrum Master agents</action>
+  <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
+</check>
+
+<check if="Major scope">
+  <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>
+</check>
+
+</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 with personalized message: "✅ Correct Course workflow complete, {user_name}!"</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,45 @@
+# 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"
+communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
+date: system-generated
+
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
+template: false
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+checklist: "{installed_path}/checklist.md"
+default_output_file: "{output_folder}/sprint-change-proposal-{date}.md"
+
+# Workflow execution mode (interactive: step-by-step with user, non-interactive: automated)
+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"
+
+standalone: true
+
+web_bundle: false

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

@@ -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: code-review (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.