From 7d6aae1b7896f6d5d43654bd561abaab6ae94ac2 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Thu, 11 Dec 2025 21:20:44 -0700 Subject: [PATCH] fix(bmm): remove stale 'drafted' story state from docs and workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `drafted` story state is no longer used since create-story now sets status directly to `ready-for-dev`. This PR removes all references to this legacy state from BMM documentation and workflow files. Changes: - Remove `drafted` from story status definitions and state machine docs - Remove dead story-context file detection (story-context files no longer exist) - Replace "draft" verb with "create" in story-related messaging - Add legacy `drafted` → `ready-for-dev` migration in sprint-status - Clarify that validate-create-story is optional and doesn't change status - Document story handoff sequence: create-story → (optional) validate → dev-story Story lifecycle is now: backlog → ready-for-dev → in-progress → review → done Closes #1089 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- src/modules/bmm/README.md | 2 +- src/modules/bmm/agents/sm.agent.yaml | 4 ++-- src/modules/bmm/docs/agents-guide.md | 8 ++++--- src/modules/bmm/docs/brownfield-guide.md | 4 ++-- src/modules/bmm/docs/glossary.md | 7 +++--- src/modules/bmm/docs/quick-start.md | 4 ++-- .../create-story/instructions.xml | 6 ++--- .../4-implementation/create-story/template.md | 8 +++---- .../dev-story/instructions.xml | 6 +++-- .../retrospective/instructions.md | 2 +- .../sprint-planning/instructions.md | 23 +++++++------------ .../sprint-status-template.yaml | 7 +++--- .../sprint-status/instructions.md | 12 +++++----- 13 files changed, 43 insertions(+), 50 deletions(-) diff --git a/src/modules/bmm/README.md b/src/modules/bmm/README.md index 047c8581..2859b929 100644 --- a/src/modules/bmm/README.md +++ b/src/modules/bmm/README.md @@ -93,7 +93,7 @@ BMM automatically adjusts to project complexity (Levels 0-4): ### Story-Centric Implementation -Stories move through a defined lifecycle: `backlog → drafted → ready → in-progress → review → done` +Stories move through a defined lifecycle: `backlog → ready-for-dev → in-progress → review → done` Just-in-time epic context and story context provide exact expertise when needed. diff --git a/src/modules/bmm/agents/sm.agent.yaml b/src/modules/bmm/agents/sm.agent.yaml index ee7ecc08..426b9866 100644 --- a/src/modules/bmm/agents/sm.agent.yaml +++ b/src/modules/bmm/agents/sm.agent.yaml @@ -30,11 +30,11 @@ agent: - trigger: create-story workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/create-story/workflow.yaml" - description: Create a Draft Story (Required to prepare stories for development) + description: Create Story (Required to prepare stories for development) - trigger: validate-create-story validate-workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/create-story/workflow.yaml" - description: Validate Story Draft (Highly Recommended, use fresh context and different LLM for best results) + description: Validate Story (Highly Recommended, use fresh context and different LLM for best results) - trigger: epic-retrospective workflow: "{project-root}/.bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml" diff --git a/src/modules/bmm/docs/agents-guide.md b/src/modules/bmm/docs/agents-guide.md index ccf74fa7..c96c9cd4 100644 --- a/src/modules/bmm/docs/agents-guide.md +++ b/src/modules/bmm/docs/agents-guide.md @@ -180,11 +180,13 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age - `workflow-status` - Check what to do next - `sprint-planning` - Initialize `sprint-status.yaml` tracking -- `create-story` - Draft next story from epic -- `validate-create-story` - Independent story validation +- `create-story` - Create next story from epic (sets status to `ready-for-dev`) +- `validate-create-story` - Optional quality check (does not change status; run before dev-story for extra validation) - `epic-retrospective` - Post-epic review - `correct-course` - Handle changes during implementation +**Story handoff sequence:** `create-story` → (optional) `validate-create-story` → `dev-story` + **Communication Style:** Task-oriented and efficient. Direct and eliminates ambiguity. Focuses on clear handoffs and developer-ready specifications. **Expertise:** @@ -644,7 +646,7 @@ Many workflows have optional validation workflows that perform independent revie | -------------------------- | ----------- | ------------------------------------------ | | `implementation-readiness` | Architect | PRD + Architecture + Epics + UX (optional) | | `validate-design` | UX Designer | UX specification and artifacts | -| `validate-create-story` | SM | Story draft | +| `validate-create-story` | SM | Story file | **When to use validation:** diff --git a/src/modules/bmm/docs/brownfield-guide.md b/src/modules/bmm/docs/brownfield-guide.md index ef027226..9cb50760 100644 --- a/src/modules/bmm/docs/brownfield-guide.md +++ b/src/modules/bmm/docs/brownfield-guide.md @@ -340,7 +340,7 @@ flowchart TD **Status Progression:** - Epic: `backlog → in-progress → done` -- Story: `backlog → drafted → ready-for-dev → in-progress → review → done` +- Story: `backlog → ready-for-dev → in-progress → review → done` **Brownfield-Specific Implementation Tips:** @@ -397,7 +397,7 @@ Document in tech-spec/architecture: ### 8. Use Sprint Planning Effectively - Run `sprint-planning` at Phase 4 start -- Context epics before drafting stories +- Context epics before creating stories - Update `sprint-status.yaml` as work progresses ### 9. Learn Continuously diff --git a/src/modules/bmm/docs/glossary.md b/src/modules/bmm/docs/glossary.md index f2a6a6c7..d611b96c 100644 --- a/src/modules/bmm/docs/glossary.md +++ b/src/modules/bmm/docs/glossary.md @@ -186,12 +186,11 @@ Multi-agent collaboration feature where all installed agents (19+ from BMM, CIS, ### Story Status Progression ``` -backlog → drafted → ready-for-dev → in-progress → review → done +backlog → ready-for-dev → in-progress → review → done ``` -- **backlog** - Story exists in epic but not yet drafted -- **drafted** - Story file created by SM via create-story -- **ready-for-dev** - Story drafted and reviewed, ready for DEV +- **backlog** - Story exists in epic but not yet created +- **ready-for-dev** - Story file created via create-story; validation is optional (run `validate-create-story` for quality check before dev picks it up) - **in-progress** - DEV is implementing via dev-story - **review** - Implementation complete, awaiting code-review - **done** - Completed with DoD met diff --git a/src/modules/bmm/docs/quick-start.md b/src/modules/bmm/docs/quick-start.md index 0560b6de..193c1bc3 100644 --- a/src/modules/bmm/docs/quick-start.md +++ b/src/modules/bmm/docs/quick-start.md @@ -200,12 +200,12 @@ Once planning and architecture are complete, you'll move to Phase 4. **Important 3. Tell the agent: "Run sprint-planning" 4. This creates your `sprint-status.yaml` file that tracks all epics and stories -#### 3.2 Draft Your First Story +#### 3.2 Create Your First Story 1. **Start a new chat** with the **SM agent** 2. Wait for the menu 3. Tell the agent: "Run create-story" -4. This drafts the story file from the epic +4. This creates the story file from the epic #### 3.3 Implement the Story diff --git a/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml index 8665faec..3c908c80 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml @@ -30,7 +30,7 @@ **Required Options:** 1. Run `sprint-planning` to initialize sprint tracking (recommended) - 2. Provide specific epic-story number to draft (e.g., "1-2-user-auth") + 2. Provide specific epic-story number to create (e.g., "1-2-user-auth") 3. Provide path to story documents if sprint status doesn't exist yet Choose option [1], provide epic-story number, path to story docs, or [q] to quit: @@ -72,7 +72,7 @@ 📋 No backlog stories found in sprint-status.yaml - All stories are either already drafted, in progress, or done. + All stories are either already created, in progress, or done. **Options:** 1. Run sprint-planning to refresh story tracking @@ -129,7 +129,7 @@ 📋 No backlog stories found in sprint-status.yaml - All stories are either already drafted, in progress, or done. + All stories are either already created, in progress, or done. **Options:** 1. Run sprint-planning to refresh story tracking diff --git a/src/modules/bmm/workflows/4-implementation/create-story/template.md b/src/modules/bmm/workflows/4-implementation/create-story/template.md index 6aa80bad..c4e129f5 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/template.md +++ b/src/modules/bmm/workflows/4-implementation/create-story/template.md @@ -1,6 +1,8 @@ # Story {{epic_num}}.{{story_num}}: {{story_title}} -Status: drafted +Status: ready-for-dev + + ## Story @@ -36,10 +38,6 @@ so that {{benefit}}. ## Dev Agent Record -### Context Reference - - - ### Agent Model Used {{agent_model_name_version}} diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml index 507abceb..1dd5df41 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml @@ -40,9 +40,11 @@ **What would you like to do?** 1. Run `create-story` to create next story from epics with comprehensive context - 2. Run `*validate-create-story` to improve existing drafted stories before development + 2. Run `*validate-create-story` to improve existing stories before development (recommended quality check) 3. Specify a particular story file to develop (provide full path) 4. Check {{sprint_status}} file to see current sprint status + + 💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality check. Choose option [1], [2], [3], or [4], or specify story file path: @@ -85,7 +87,7 @@ **Available Options:** 1. Run `create-story` to create next story from epics with comprehensive context - 2. Run `*validate-create-story` to improve existing drafted stories + 2. Run `*validate-create-story` to improve existing stories 3. Specify which story to develop What would you like to do? Choose option [1], [2], or [3]: diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md index 29fa52fb..0b5a1d98 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md @@ -1396,7 +1396,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need {{else}} 4. **Begin Epic {{next_epic_num}} when ready** - - Start drafting stories with SM agent's `create-story` + - Start creating stories with SM agent's `create-story` - Epic will be marked as `in-progress` automatically when first story is created - Ensure all critical path items are done first {{/if}} diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md index 8bae8f67..bf1f280f 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md @@ -73,22 +73,17 @@ development_status: **Story file detection:** - Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`) -- If exists → upgrade status to at least `drafted` - -**Story context detection:** - -- Check: `{story_location_absolute}/{story-key}-context.md` (e.g., `stories/1-1-user-authentication-context.md`) - If exists → upgrade status to at least `ready-for-dev` **Preservation rule:** - If existing `{status_file}` exists and has more advanced status, preserve it -- Never downgrade status (e.g., don't change `done` to `drafted`) +- Never downgrade status (e.g., don't change `done` to `ready-for-dev`) **Status Flow Reference:** - Epic: `backlog` → `in-progress` → `done` -- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done` +- Story: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done` - Retrospective: `optional` ↔ `completed` @@ -117,8 +112,7 @@ development_status: # # Story Status: # - backlog: Story only exists in epic file -# - drafted: Story file created in stories folder -# - ready-for-dev: Draft approved and story context created +# - ready-for-dev: Story file created in stories folder # - in-progress: Developer actively working on implementation # - review: Ready for code review (via Dev's code-review workflow) # - done: Story completed @@ -131,7 +125,7 @@ development_status: # =============== # - Epic transitions to 'in-progress' automatically when first story is created # - Stories can be worked in parallel if team capacity allows -# - SM typically drafts next story after previous one is 'done' to incorporate learnings +# - SM typically creates next story after previous one is 'done' to incorporate learnings # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended) generated: { date } @@ -198,18 +192,17 @@ backlog → in-progress → done ``` - **backlog**: Epic not yet started -- **in-progress**: Epic actively being worked on (stories being drafted/implemented) +- **in-progress**: Epic actively being worked on (stories being created/implemented) - **done**: All stories in epic completed **Story Status Flow:** ``` -backlog → drafted → ready-for-dev → in-progress → review → done +backlog → ready-for-dev → in-progress → review → done ``` - **backlog**: Story only exists in epic file -- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`) -- **ready-for-dev**: Draft approved + story context created +- **ready-for-dev**: Story file created (e.g., `stories/1-3-plant-naming.md`) - **in-progress**: Developer actively working - **review**: Ready for code review (via Dev's code-review workflow) - **done**: Completed @@ -229,4 +222,4 @@ optional ↔ completed 2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported 3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows 4. **Review Before Done**: Stories should pass through `review` before `done` -5. **Learning Transfer**: SM typically drafts next story after previous one is `done` to incorporate learnings +5. **Learning Transfer**: SM typically creates next story after previous one is `done` to incorporate learnings diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml b/src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml index b741a050..fbfea426 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml @@ -17,8 +17,7 @@ # # Story Status: # - backlog: Story only exists in epic file -# - drafted: Story file created in stories folder -# - ready-for-dev: Draft approved, ready for development +# - ready-for-dev: Story file created, ready for development # - in-progress: Developer actively working on implementation # - review: Implementation complete, ready for review # - done: Story completed @@ -30,7 +29,7 @@ # WORKFLOW NOTES: # =============== # - Mark epic as 'in-progress' when starting work on its first story -# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings +# - SM typically creates next story ONLY after previous one is 'done' to incorporate learnings # - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM) # EXAMPLE STRUCTURE (your actual epics/stories will replace these): @@ -44,7 +43,7 @@ story_location: "{story_location}" development_status: epic-1: backlog 1-1-user-authentication: done - 1-2-account-management: drafted + 1-2-account-management: ready-for-dev 1-3-plant-data-model: backlog 1-4-add-plant-manual: backlog epic-1-retrospective: optional diff --git a/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md index cbf3a9f9..ab0fdecf 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md @@ -40,12 +40,14 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat - Epics: keys starting with "epic-" (and not ending with "-retrospective") - Retrospectives: keys ending with "-retrospective" - Stories: everything else (e.g., 1-2-login-form) - Count story statuses: backlog, drafted, ready-for-dev, in-progress, review, done + If any story has status `drafted`, treat as `ready-for-dev` (legacy status) + Count story statuses: backlog, ready-for-dev, in-progress, review, done Count epic statuses: backlog, contexted Detect risks: - Stories in review but no reviewer assigned context → suggest `/bmad:bmm:workflows:code-review` - Stories in in-progress with no ready-for-dev items behind them → keep focus on the active story - - All epics backlog/contexted but no stories drafted → prompt to run `/bmad:bmm:workflows:create-story` + - All epics backlog/contexted but no stories ready-for-dev → prompt to run `/bmad:bmm:workflows:create-story` + - Stories in ready-for-dev may be unvalidated → suggest `/bmad:bmm:workflows:validate-create-story` before `dev-story` for quality check @@ -67,7 +69,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat - Tracking: {{tracking_system}} - Status file: {sprint_status_file} -**Stories:** backlog {{count_backlog}}, drafted {{count_drafted}}, ready-for-dev {{count_ready}}, in-progress {{count_in_progress}}, review {{count_review}}, done {{count_done}} +**Stories:** backlog {{count_backlog}}, ready-for-dev {{count_ready}}, in-progress {{count_in_progress}}, review {{count_review}}, done {{count_done}} **Epics:** backlog {{epic_backlog}}, contexted {{epic_contexted}} @@ -85,7 +87,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat **Per Epic:** {{#each by_epic}} -- {{epic_id}}: context={{context_status}}, stories → backlog {{backlog}}, drafted {{drafted}}, ready {{ready_for_dev}}, in-progress {{in_progress}}, review {{review}}, done {{done}} +- {{epic_id}}: context={{context_status}}, stories → backlog {{backlog}}, ready {{ready_for_dev}}, in-progress {{in_progress}}, review {{review}}, done {{done}} {{/each}} {{/if}} @@ -110,7 +112,6 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. - In Progress: {{stories_in_progress}} - Review: {{stories_in_review}} - Ready for Dev: {{stories_ready_for_dev}} -- Drafted: {{stories_drafted}} - Backlog: {{stories_backlog}} - Done: {{stories_done}} @@ -135,7 +136,6 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. next_workflow_id = {{next_workflow_id}} next_story_id = {{next_story_id}} count_backlog = {{count_backlog}} - count_drafted = {{count_drafted}} count_ready = {{count_ready}} count_in_progress = {{count_in_progress}} count_review = {{count_review}}