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

docs update

Browse Source
This commit is contained in:
Brian Madison
2025-10-12 16:59:54 -05:00
parent 79ac3c91fe
commit c3c51945bb
11 changed files with 1052 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
src/modules/bmm/README.md
View File

@@ -39,10 +39,12 @@ The heart of BMM - structured workflows for the four development phases:
- `tech-spec` - Epic-specific technical specifications
4. **Implementation Phase** (Iterative)
- `create-story` - Story generation
- `story-context` - Expertise injection
- `dev-story` - Implementation
- `review-story` - Quality validation
- `create-story` - Story drafting (SM agent)
- `story-ready` - Approve story for development (SM agent)
- `story-context` - Expertise injection (SM agent)
- `dev-story` - Implementation (DEV agent)
- `story-approved` - Mark story done (DEV agent)
- `review-story` - Quality validation (DEV/SR agent)
- `correct-course` - Issue resolution
- `retrospective` - Continuous improvement
@@ -86,6 +88,21 @@ BMM automatically adapts to project complexity:
Technical specifications are created one epic at a time during implementation, not all upfront, allowing for learning and adaptation.
### Story State Machine
Stories flow through a 4-state lifecycle tracked in the status file:
```
BACKLOG → TODO → IN PROGRESS → DONE
```
- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition)
- **TODO**: Single story ready for SM to draft (or drafted, awaiting approval)
- **IN PROGRESS**: Single story approved for DEV to implement
- **DONE**: Completed stories with dates and points
Agents never search for "next story" - they always read the exact story from the status file. Simple workflows (`story-ready`, `story-approved`) advance the queue automatically.
### Context Injection
Story-specific technical guidance is generated dynamically, providing developers with exactly the expertise needed for each task.

61
src/modules/bmm/workflows/2-plan/tech-spec/instructions-level0-story.md
View File

@@ -98,14 +98,57 @@
</step>
<step n="4" goal="Update project-workflow-analysis with progress">
<step n="4" goal="Update project-workflow-status and initialize Phase 4">
<action>Open {output_folder}/project-workflow-status.md</action>
<action>Update "Workflow Status Tracker" section</action>
<action>Set current_phase = "2-Plan"</action>
<action>Set current_workflow = "tech-spec (Level 0 - story generation complete)"</action>
<action>Check "2-Plan" checkbox in Phase Completion Status</action>
<action>Update "Workflow Status Tracker" section:</action>
- Set current_phase = "4-Implementation" (Level 0 skips Phase 3)
- Set current_workflow = "tech-spec (Level 0 - story generation complete, ready for implementation)"
- Check "2-Plan" checkbox in Phase Completion Status
- Set progress_percentage = 40% (planning complete, skipping solutioning)
<action>Initialize Phase 4 Implementation Progress section:</action>
#### BACKLOG (Not Yet Drafted)
**Ordered story sequence - populated at Phase 4 start:**
| Epic | Story | ID | Title | File |
| ---------------------------------- | ----- | --- | ----- | ---- |
| (empty - Level 0 has only 1 story) | | | | |
**Total in backlog:** 0 stories
**NOTE:** Level 0 has single story only. No additional stories in backlog.
#### TODO (Needs Drafting)
Initialize with the ONLY story (already drafted):
- **Story ID:** {slug}
- **Story Title:** {{story_title}}
- **Story File:** `story-{slug}.md`
- **Status:** Draft (needs review before development)
- **Action:** User reviews drafted story, then runs SM agent `story-ready` workflow to approve
#### IN PROGRESS (Approved for Development)
Leave empty initially:
(Story will be moved here by SM agent `story-ready` workflow after user approves story-{slug}.md)
#### DONE (Completed Stories)
Initialize empty table:
| Story ID | File | Completed Date | Points |
| ---------- | ---- | -------------- | ------ |
| (none yet) | | | |
**Total completed:** 0 stories
**Total points completed:** 0 points
<action>Add to Artifacts Generated table:</action>
@@ -117,17 +160,17 @@
<action>Update "Next Action Required":</action>
```
**What to do next:** Run story-context workflow to generate implementation context
**What to do next:** Review drafted story-{slug}.md, then mark it ready for development
**Command to run:** Load SM agent and run workflow 'story-context' OR load DEV agent and run dev-story workflow directly
**Command to run:** Load SM agent and run 'story-ready' workflow (confirms story-{slug}.md is ready)
**Agent to load:** bmad/bmm/agents/sm.md OR bmad/bmm/agents/dev.md
**Agent to load:** bmad/bmm/agents/sm.md
```
<action>Add to Decision Log:</action>
```
- **{{date}}**: Level 0 tech-spec and story generation completed. Story: story-{slug}.md ready for context generation.
- **{{date}}**: Level 0 tech-spec and story generation completed. Skipping Phase 3 (solutioning) - moving directly to Phase 4 (implementation). Single story (story-{slug}.md) drafted and ready for review.
```
<action>Save project-workflow-status.md</action>

65
src/modules/bmm/workflows/2-plan/tech-spec/instructions-level1-stories.md
View File

@@ -228,14 +228,63 @@ Epic: Icon Reliability
</step>
<step n="6" goal="Update project-workflow-analysis with progress">
<step n="6" goal="Update project-workflow-status and populate backlog for Phase 4">
<action>Open {output_folder}/project-workflow-status.md</action>
<action>Update "Workflow Status Tracker" section</action>
<action>Set current_phase = "2-Plan"</action>
<action>Set current_workflow = "tech-spec (Level 1 - epic and stories generation complete)"</action>
<action>Check "2-Plan" checkbox in Phase Completion Status</action>
<action>Update "Workflow Status Tracker" section:</action>
- Set current_phase = "4-Implementation" (Level 1 skips Phase 3)
- Set current_workflow = "tech-spec (Level 1 - epic and stories generation complete, ready for implementation)"
- Check "2-Plan" checkbox in Phase Completion Status
- Set progress_percentage = 40% (planning complete, skipping solutioning)
<action>Populate story backlog in "### Implementation Progress (Phase 4 Only)" section:</action>
#### BACKLOG (Not Yet Drafted)
**Ordered story sequence - populated at Phase 4 start:**
| Epic | Story | ID | Title | File |
| ---- | ----- | --- | ----- | ---- |
{{#if story_2}}
| 1 | 2 | {epic_slug}-2 | {{story_2_title}} | story-{epic_slug}-2.md |
{{/if}}
{{#if story_3}}
| 1 | 3 | {epic_slug}-3 | {{story_3_title}} | story-{epic_slug}-3.md |
{{/if}}
**Total in backlog:** {{story_count - 1}} stories
**NOTE:** Level 1 uses slug-based IDs like "{epic_slug}-1", "{epic_slug}-2" instead of numeric "1.1", "1.2"
#### TODO (Needs Drafting)
Initialize with FIRST story (already drafted):
- **Story ID:** {epic_slug}-1
- **Story Title:** {{story_1_title}}
- **Story File:** `story-{epic_slug}-1.md`
- **Status:** Draft (needs review before development)
- **Action:** User reviews drafted story, then runs SM agent `story-ready` workflow to approve
#### IN PROGRESS (Approved for Development)
Leave empty initially:
(Story will be moved here by SM agent `story-ready` workflow after user approves story-{epic_slug}-1.md)
#### DONE (Completed Stories)
Initialize empty table:
| Story ID | File | Completed Date | Points |
| ---------- | ---- | -------------- | ------ |
| (none yet) | | | |
**Total completed:** 0 stories
**Total points completed:** 0 points
<action>Add to Artifacts Generated table:</action>
@@ -252,9 +301,9 @@ Epic: Icon Reliability
<action>Update "Next Action Required":</action>
```
**What to do next:** Run story-context workflow on first story, then dev-story to implement
**What to do next:** Review drafted story-{epic_slug}-1.md, then mark it ready for development
**Command to run:** Load SM agent and run 'story-context' workflow (select story-{epic_slug}-1.md)
**Command to run:** Load SM agent and run 'story-ready' workflow (confirms story-{epic_slug}-1.md is ready)
**Agent to load:** bmad/bmm/agents/sm.md
```
@@ -262,7 +311,7 @@ Epic: Icon Reliability
<action>Add to Decision Log:</action>
```
- **{{date}}**: Level 1 tech-spec and epic/stories generation completed. {{story_count}} stories created. Ready for implementation of story-{epic_slug}-1.md.
- **{{date}}**: Level 1 tech-spec and epic/stories generation completed. {{story_count}} stories created. Skipping Phase 3 (solutioning) - moving directly to Phase 4 (implementation). Story backlog populated. First story (story-{epic_slug}-1.md) drafted and ready for review.
```
<action>Save project-workflow-status.md</action>

106
src/modules/bmm/workflows/3-solutioning/instructions.md
View File

@@ -637,6 +637,112 @@ Generate completion summary:
</action>
<template-output>completion_summary</template-output>
<action>
Prepare for Phase 4 transition - Populate story backlog:
1. Read PRD from {output_folder}/PRD.md or {output_folder}/epics.md
2. Extract all epics and their stories
3. Create ordered backlog list (Epic 1 stories first, then Epic 2, etc.)
For each story in sequence:
- epic_num: Epic number
- story_num: Story number within epic
- story_id: "{{epic_num}}.{{story_num}}" format
- story_title: Story title from PRD/epics
- story_file: "story-{{epic_num}}.{{story_num}}.md"
4. Update project-workflow-status.md with backlog population:
Open {output_folder}/project-workflow-status.md
In "### Implementation Progress (Phase 4 Only)" section:
#### BACKLOG (Not Yet Drafted)
Populate table with ALL stories:
| Epic | Story | ID | Title | File |
|------|-------|----|-------|------|
| 1 | 1 | 1.1 | {{story_title}} | story-1.1.md |
| 1 | 2 | 1.2 | {{story_title}} | story-1.2.md |
| 1 | 3 | 1.3 | {{story_title}} | story-1.3.md |
| 2 | 1 | 2.1 | {{story_title}} | story-2.1.md |
... (all stories)
**Total in backlog:** {{total_story_count}} stories
#### TODO (Needs Drafting)
Initialize with FIRST story:
- **Story ID:** 1.1
- **Story Title:** {{first_story_title}}
- **Story File:** `story-1.1.md`
- **Status:** Not created OR Draft (needs review)
- **Action:** SM should run `create-story` workflow to draft this story
#### IN PROGRESS (Approved for Development)
Leave empty initially:
(Story will be moved here by SM agent `story-ready` workflow)
#### DONE (Completed Stories)
Initialize empty table:
| Story ID | File | Completed Date | Points |
|----------|------|----------------|--------|
| (none yet) | | | |
**Total completed:** 0 stories
**Total points completed:** 0 points
5. Update "Workflow Status Tracker" section:
- Set current_phase = "4-Implementation"
- Set current_workflow = "Ready to begin story implementation"
- Set progress_percentage = {{calculate based on phase completion}}
- Check "3-Solutioning" checkbox in Phase Completion Status
6. Update "Next Action Required" section:
- Set next_action = "Draft first user story"
- Set next_command = "Load SM agent and run 'create-story' workflow"
- Set next_agent = "bmad/bmm/agents/sm.md"
7. Update "Artifacts Generated" table:
Add entries for all generated tech specs
8. Add to Decision Log:
- **{{date}}**: Phase 3 (Solutioning) complete. Architecture and tech specs generated. Populated story backlog with {{total_story_count}} stories. Ready for Phase 4 (Implementation). Next: SM drafts story 1.1.
9. Save project-workflow-status.md
</action>
<ask>
**Phase 3 (Solutioning) Complete!**
✅ Solution architecture generated
✅ Cohesion check passed
✅ {{epic_count}} tech specs generated
✅ Story backlog populated ({{total_story_count}} stories)
**Documents Generated:**
- solution-architecture.md
- cohesion-check-report.md
- tech-spec-epic-1.md through tech-spec-epic-{{epic_count}}.md
**Ready for Phase 4 (Implementation)**
**Next Steps:**
1. Load SM agent: `bmad/bmm/agents/sm.md`
2. Run `create-story` workflow
3. SM will draft story {{first_story_id}}: {{first_story_title}}
4. You review drafted story
5. Run `story-ready` workflow to approve it for development
Would you like to proceed with story drafting now? (y/n)
</ask>
</step>
</workflow>

43
src/modules/bmm/workflows/4-implementation/create-story/instructions.md
View File

@@ -27,6 +27,49 @@
<action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
</step>
<step n="2.5" goal="Check status file TODO section for story to draft">
<action>Read {output_folder}/project-workflow-status.md (if exists)</action>
<action>Navigate to "### Implementation Progress (Phase 4 Only)" section</action>
<action>Find "#### TODO (Needs Drafting)" section</action>
<check if="TODO section has a story">
<action>Extract story information from TODO section:</action>
- todo_story_id: The story ID to draft (e.g., "1.1", "auth-feature-1", "login-fix")
- todo_story_title: The story title (for validation)
- todo_story_file: The exact story file path to create
<critical>This is the PRIMARY source for determining which story to draft</critical>
<critical>DO NOT search or guess - the status file tells you exactly which story to create</critical>
<action>Parse story numbering from todo_story_id:</action>
<check if='todo_story_id matches "N.M" format (e.g., "1.1", "2.3")'>
<action>Set {{epic_num}} = N, {{story_num}} = M</action>
<action>Set {{story_file}} = "story-{{epic_num}}.{{story_num}}.md"</action>
</check>
<check if='todo_story_id matches "slug-N" format (e.g., "auth-feature-1", "icon-reliability-2")'>
<action>Set {{epic_slug}} = slug part, {{story_num}} = N</action>
<action>Set {{story_file}} = "story-{{epic_slug}}-{{story_num}}.md"</action>
</check>
<check if='todo_story_id matches "slug" format (e.g., "login-fix", "icon-migration")'>
<action>Set {{story_slug}} = full slug</action>
<action>Set {{story_file}} = "story-{{story_slug}}.md"</action>
</check>
<action>Validate that {{story_file}} matches {{todo_story_file}} from status file</action>
<action>If mismatch, HALT with error: "Story file mismatch. Status file says: {{todo_story_file}}, derived: {{story_file}}"</action>
<action>Skip old story discovery logic in Step 3 - we know exactly what to draft</action>
</check>
<check if="TODO section is empty OR status file not found">
<action>Fall back to old story discovery logic in Step 3</action>
<action>Note: This is the legacy behavior for projects not using the new status file system</action>
</check>
</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>

266
src/modules/bmm/workflows/4-implementation/story-approved/instructions.md Normal file
View File

@@ -0,0 +1,266 @@
# Story Approved Workflow Instructions (DEV Agent)
<workflow>
<critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
<critical>NO SEARCHING - DEV agent reads status file IN PROGRESS section to know which story was being worked on</critical>
<critical>Workflow: Update story file status, move story IN PROGRESS → DONE, move TODO → IN PROGRESS, move BACKLOG → TODO</critical>
<step n="1" goal="Read status file and identify the IN PROGRESS story">
<action>Read {output_folder}/project-workflow-status.md</action>
<action>Navigate to "### Implementation Progress (Phase 4 Only)" section</action>
<action>Find "#### IN PROGRESS (Approved for Development)" section</action>
<action>Extract current story information:</action>
- current_story_id: The story ID (e.g., "1.1", "auth-feature-1", "login-fix")
- current_story_title: The story title
- current_story_file: The exact story file path
- current_story_points: Story points (if tracked)
<action>Read the TODO section to know what's next:</action>
- todo_story_id: Next story to move to IN PROGRESS (if exists)
- todo_story_title: Next story title
- todo_story_file: Next story file path
<action>Read the BACKLOG section to know what comes after:</action>
- next_backlog_story_id: Story to move to TODO (if exists)
- next_backlog_story_title
- next_backlog_story_file
<critical>DO NOT SEARCH for stories - the status file tells you exactly which story is in each state</critical>
</step>
<step n="2" goal="Update the current story file status to Done">
<action>Read the story file: {story_dir}/{current_story_file}</action>
<action>Find the "Status:" line (usually at the top)</action>
<action>Update story file:</action>
- Change: `Status: Ready` or `Status: In Review`
- To: `Status: Done`
<action>Add completion notes if Dev Agent Record section exists:</action>
Find "## Dev Agent Record" section and add:
```
### Completion Notes
**Completed:** {{date}}
**Definition of Done:** All acceptance criteria met, code reviewed, tests passing, deployed
```
<action>Save the story file</action>
</step>
<step n="3" goal="Move story IN PROGRESS → DONE, advance the queue">
<action>Open {output_folder}/project-workflow-status.md</action>
<action>Update "#### DONE (Completed Stories)" section:</action>
Add the completed story to the table:
| Story ID | File | Completed Date | Points |
| -------------------- | ---------------------- | -------------- | ------------------------ |
| {{current_story_id}} | {{current_story_file}} | {{date}} | {{current_story_points}} |
... (existing done stories)
**Total completed:** {{done_count + 1}} stories
**Total points completed:** {{done_points + current_story_points}} points
<action>Update "#### IN PROGRESS (Approved for Development)" section:</action>
<check if="todo_story exists">
Move the TODO story to IN PROGRESS:
#### IN PROGRESS (Approved for Development)
- **Story ID:** {{todo_story_id}}
- **Story Title:** {{todo_story_title}}
- **Story File:** `{{todo_story_file}}`
- **Story Status:** Ready (OR Draft if not yet reviewed)
- **Context File:** `{{context_file_path}}` (if exists, otherwise note "Context not yet generated")
- **Action:** DEV should run `dev-story` workflow to implement this story
</check>
<check if="todo_story does NOT exist">
Mark IN PROGRESS as empty:
#### IN PROGRESS (Approved for Development)
(No story currently in progress - all stories complete!)
</check>
<action>Update "#### TODO (Needs Drafting)" section:</action>
<check if="next_backlog_story exists">
Move the first BACKLOG story to TODO:
#### TODO (Needs Drafting)
- **Story ID:** {{next_backlog_story_id}}
- **Story Title:** {{next_backlog_story_title}}
- **Story File:** `{{next_backlog_story_file}}`
- **Status:** Not created OR Draft (needs review)
- **Action:** SM should run `create-story` workflow to draft this story
</check>
<check if="next_backlog_story does NOT exist">
Mark TODO as empty:
#### TODO (Needs Drafting)
(No more stories to draft - all stories are drafted or complete)
</check>
<action>Update "#### BACKLOG (Not Yet Drafted)" section:</action>
Remove the first story from the BACKLOG table (the one we just moved to TODO).
If BACKLOG had 1 story and is now empty:
| Epic | Story | ID | Title | File |
| ----------------------------- | ----- | --- | ----- | ---- |
| (empty - all stories drafted) | | | | |
**Total in backlog:** 0 stories
<action>Update story counts in "#### Epic/Story Summary" section:</action>
- Increment done_count by 1
- Increment done_points by {{current_story_points}}
- Decrement backlog_count by 1 (if story was moved from BACKLOG → TODO)
- Update epic breakdown:
- Increment epic_done_stories for the current story's epic
<check if="all stories complete">
<action>Check "4-Implementation" checkbox in "### Phase Completion Status"</action>
<action>Set progress_percentage = 100%</action>
</check>
</step>
<step n="4" goal="Update Decision Log and Next Action">
<action>Add to "## Decision Log" section:</action>
```
- **{{date}}**: Story {{current_story_id}} ({{current_story_title}}) approved and marked done by DEV agent. Moved from IN PROGRESS → DONE. {{#if todo_story}}Story {{todo_story_id}} moved from TODO → IN PROGRESS.{{/if}} {{#if next_backlog_story}}Story {{next_backlog_story_id}} moved from BACKLOG → TODO.{{/if}}
```
<action>Update "### Next Action Required" section:</action>
<check if="todo_story exists">
```
**What to do next:** {{#if todo_story_status == 'Draft'}}Review drafted story {{todo_story_id}}, then mark it ready{{else}}Implement story {{todo_story_id}}{{/if}}
**Command to run:** {{#if todo_story_status == 'Draft'}}Load SM agent and run 'story-ready' workflow{{else}}Run 'dev-story' workflow to implement{{/if}}
**Agent to load:** {{#if todo_story_status == 'Draft'}}bmad/bmm/agents/sm.md{{else}}bmad/bmm/agents/dev.md{{/if}}
```
</check>
<check if="todo_story does NOT exist AND backlog not empty">
```
**What to do next:** Draft the next story ({{next_backlog_story_id}})
**Command to run:** Load SM agent and run 'create-story' workflow
**Agent to load:** bmad/bmm/agents/sm.md
```
</check>
<check if="all stories complete">
```
**What to do next:** All stories complete! Run retrospective workflow or close project.
**Command to run:** Load PM agent and run 'retrospective' workflow
**Agent to load:** bmad/bmm/agents/pm.md
```
</check>
<action>Save project-workflow-status.md</action>
</step>
<step n="5" goal="Confirm completion to user">
<action>Display summary</action>
**Story Approved and Marked Done!**
✅ Story file updated: `{{current_story_file}}` → Status: Done
✅ Status file updated: Story moved IN PROGRESS → DONE
{{#if todo_story}}✅ Next story moved: TODO → IN PROGRESS ({{todo_story_id}}: {{todo_story_title}}){{/if}}
{{#if next_backlog_story}}✅ Next story moved: BACKLOG → TODO ({{next_backlog_story_id}}: {{next_backlog_story_title}}){{/if}}
**Completed Story:**
- **ID:** {{current_story_id}}
- **Title:** {{current_story_title}}
- **File:** `{{current_story_file}}`
- **Points:** {{current_story_points}}
- **Completed:** {{date}}
**Progress Summary:**
- **Stories Completed:** {{done_count}} / {{total_stories}}
- **Points Completed:** {{done_points}} / {{total_points}}
- **Progress:** {{progress_percentage}}%
{{#if all_stories_complete}}
**🎉 ALL STORIES COMPLETE!**
Congratulations! You have completed all stories for this project.
**Next Steps:**
1. Run `retrospective` workflow with PM agent to review the project
2. Close out the project
3. Celebrate! 🎊
{{/if}}
{{#if todo_story}}
**Next Story (IN PROGRESS):**
- **ID:** {{todo_story_id}}
- **Title:** {{todo_story_title}}
- **File:** `{{todo_story_file}}`
- **Status:** {{todo_story_status}}
**Next Steps:**
{{#if todo_story_status == 'Draft'}}
1. Review the drafted story {{todo_story_file}}
2. Load SM agent and run `story-ready` workflow to approve it
3. Then return to DEV agent to implement
{{else}}
1. Stay with DEV agent and run `dev-story` workflow
2. Implement story {{todo_story_id}}
{{/if}}
{{/if}}
{{#if backlog_not_empty AND todo_empty}}
**Next Story (TODO):**
- **ID:** {{next_backlog_story_id}}
- **Title:** {{next_backlog_story_title}}
**Next Steps:**
1. Load SM agent
2. Run `create-story` workflow to draft story {{next_backlog_story_id}}
{{/if}}
</step>
</workflow>
```

41
src/modules/bmm/workflows/4-implementation/story-approved/workflow.yaml Normal file
View File

@@ -0,0 +1,41 @@
# Story Approved Workflow (DEV Agent)
name: story-approved
description: "Marks a story as done (DoD complete) and moves it from IN PROGRESS → DONE in the status file. Advances the story queue. Simple status-update workflow with no searching required."
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/4-implementation/story-approved"
instructions: "{installed_path}/instructions.md"
# Variables and inputs
variables:
story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
status_file: "{output_folder}/project-workflow-status.md" # Status file to update
auto_update_status: true # Always update status file
# Output configuration - no output file, just status updates
default_output_file: ""
required_tools:
- read_file
- edit_file
tags:
- story-management
- status-update
- dev-agent
- bmad-v6
execution_hints:
interactive: false # Minimal prompts; quick status update
autonomous: true # Proceed without user input
iterative: false # Single-pass workflow
web_bundle: false

152
src/modules/bmm/workflows/4-implementation/story-ready/instructions.md Normal file
View File

@@ -0,0 +1,152 @@
# Story Ready Workflow Instructions (SM Agent)
<workflow>
<critical>This workflow is run by SM agent AFTER user reviews a drafted story and confirms it's ready for development</critical>
<critical>NO SEARCHING - SM agent reads status file TODO section to know which story was drafted</critical>
<critical>Simple workflow: Update story file status, move story TODO → IN PROGRESS, move next story BACKLOG → TODO</critical>
<step n="1" goal="Read status file and identify the TODO story">
<action>Read {output_folder}/project-workflow-status.md</action>
<action>Navigate to "### Implementation Progress (Phase 4 Only)" section</action>
<action>Find "#### TODO (Needs Drafting)" section</action>
<action>Extract story information:</action>
- todo_story_id: The story ID (e.g., "1.1", "auth-feature-1", "login-fix")
- todo_story_title: The story title
- todo_story_file: The exact story file path
<critical>DO NOT SEARCH for stories - the status file tells you exactly which story is in TODO</critical>
</step>
<step n="2" goal="Update the story file status">
<action>Read the story file: {story_dir}/{todo_story_file}</action>
<action>Find the "Status:" line (usually at the top)</action>
<action>Update story file:</action>
- Change: `Status: Draft`
- To: `Status: Ready`
<action>Save the story file</action>
</step>
<step n="3" goal="Move story from TODO → IN PROGRESS in status file">
<action>Open {output_folder}/project-workflow-status.md</action>
<action>Update "#### TODO (Needs Drafting)" section:</action>
Read the BACKLOG section to get the next story. If BACKLOG is empty:
#### TODO (Needs Drafting)
(No more stories to draft - all stories are drafted or complete)
If BACKLOG has stories, move the first BACKLOG story to TODO:
#### TODO (Needs Drafting)
- **Story ID:** {{next_backlog_story_id}}
- **Story Title:** {{next_backlog_story_title}}
- **Story File:** `{{next_backlog_story_file}}`
- **Status:** Not created OR Draft (needs review)
- **Action:** SM should run `create-story` workflow to draft this story
<action>Update "#### IN PROGRESS (Approved for Development)" section:</action>
Move the TODO story here:
#### IN PROGRESS (Approved for Development)
- **Story ID:** {{todo_story_id}}
- **Story Title:** {{todo_story_title}}
- **Story File:** `{{todo_story_file}}`
- **Story Status:** Ready
- **Context File:** `{{context_file_path}}` (if exists, otherwise note "Context not yet generated")
- **Action:** DEV should run `dev-story` workflow to implement this story
<action>Update "#### BACKLOG (Not Yet Drafted)" section:</action>
Remove the first story from the BACKLOG table (the one we just moved to TODO).
If BACKLOG had 1 story and is now empty:
| Epic | Story | ID | Title | File |
| ----------------------------- | ----- | --- | ----- | ---- |
| (empty - all stories drafted) | | | | |
**Total in backlog:** 0 stories
<action>Update story counts in "#### Epic/Story Summary" section:</action>
- Decrement backlog_count by 1 (if story was moved from BACKLOG → TODO)
- Keep in_progress_count = 1
- Keep todo_count = 1 or 0 (depending on if there's a next story)
</step>
<step n="4" goal="Update Decision Log and Next Action">
<action>Add to "## Decision Log" section:</action>
```
- **{{date}}**: Story {{todo_story_id}} ({{todo_story_title}}) marked ready for development by SM agent. Moved from TODO → IN PROGRESS. {{#if next_story}}Next story {{next_story_id}} moved from BACKLOG → TODO.{{/if}}
```
<action>Update "### Next Action Required" section:</action>
```
**What to do next:** Generate context for story {{todo_story_id}}, then implement it
**Command to run:** Run 'story-context' workflow to generate implementation context (or skip to dev-story)
**Agent to load:** bmad/bmm/agents/sm.md (for story-context) OR bmad/bmm/agents/dev.md (for dev-story)
```
<action>Save project-workflow-status.md</action>
</step>
<step n="5" goal="Confirm completion to user">
<action>Display summary</action>
**Story Marked Ready for Development!**
✅ Story file updated: `{{todo_story_file}}` → Status: Ready
✅ Status file updated: Story moved TODO → IN PROGRESS
{{#if next_story}}✅ Next story moved: BACKLOG → TODO ({{next_story_id}}: {{next_story_title}}){{/if}}
{{#if no_more_stories}}✅ All stories have been drafted - backlog is empty{{/if}}
**Current Story (IN PROGRESS):**
- **ID:** {{todo_story_id}}
- **Title:** {{todo_story_title}}
- **File:** `{{todo_story_file}}`
- **Status:** Ready for development
**Next Steps:**
1. **Recommended:** Run `story-context` workflow to generate implementation context
- This creates a comprehensive context XML for the DEV agent
- Includes relevant architecture, dependencies, and existing code
2. **Alternative:** Skip context generation and go directly to `dev-story` workflow
- Faster, but DEV agent will have less context
- Only recommended for simple, well-understood stories
**To proceed:**
- For context generation: Stay with SM agent and run `story-context` workflow
- For direct implementation: Load DEV agent and run `dev-story` workflow
</step>
</workflow>

41
src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml Normal file
View File

@@ -0,0 +1,41 @@
# Story Ready Workflow (SM Agent)
name: story-ready
description: "Marks a drafted story as ready for development and moves it from TODO → IN PROGRESS in the status file. Simple status-update workflow with no searching required."
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/4-implementation/story-ready"
instructions: "{installed_path}/instructions.md"
# Variables and inputs
variables:
story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
status_file: "{output_folder}/project-workflow-status.md" # Status file to update
auto_update_status: true # Always update status file
# Output configuration - no output file, just status updates
default_output_file: ""
required_tools:
- read_file
- edit_file
tags:
- story-management
- status-update
- sm-agent
- bmad-v6
execution_hints:
interactive: false # Minimal prompts; quick status update
autonomous: true # Proceed without user input
iterative: false # Single-pass workflow
web_bundle: false

214
src/modules/bmm/workflows/README.md
View File

@@ -1,5 +1,5 @@
---
last-redoc-date: 2025-10-01
last-redoc-date: 2025-10-12
---
# BMM Workflows - The Complete v6 Flow
@@ -86,13 +86,19 @@ The central orchestrator that determines project scale and generates appropriate
### Scale Levels
| Level | Scope | Outputs | Next Phase |
| ----- | ------------------------ | ----------------------- | ---------------- |
| **0** | Single atomic change | tech-spec only | → Implementation |
| **1** | 1-10 stories, 1 epic | Minimal PRD + tech-spec | → Implementation |
| **2** | 5-15 stories, 1-2 epics | Focused PRD + tech-spec | → Implementation |
| **3** | 12-40 stories, 2-5 epics | Full PRD + Epics list | → Solutioning |
| **4** | 40+ stories, 5+ epics | Enterprise PRD + Epics | → Solutioning |
| Level | Scope | Outputs | Next Phase |
| ----- | ------------------------ | ------------------------------ | ---------------- |
| **0** | Single atomic change | tech-spec + 1 story | → Implementation |
| **1** | 1-10 stories, 1 epic | tech-spec + epic + 2-3 stories | → Implementation |
| **2** | 5-15 stories, 1-2 epics | Focused PRD + tech-spec | → Implementation |
| **3** | 12-40 stories, 2-5 epics | Full PRD + Epics list | → Solutioning |
| **4** | 40+ stories, 5+ epics | Enterprise PRD + Epics | → Solutioning |
**Key Changes (v6a):**
- **Level 0**: Now generates a single user story in addition to tech-spec
- **Level 1**: Now generates 2-3 stories as part of planning (prefer longer stories over more stories)
- Both Level 0/1 skip Phase 3 and populate Phase 4 story backlog automatically
### Routing Logic
@@ -114,11 +120,14 @@ plan-project
### Key Outputs
- **PRD.md**: Product Requirements Document (Levels 1-4)
- **PRD.md**: Product Requirements Document (Levels 2-4)
- **Epics.md**: Epic breakdown with stories (Levels 2-4)
- **epic-stories.md**: Epic summary with story links (Level 1)
- **tech-spec.md**: Technical specification (Levels 0-2 only)
- **story-{slug}.md**: Single user story (Level 0)
- **story-{slug}-1.md, story-{slug}-2.md, story-{slug}-3.md**: User stories (Level 1)
- **GDD.md**: Game Design Document (game projects)
- **project-workflow-status.md**: Workflow state tracking
- **project-workflow-status-YYYY-MM-DD.md**: Versioned workflow state tracking with story backlog
## Phase 3: Solutioning (Levels 3-4 Only)
@@ -149,62 +158,128 @@ FOR each epic in sequence:
The core development cycle that transforms requirements into working software.
### The Story State Machine
Phase 4 uses a 4-state lifecycle to manage story progression, tracked in `project-workflow-status.md`:
```
BACKLOG → TODO → IN PROGRESS → DONE
```
#### State Definitions
- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition)
- Contains all stories with IDs, titles, and file names
- Order is sequential (Epic 1 stories first, then Epic 2, etc.)
- **TODO**: Single story that needs drafting (or drafted, awaiting approval)
- SM drafts story here using `create-story` workflow
- Story status is "Draft" until user approves
- User runs `story-ready` workflow to approve
- **IN PROGRESS**: Single story approved for development
- Moved here by `story-ready` workflow
- DEV implements using `dev-story` workflow
- Story status is "Ready" or "In Review"
- **DONE**: Completed stories with dates and points
- Moved here by `story-approved` workflow after DoD complete
- Immutable record of completed work
**Key Innovation**: Agents never search for "next story" - they always read the exact story from the status file.
### The Implementation Loop
```
┌─────────────────────────────────────────┐
│ SM: create-story │
│ (Generate next story from epics.md) │
└─────────────────────┬───────────────────┘
↓
┌─────────────────────────────────────────┐
│ SM: story-context │
│ (Generate expertise injection XML) │
└─────────────────────┬───────────────────┘
↓
┌─────────────────────────────────────────┐
│ DEV: dev-story │
│ (Implement with context injection) │
└─────────────────────┬───────────────────┘
↓
┌─────────────────────────────────────────┐
│ SR/DEV: review-story │
│ (Validate against criteria) │
└─────────────────────┬───────────────────┘
↓
┌─────────┴─────────┐
│ Issues Found? │
└─────────┬─────────┘
┌─────┴─────┐
↓ ↓
[No: Next Story] [Yes: correct-course]
↓
[Return to appropriate step]
Phase Transition (Phase 2 or 3 → Phase 4)
↓
┌─────────────────────────────────────────────────┐
│ BACKLOG populated with all stories │
│ TODO initialized with first story │
└───────────────────┬─────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ SM: create-story (drafts story in TODO) │
│ Reads: status file TODO section │
│ Output: Story file with Status="Draft" │
└───────────────────┬─────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ User reviews story │
│ ↓ │
│ SM: story-ready (approves story) │
│ Actions: TODO → IN PROGRESS │
│ BACKLOG → TODO (next story) │
│ Story Status = "Ready" │
└───────────────────┬─────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ SM: story-context (optional but recommended) │
│ Generates expertise injection XML │
└───────────────────┬─────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ DEV: dev-story (implements story) │
│ Reads: status file IN PROGRESS section │
│ Implements with context injection │
└───────────────────┬─────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ User reviews implementation (DoD check) │
│ ↓ │
│ DEV: story-approved (marks story done) │
│ Actions: IN PROGRESS → DONE │
│ TODO → IN PROGRESS (if exists) │
│ BACKLOG → TODO (if exists) │
│ Story Status = "Done" │
└───────────────────┬─────────────────────────────┘
↓
┌───────┴────────┐
│ More stories? │
└───────┬─────────┘
┌───┴───┐
↓ ↓
[Yes: Loop] [No: Epic/Project Complete]
↓
[retrospective]
```
### Workflow Responsibilities
| Workflow | Agent | Purpose | Key Innovation |
| ------------------ | ------ | ---------------------------- | -------------------------- |
| **create-story** | SM | Generate ONE story at a time | Enforces epics.md planning |
| **story-context** | SM | Create expertise injection | JIT technical guidance |
| **dev-story** | DEV | Implement with context | Resumable after review |
| **review-story** | SR/DEV | Comprehensive validation | Fresh context review |
| **correct-course** | SM | Handle issues/changes | Adaptive response |
| **retrospective** | SM | Capture epic learnings | Continuous improvement |
| Workflow | Agent | Purpose | State Transition | No Search Required |
| ------------------ | ------ | ------------------------------------- | --------------------- | ------------------------ |
| **create-story** | SM | Draft story from TODO section | (Story stays in TODO) | Reads TODO section |
| **story-ready** | SM | Approve drafted story for development | TODO → IN PROGRESS | Reads TODO section |
| **story-context** | SM | Generate expertise injection XML | (No state change) | Reads IN PROGRESS |
| **dev-story** | DEV | Implement story | (No state change) | Reads IN PROGRESS |
| **story-approved** | DEV | Mark story done after DoD complete | IN PROGRESS → DONE | Reads IN PROGRESS |
| **review-story** | SR/DEV | Quality validation (optional) | (No state change) | Manual story selection |
| **correct-course** | SM | Handle issues/changes | (Adaptive) | Manual story selection |
| **retrospective** | SM | Capture epic learnings | (No state change) | Manual or epic-triggered |
### Story Flow States
### Story File Status Values
Stories have a `Status:` field in their markdown file that reflects their position in the state machine:
```
Draft (create-story)
→ Approved (SM approval)
→ In Progress (dev-story)
→ Ready for Review (dev complete)
→ Done (review passed)
OR
→ In Progress (review failed, back to dev)
Status: Draft (Story created by create-story, awaiting user review)
↓
Status: Ready (User approved via story-ready, ready for implementation)
↓
Status: In Review (Implementation complete, awaiting final approval)
↓
Status: Done (User approved via story-approved, DoD complete)
```
**Status File Position vs Story File Status:**
| Status File State | Story File Status | Meaning |
| ----------------- | -------------------- | ------------------------------------- |
| BACKLOG | (file doesn't exist) | Story not yet drafted |
| TODO | Draft | Story drafted, awaiting user approval |
| IN PROGRESS | Ready or In Review | Story approved for development |
| DONE | Done | Story complete, DoD met |
## Greenfield vs Brownfield Considerations
### Greenfield Projects
@@ -251,13 +326,24 @@ plan-project (Phase 2)
### Tracking Documents
- **project-workflow-status.md**: Maintains workflow state, level, and progress
- **Epics.md**: Master list of epics and stories (source of truth for planning)
- **project-workflow-status-YYYY-MM-DD.md**: Versioned workflow state tracking with 4-section story backlog
- **BACKLOG**: Ordered list of stories to be drafted
- **TODO**: Single story ready for drafting (or drafted, awaiting approval)
- **IN PROGRESS**: Single story approved for development
- **DONE**: Completed stories with dates and points
- Populated automatically at phase transitions
- Single source of truth for story progression
- Agents read (never search) to know what to work on next
- **Epics.md**: Master list of epics and stories (source of truth for planning, Level 2-4)
### Phase Outputs
- **Phase 1**: Briefs and research documents
- **Phase 2**: PRD, Epics, or tech-spec based on level
- **Phase 2**:
- Level 0: tech-spec.md + story-{slug}.md
- Level 1: tech-spec.md + epic-stories.md + story-{slug}-N.md files
- Level 2-4: PRD.md, Epics.md, or tech-spec.md based on level
- **Phase 3**: solution-architecture.md, epic-specific tech specs
- **Phase 4**: Story files, context XMLs, implemented code
@@ -320,12 +406,14 @@ bmad architect solution-architecture
bmad architect tech-spec # Per epic, JIT
# Phase 4: Implementation
bmad sm create-story # One at a time
bmad sm story-context # After each story
bmad dev develop # With context loaded
bmad dev review-story # Or SR agent
bmad sm correct-course # If issues
bmad sm retrospective # After epic
bmad sm create-story # Draft story from TODO section
bmad sm story-ready # Approve story for development (after user review)
bmad sm story-context # Generate context XML (optional but recommended)
bmad dev dev-story # Implement story from IN PROGRESS section
bmad dev story-approved # Mark story done (after user confirms DoD)
bmad dev review-story # Quality validation (optional)
bmad sm correct-course # If issues arise
bmad sm retrospective # After epic complete
```
## Future Enhancements

148
src/modules/bmm/workflows/_shared/project-workflow-status-template.md
View File

@@ -27,38 +27,109 @@
{{#if in_phase_4}}
#### Current Work In Progress
#### BACKLOG (Not Yet Drafted)
- **Current Epic:** {{current_epic_number}} - {{current_epic_title}}
- **Current Story:** {{current_story_number}} - {{current_story_title}}
**Ordered story sequence - populated at Phase 4 start:**
| Epic | Story | ID | Title | File |
| ---- | ----- | --- | ----- | ---- |
{{#backlog_stories}}
| {{epic_num}} | {{story_num}} | {{story_id}} | {{story_title}} | {{story_file}} |
{{/backlog_stories}}
**Total in backlog:** {{backlog_count}} stories
**Instructions:**
- Stories move from BACKLOG → TODO when previous story is complete
- SM agent uses story information from this table to draft new stories
- Story order is sequential (Epic 1 stories first, then Epic 2, etc.)
#### TODO (Needs Drafting)
- **Story ID:** {{todo_story_id}}
- **Story Title:** {{todo_story_title}}
- **Story File:** `{{todo_story_file}}`
- **Status:** Not created OR Draft (needs review)
- **Action:** SM should run `create-story` workflow to draft this story
**Instructions:**
- Only ONE story in TODO at a time
- Story stays in TODO until user marks it "ready for development"
- SM reads this section to know which story to draft next
- After SM creates/updates story, user reviews and approves via `story-ready` workflow
#### IN PROGRESS (Approved for Development)
- **Story ID:** {{current_story_id}}
- **Story Title:** {{current_story_title}}
- **Story File:** `{{current_story_file}}`
- **Story Status:** {{current_story_status}}
- **Story Status:** Ready | In Review
- **Context File:** `{{current_story_context_file}}`
- **Action:** DEV should run `dev-story` workflow to implement this story
#### Next Story To Work On
**Instructions:**
- **Next Epic:** {{next_epic_number}} - {{next_epic_title}}
- **Next Story:** {{next_story_number}} - {{next_story_title}}
- **Next Story File:** `{{next_story_file}}`
- Only ONE story in IN PROGRESS at a time
- Story stays here until user marks it "approved" (DoD complete)
- DEV reads this section to know which story to implement
- After DEV completes story, user reviews and runs `story-approved` workflow
**Logic:** Next story is determined by:
#### DONE (Completed Stories)
1. If current epic has more stories → next story in same epic
2. If current epic complete → first story of next epic
3. If all epics complete → Project complete!
| Story ID | File | Completed Date | Points |
| -------- | ---- | -------------- | ------ |
{{#done_stories}}
| {{story_id}} | {{story_file}} | {{completed_date}} | {{story_points}} |
{{/done_stories}}
**Total completed:** {{done_count}} stories
**Total points completed:** {{done_points}} points
**Instructions:**
- Stories move here when user runs `story-approved` workflow (DEV agent)
- Immutable record of completed work
- Used for velocity tracking and progress reporting
#### Epic/Story Summary
**Total Epics:** {{total_epics}}
**Total Stories:** {{total_stories}}
**Completed Stories:** {{completed_stories}}
**Remaining Stories:** {{remaining_stories}}
**Stories in Backlog:** {{backlog_count}}
**Stories in TODO:** {{todo_count}} (should always be 0 or 1)
**Stories in IN PROGRESS:** {{in_progress_count}} (should always be 0 or 1)
**Stories DONE:** {{done_count}}
**Epic Breakdown:**
{{#epics}}
- Epic {{epic_number}}: {{epic_title}} ({{epic_completed_stories}}/{{epic_total_stories}} stories complete)
- Epic {{epic_number}}: {{epic_title}} ({{epic_done_stories}}/{{epic_total_stories}} stories complete)
{{/epics}}
#### State Transition Logic
**Story Lifecycle:**
```
BACKLOG → TODO → IN PROGRESS → DONE
```
**Transition Rules:**
1. **BACKLOG → TODO**: Automatically when previous story moves TODO → IN PROGRESS
2. **TODO → IN PROGRESS**: User runs SM agent `story-ready` workflow after reviewing drafted story
3. **IN PROGRESS → DONE**: User runs DEV agent `story-approved` workflow after DoD complete
**Important:**
- SM agent NEVER searches for "next story" - always reads TODO section
- DEV agent NEVER searches for "current story" - always reads IN PROGRESS section
- Both agents update this status file after their workflows complete
{{/if}}
### Artifacts Generated
@@ -176,27 +247,52 @@
**When to use this file:**
- Running create-story workflow → Read "Next Story To Work On" section
- Checking epic/story progress → Read "Implementation Progress" section
- Updating story status → Update "Current Story Status" and recalculate next story
- Running `create-story` workflow → Read "TODO (Needs Drafting)" section for exact story to draft
- Running `story-ready` workflow → Update status file, move story from TODO → IN PROGRESS, move next story from BACKLOG → TODO
- Checking epic/story progress → Read "Epic/Story Summary" section
**Key fields:**
**Key fields to read:**
- `next_story_file` → The exact file path to create
- `next_epic_number` + `next_story_number` → For story numbering
- `todo_story_id` → The story ID to draft (e.g., "1.1", "auth-feature-1")
- `todo_story_title` → The story title for drafting
- `todo_story_file` → The exact file path to create
**Key fields to update:**
- Move completed TODO story → IN PROGRESS section
- Move next BACKLOG story → TODO section
- Update story counts
**Workflows:**
1. `create-story` - Drafts the story in TODO section (user reviews it)
2. `story-ready` - After user approval, moves story TODO → IN PROGRESS
### For DEV (Developer) Agent
**When to use this file:**
- Running dev-story workflow → Read "Current Work In Progress" section
- After completing story → Update status to "Complete", recalculate next story
- Checking what to work on → Read "Next Story To Work On"
- Running `dev-story` workflow → Read "IN PROGRESS (Approved for Development)" section for current story
- Running `story-approved` workflow → Update status file, move story from IN PROGRESS → DONE, move TODO story → IN PROGRESS, move BACKLOG story → TODO
- Checking what to work on → Read "IN PROGRESS" section
**Key fields:**
**Key fields to read:**
- `current_story_file` → The story to implement
- `current_story_status` → Update after completion
- `current_story_context_file` → The context XML for this story
- `current_story_status` → Current status (Ready | In Review)
**Key fields to update:**
- Move completed IN PROGRESS story → DONE section with completion date
- Move TODO story → IN PROGRESS section
- Move next BACKLOG story → TODO section
- Update story counts and points
**Workflows:**
1. `dev-story` - Implements the story in IN PROGRESS section
2. `story-approved` - After user approval (DoD complete), moves story IN PROGRESS → DONE
### For PM (Product Manager) Agent