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