fix(bmm): remove stale 'drafted' story state from docs and workflows

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 <noreply@anthropic.com>

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.
 

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"

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
+- `create-story` - Create next story from epic (sets status to `ready-for-dev`)
-- `validate-create-story` - Independent story validation
+- `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:**
 

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

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
+- **backlog** - Story exists in epic but not yet created
-- **drafted** - Story file created by SM via create-story
+- **ready-for-dev** - Story file created via create-story; validation is optional (run `validate-create-story` for quality check before dev picks it up)
-- **ready-for-dev** - Story drafted and reviewed, ready for DEV
 - **in-progress** - DEV is implementing via dev-story
 - **review** - Implementation complete, awaiting code-review
 - **done** - Completed with DoD met

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
 

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

@@ -30,7 +30,7 @@
       <output>
         **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
       </output>
       <ask>Choose option [1], provide epic-story number, path to story docs, or [q] to quit:</ask>
@@ -72,7 +72,7 @@
       <check if="no backlog story found">
         <output>📋 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 @@
     <check if="no backlog story found">
       <output>📋 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

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
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
 
 ## Story
 
@@ -36,10 +38,6 @@ so that {{benefit}}.
 
 ## Dev Agent Record
 
-### Context Reference
-
-<!-- Path(s) to story context XML will be added here by context workflow -->
-
 ### Agent Model Used
 
 {{agent_model_name_version}}

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.
         </output>
         <ask>Choose option [1], [2], [3], or [4], or specify story file path:</ask>
 
@@ -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
         </output>
         <ask>What would you like to do? Choose option [1], [2], or [3]:</ask>

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

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`
   </step>
 
@@ -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: Story file created in stories folder
-#   - ready-for-dev: Draft approved and story context created
 #   - 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**: Story file created (e.g., `stories/1-3-plant-naming.md`)
-- **ready-for-dev**: Draft approved + story context created
 - **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

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: Story file created, ready for development
-#   - ready-for-dev: Draft approved, 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

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)
-  <action>Count story statuses: backlog, drafted, ready-for-dev, in-progress, review, done</action>
+  <action>If any story has status `drafted`, treat as `ready-for-dev` (legacy status)</action>
+  <action>Count story statuses: backlog, ready-for-dev, in-progress, review, done</action>
   <action>Count epic statuses: backlog, contexted</action>
   <action>Detect risks:</action>
   - 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
 </step>
 
 <step n="3" goal="Select next action recommendation">
@@ -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}}
   </output>
@@ -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}}
     </output>
@@ -135,7 +136,6 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
   <template-output>next_workflow_id = {{next_workflow_id}}</template-output>
   <template-output>next_story_id = {{next_story_id}}</template-output>
   <template-output>count_backlog = {{count_backlog}}</template-output>
-  <template-output>count_drafted = {{count_drafted}}</template-output>
   <template-output>count_ready = {{count_ready}}</template-output>
   <template-output>count_in_progress = {{count_in_progress}}</template-output>
   <template-output>count_review = {{count_review}}</template-output>