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

BoMB updates

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

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

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

39
bmad/bmm/workflows/4-implementation/create-story/checklist.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: 'Create Story Checklist'
validation-target: 'Newly generated story markdown file'
required-inputs:
- 'epics.md (preferred) or PRD'
optional-inputs:
- 'HLA document for architecture context'
validation-rules:
- 'Story structure matches sections: Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Change Log, Dev Agent Record'
- 'Dev Notes include Project Structure Notes and References subsections'
- 'All non-trivial technical notes include a source citation'
- 'Tasks include explicit testing subtasks based on testing strategy'
---
# Create Story Checklist
## Document Structure
- [ ] Title includes story id and title
- [ ] Status set to Draft
- [ ] Story section present with As a / I want / so that
- [ ] Acceptance Criteria is a numbered list
- [ ] Tasks/Subtasks present with checkboxes
- [ ] Dev Notes includes architecture/testing context
- [ ] Change Log table initialized
- [ ] Dev Agent Record sections present (Context Reference, Agent Model Used, Debug Log References, Completion Notes, File List)
## Content Quality
- [ ] Acceptance Criteria sourced from epics/PRD (or explicitly confirmed by user)
- [ ] Tasks reference AC numbers where applicable
- [ ] Dev Notes do not invent details; cite sources where possible
- [ ] File saved to stories directory from config (dev_story_location)
- [ ] If creating a new story number, epics.md explicitly enumerates this story under the target epic; otherwise generation HALTED with instruction to run PM/SM `*correct-course` (open `{project-root}/bmad/bmm/agents/pm.md` or `{project-root}/bmad/bmm/agents/sm.md` and execute `*correct-course`)
## Optional Post-Generation
- [ ] Story Context generation run (if auto_run_context)
- [ ] Context Reference recorded in story

81
bmad/bmm/workflows/4-implementation/create-story/instructions.md Normal file
View File

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

57
bmad/bmm/workflows/4-implementation/create-story/template.md Normal file
View File

@@ -0,0 +1,57 @@
# Story {{epic_num}}.{{story_num}}: {{story_title}}
Status: Draft
## Story
As a {{role}},
I want {{action}},
so that {{benefit}}.
## Acceptance Criteria
1. [Add acceptance criteria from epics/PRD]
## Tasks / Subtasks
- [ ] Task 1 (AC: #)
- [ ] Subtask 1.1
- [ ] Task 2 (AC: #)
- [ ] Subtask 2.1
## Dev Notes
- Relevant architecture patterns and constraints
- Source tree components to touch
- Testing standards summary
### Project Structure Notes
- Alignment with unified project structure (paths, modules, naming)
- Detected conflicts or variances (with rationale)
### References
- Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
## Change Log
| Date | Version | Description | Author |
| -------- | ------- | ------------- | ------------- |
| {{date}} | 0.1 | Initial draft | {{user_name}} |
## Dev Agent Record
### Context Reference
<!-- Path(s) to story context XML/JSON will be added here by context workflow -->
### Agent Model Used
{{agent_model_name_version}}
### Debug Log References
### Completion Notes List
### File List

72
bmad/bmm/workflows/4-implementation/create-story/workflow.yaml Normal file
View File

@@ -0,0 +1,72 @@
name: create-story
description: "Create the next user story markdown from epics/PRD and architecture, using a standard template and saving to the stories folder"
author: "BMad"
# Critical variables from config
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
date: system-generated
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/create-story"
template: "{installed_path}/template.md"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# Variables and inputs
variables:
story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
prd_file: "{output_folder}/prd.md" # Fallback for requirements
hla_file: "{output_folder}/high-level-architecture.md" # Optional architecture context
tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
tech_spec_search_dir: "{project-root}/docs"
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
arch_docs_search_dirs: |
- "{project-root}/docs"
- "{output_folder}"
arch_docs_file_names: |
- tech-stack.md
- unified-project-structure.md
- coding-standards.md
- testing-strategy.md
- backend-architecture.md
- frontend-architecture.md
- data-models.md
- database-schema.md
- rest-api-spec.md
- external-apis.md
story_title: "" # Will be elicited if not derivable
epic_num: 1
story_num: 1
auto_run_context: true # Optionally run story-context after creation
non_interactive: true # Generate without elicitation; avoid interactive prompts
# Output configuration
default_output_file: "{story_dir}/story-{{epic_num}}.{{story_num}}.md"
required_tools:
- list_files
- file_info
- read_file
- write_file
- create_directory
- search_repo
- glob
recommended_inputs:
- epics: "Epic breakdown (epic-list.md)"
- prd: "PRD document"
- hla: "High-Level Architecture (optional)"
tags:
- story-generation
- planning
- bmad-v6
execution_hints:
interactive: false
autonomous: true
iterative: true