bmad-method 5.1.2 → 6.0.0-alpha.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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