bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/modules/bmm/workflows/4-implementation/review-story/instructions.md

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

package/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml

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

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

@@ -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/build-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_

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

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

package/src/modules/bmm/workflows/4-implementation/story-context/context-template.xml

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

package/src/modules/bmm/workflows/4-implementation/story-context/instructions.md

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