bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

package/bmad/bmm/workflows/4-implementation/create-story/checklist.md

@@ -0,0 +1,240 @@
+# Create Story Quality Validation Checklist
+
+```xml
+<critical>This validation runs in a FRESH CONTEXT by an independent validator agent</critical>
+<critical>The validator audits story quality and offers to improve if issues are found</critical>
+<critical>Load only the story file and necessary source documents - do NOT load workflow instructions</critical>
+
+<validation-checklist>
+
+<expectations>
+**What create-story workflow should have accomplished:**
+
+1. **Previous Story Continuity:** If a previous story exists (status: done/review/in-progress), current story should have "Learnings from Previous Story" subsection in Dev Notes that references: new files created, completion notes, architectural decisions, unresolved review items
+2. **Source Document Coverage:** Story should cite tech spec (if exists), epics, PRD, and relevant architecture docs (architecture.md, testing-strategy.md, coding-standards.md, unified-project-structure.md)
+3. **Requirements Traceability:** ACs sourced from tech spec (preferred) or epics, not invented
+4. **Dev Notes Quality:** Specific guidance with citations, not generic advice
+5. **Task-AC Mapping:** Every AC has tasks, every task references AC, testing subtasks present
+6. **Structure:** Status="drafted", proper story statement, Dev Agent Record sections initialized
+</expectations>
+
+## Validation Steps
+
+### 1. Load Story and Extract Metadata
+- [ ] Load story file: {{story_file_path}}
+- [ ] Parse sections: Status, Story, ACs, Tasks, Dev Notes, Dev Agent Record, Change Log
+- [ ] Extract: epic_num, story_num, story_key, story_title
+- [ ] Initialize issue tracker (Critical/Major/Minor)
+
+### 2. Previous Story Continuity Check
+
+**Find previous story:**
+- [ ] Load {output_folder}/sprint-status.yaml
+- [ ] Find current {{story_key}} in development_status
+- [ ] Identify story entry immediately above (previous story)
+- [ ] Check previous story status
+
+**If previous story status is done/review/in-progress:**
+- [ ] Load previous story file: {story_dir}/{{previous_story_key}}.md
+- [ ] Extract: Dev Agent Record (Completion Notes, File List with NEW/MODIFIED)
+- [ ] Extract: Senior Developer Review section if present
+- [ ] Count unchecked [ ] items in Review Action Items
+- [ ] Count unchecked [ ] items in Review Follow-ups (AI)
+
+**Validate current story captured continuity:**
+- [ ] Check: "Learnings from Previous Story" subsection exists in Dev Notes
+  - If MISSING and previous story has content → **CRITICAL ISSUE**
+- [ ] If subsection exists, verify it includes:
+  - [ ] References to NEW files from previous story → If missing → **MAJOR ISSUE**
+  - [ ] Mentions completion notes/warnings → If missing → **MAJOR ISSUE**
+  - [ ] Calls out unresolved review items (if any exist) → If missing → **CRITICAL ISSUE**
+  - [ ] Cites previous story: [Source: stories/{{previous_story_key}}.md]
+
+**If previous story status is backlog/drafted:**
+- [ ] No continuity expected (note this)
+
+**If no previous story exists:**
+- [ ] First story in epic, no continuity expected
+
+### 3. Source Document Coverage Check
+
+**Build available docs list:**
+- [ ] Check exists: tech-spec-epic-{{epic_num}}*.md in {tech_spec_search_dir}
+- [ ] Check exists: {output_folder}/epics.md
+- [ ] Check exists: {output_folder}/PRD.md
+- [ ] Check exists in {output_folder}/ or {project-root}/docs/:
+  - architecture.md, testing-strategy.md, coding-standards.md
+  - unified-project-structure.md, tech-stack.md
+  - backend-architecture.md, frontend-architecture.md, data-models.md
+
+**Validate story references available docs:**
+- [ ] Extract all [Source: ...] citations from story Dev Notes
+- [ ] Tech spec exists but not cited → **CRITICAL ISSUE**
+- [ ] Epics exists but not cited → **CRITICAL ISSUE**
+- [ ] Architecture.md exists → Read for relevance → If relevant but not cited → **MAJOR ISSUE**
+- [ ] Testing-strategy.md exists → Check Dev Notes mentions testing standards → If not → **MAJOR ISSUE**
+- [ ] Testing-strategy.md exists → Check Tasks have testing subtasks → If not → **MAJOR ISSUE**
+- [ ] Coding-standards.md exists → Check Dev Notes references standards → If not → **MAJOR ISSUE**
+- [ ] Unified-project-structure.md exists → Check Dev Notes has "Project Structure Notes" subsection → If not → **MAJOR ISSUE**
+
+**Validate citation quality:**
+- [ ] Verify cited file paths are correct and files exist → Bad citations → **MAJOR ISSUE**
+- [ ] Check citations include section names, not just file paths → Vague citations → **MINOR ISSUE**
+
+### 4. Acceptance Criteria Quality Check
+
+- [ ] Extract Acceptance Criteria from story
+- [ ] Count ACs: {{ac_count}} (if 0 → **CRITICAL ISSUE** and halt)
+- [ ] Check story indicates AC source (tech spec, epics, PRD)
+
+**If tech spec exists:**
+- [ ] Load tech spec
+- [ ] Search for this story number
+- [ ] Extract tech spec ACs for this story
+- [ ] Compare story ACs vs tech spec ACs → If mismatch → **MAJOR ISSUE**
+
+**If no tech spec but epics.md exists:**
+- [ ] Load epics.md
+- [ ] Search for Epic {{epic_num}}, Story {{story_num}}
+- [ ] Story not found in epics → **CRITICAL ISSUE** (should have halted)
+- [ ] Extract epics ACs
+- [ ] Compare story ACs vs epics ACs → If mismatch without justification → **MAJOR ISSUE**
+
+**Validate AC quality:**
+- [ ] Each AC is testable (measurable outcome)
+- [ ] Each AC is specific (not vague)
+- [ ] Each AC is atomic (single concern)
+- [ ] Vague ACs found → **MINOR ISSUE**
+
+### 5. Task-AC Mapping Check
+
+- [ ] Extract Tasks/Subtasks from story
+- [ ] For each AC: Search tasks for "(AC: #{{ac_num}})" reference
+  - [ ] AC has no tasks → **MAJOR ISSUE**
+- [ ] For each task: Check if references an AC number
+  - [ ] Tasks without AC refs (and not testing/setup) → **MINOR ISSUE**
+- [ ] Count tasks with testing subtasks
+  - [ ] Testing subtasks < ac_count → **MAJOR ISSUE**
+
+### 6. Dev Notes Quality Check
+
+**Check required subsections exist:**
+- [ ] Architecture patterns and constraints
+- [ ] References (with citations)
+- [ ] Project Structure Notes (if unified-project-structure.md exists)
+- [ ] Learnings from Previous Story (if previous story has content)
+- [ ] Missing required subsections → **MAJOR ISSUE**
+
+**Validate content quality:**
+- [ ] Architecture guidance is specific (not generic "follow architecture docs") → If generic → **MAJOR ISSUE**
+- [ ] Count citations in References subsection
+  - [ ] No citations → **MAJOR ISSUE**
+  - [ ] < 3 citations and multiple arch docs exist → **MINOR ISSUE**
+- [ ] Scan for suspicious specifics without citations:
+  - API endpoints, schema details, business rules, tech choices
+  - [ ] Likely invented details found → **MAJOR ISSUE**
+
+### 7. Story Structure Check
+
+- [ ] Status = "drafted" → If not → **MAJOR ISSUE**
+- [ ] Story section has "As a / I want / so that" format → If malformed → **MAJOR ISSUE**
+- [ ] Dev Agent Record has required sections:
+  - Context Reference, Agent Model Used, Debug Log References, Completion Notes List, File List
+  - [ ] Missing sections → **MAJOR ISSUE**
+- [ ] Change Log initialized → If missing → **MINOR ISSUE**
+- [ ] File in correct location: {story_dir}/{{story_key}}.md → If not → **MAJOR ISSUE**
+
+### 8. Unresolved Review Items Alert
+
+**CRITICAL CHECK for incomplete review items from previous story:**
+
+- [ ] If previous story has "Senior Developer Review (AI)" section:
+  - [ ] Count unchecked [ ] items in "Action Items"
+  - [ ] Count unchecked [ ] items in "Review Follow-ups (AI)"
+  - [ ] If unchecked items > 0:
+    - [ ] Check current story "Learnings from Previous Story" mentions these
+    - [ ] If NOT mentioned → **CRITICAL ISSUE** with details:
+      - List all unchecked items with severity
+      - Note: "These may represent epic-wide concerns"
+      - Required: Add to Learnings section with note about pending items
+
+## Validation Report Generation
+
+**Calculate severity counts:**
+- Critical: {{critical_count}}
+- Major: {{major_count}}
+- Minor: {{minor_count}}
+
+**Determine outcome:**
+- Critical > 0 OR Major > 3 → **FAIL**
+- Major ≤ 3 and Critical = 0 → **PASS with issues**
+- All = 0 → **PASS**
+
+**Generate report:**
+```
+
+# Story Quality Validation Report
+
+Story: {{story_key}} - {{story_title}}
+Outcome: {{outcome}} (Critical: {{critical_count}}, Major: {{major_count}}, Minor: {{minor_count}})
+
+## Critical Issues (Blockers)
+
+{{list_each_with_description_and_evidence}}
+
+## Major Issues (Should Fix)
+
+{{list_each_with_description_and_evidence}}
+
+## Minor Issues (Nice to Have)
+
+{{list_each_with_description}}
+
+## Successes
+
+{{list_what_was_done_well}}
+
+```
+
+## User Alert and Remediation
+
+**If FAIL:**
+- Show issues summary and top 3 issues
+- Offer options: (1) Auto-improve story, (2) Show detailed findings, (3) Fix manually, (4) Accept as-is
+- If option 1: Re-load source docs, regenerate affected sections, re-run validation
+
+**If PASS with issues:**
+- Show issues list
+- Ask: "Improve story? (y/n)"
+- If yes: Enhance story with missing items
+
+**If PASS:**
+- Confirm: All quality standards met
+- List successes
+- Ready for story-context generation
+
+</validation-checklist>
+```
+
+## Quick Reference
+
+**Validation runs in fresh context and checks:**
+
+1. ✅ Previous story continuity captured (files, notes, **unresolved review items**)
+2. ✅ All relevant source docs discovered and cited
+3. ✅ ACs match tech spec/epics exactly
+4. ✅ Tasks cover all ACs with testing
+5. ✅ Dev Notes have specific guidance with citations (not generic)
+6. ✅ Structure and metadata complete
+
+**Severity Levels:**
+
+- **CRITICAL** = Missing previous story reference, missing tech spec cite, unresolved review items not called out, story not in epics
+- **MAJOR** = Missing arch docs, missing files from previous story, vague Dev Notes, ACs don't match source, no testing subtasks
+- **MINOR** = Vague citations, orphan tasks, missing Change Log
+
+**Outcome Triggers:**
+
+- **FAIL** = Any critical OR >3 major issues
+- **PASS with issues** = ≤3 major issues, no critical
+- **PASS** = All checks passed

package/bmad/bmm/workflows/4-implementation/create-story/instructions.md

@@ -0,0 +1,283 @@
+# Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
+
+````xml
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Generate all documents in {document_output_language}</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>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
+
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (prd, architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
+
+<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, architecture_file</action>
+  </step>
+
+  <step n="2" goal="Discover and load source documents">
+    <critical>PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development</critical>
+
+    <action>Find the previous completed story to extract dev agent learnings and review findings:
+      1. Load {{output_folder}}/sprint-status.yaml COMPLETELY
+      2. Find current {{story_key}} in development_status section
+      3. Identify the story entry IMMEDIATELY ABOVE current story (previous row in file order)
+      4. If previous story exists:
+         - Extract {{previous_story_key}}
+         - Check previous story status (done, in-progress, review, etc.)
+         - If status is "done", "review", or "in-progress" (has some completion):
+           * Construct path: {{story_dir}}/{{previous_story_key}}.md
+           * Load the COMPLETE previous story file
+           * Parse ALL sections comprehensively:
+
+             A) Dev Agent Record → Completion Notes List:
+                - New patterns/services created (to reuse, not recreate)
+                - Architectural deviations or decisions made
+                - Technical debt deferred to future stories
+                - Warnings or recommendations for next story
+                - Interfaces/methods created for reuse
+
+             B) Dev Agent Record → Debug Log References:
+                - Issues encountered and solutions
+                - Gotchas or unexpected challenges
+                - Workarounds applied
+
+             C) Dev Agent Record → File List:
+                - Files created (NEW) - understand new capabilities
+                - Files modified (MODIFIED) - track evolving components
+                - Files deleted (DELETED) - removed functionality
+
+             D) Dev Notes:
+                - Any "future story" notes or TODOs
+                - Patterns established
+                - Constraints discovered
+
+             E) Senior Developer Review (AI) section (if present):
+                - Review outcome (Approve/Changes Requested/Blocked)
+                - Unresolved action items (unchecked [ ] items)
+                - Key findings that might affect this story
+                - Architectural concerns raised
+
+             F) Senior Developer Review → Action Items (if present):
+                - Check for unchecked [ ] items still pending
+                - Note any systemic issues that apply to multiple stories
+
+             G) Review Follow-ups (AI) tasks (if present):
+                - Check for unchecked [ ] review tasks still pending
+                - Determine if they're epic-wide concerns
+
+             H) Story Status:
+                - If "review" or "in-progress" - incomplete, note what's pending
+                - If "done" - confirmed complete
+           * Store ALL findings as {{previous_story_learnings}} with structure:
+             - new_files: [list]
+             - modified_files: [list]
+             - new_services: [list with descriptions]
+             - architectural_decisions: [list]
+             - technical_debt: [list]
+             - warnings_for_next: [list]
+             - review_findings: [list if review exists]
+             - pending_items: [list of unchecked action items]
+         - If status is "backlog" or "drafted":
+           * Set {{previous_story_learnings}} = "Previous story not yet implemented"
+      5. If no previous story exists (first story in epic):
+         - Set {{previous_story_learnings}} = "First story in epic - no predecessor context"
+    </action>
+
+    <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) architecture_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="Find next backlog story to draft" tag="sprint-status">
+    <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely to understand story order</action>
+
+    <action>Find the FIRST story (by reading in order from top to bottom) where:
+      - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+      - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+      - Status value equals "backlog"
+    </action>
+
+    <check if="no backlog story found">
+      <output>📋 No backlog stories found in sprint-status.yaml
+
+All stories are either already drafted or completed.
+
+**Options:**
+1. Run sprint-planning to refresh story tracking
+2. Load PM agent and run correct-course to add more stories
+3. Check if current sprint is complete
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Extract from found story key (e.g., "1-2-user-authentication"):
+      - epic_num: first number before dash (e.g., "1")
+      - story_num: second number after first dash (e.g., "2")
+      - story_title: remainder after second dash (e.g., "user-authentication")
+    </action>
+    <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
+    <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
+
+    <action>Verify story is enumerated in {{epics_file}}. If not found, HALT with message:</action>
+    <action>"Story {{story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story."</action>
+
+    <action>Check if story file already exists at expected path in {{story_dir}}</action>
+    <check if="story file exists">
+      <output>ℹ️ Story file already exists: {{story_file_path}}
+
+Will update existing story file rather than creating new one.
+      </output>
+      <action>Set update_mode = true</action>
+    </check>
+  </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 architecture 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>Review {{previous_story_learnings}} and extract actionable intelligence:
+      - New patterns/services created → Note for reuse (DO NOT recreate)
+      - Architectural deviations → Understand and maintain consistency
+      - Technical debt items → Assess if this story should address them
+      - Files modified → Understand current state of evolving components
+      - Warnings/recommendations → Apply to this story's approach
+      - Review findings → Learn from issues found in previous story
+      - Pending action items → Determine if epic-wide concerns affect this story
+    </action>
+
+    <action>If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts.</action>
+
+    <action>Cross-reference {{previous_story_learnings}}.new_files with project structure to understand where new capabilities are located.</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>
+
+    <action>If {{previous_story_learnings}} contains actionable items (not "First story" or "not yet implemented"):
+      - Add "Learnings from Previous Story" subsection to Dev Notes
+      - Include relevant completion notes, new files/patterns, deviations
+      - Cite previous story file as reference [Source: stories/{{previous_story_key}}.md]
+      - Highlight interfaces/services to REUSE (not recreate)
+      - Note any technical debt to address in this story
+      - List pending review items that affect this story (if any)
+      - Reference specific files created: "Use {{file_path}} for {{purpose}}"
+      - Format example:
+        ```
+        ### Learnings from Previous Story
+
+        **From Story {{previous_story_key}} (Status: {{previous_status}})**
+
+        - **New Service Created**: `AuthService` base class available at `src/services/AuthService.js` - use `AuthService.register()` method
+        - **Architectural Change**: Switched from session-based to JWT authentication
+        - **Schema Changes**: User model now includes `passwordHash` field, migration applied
+        - **Technical Debt**: Email verification skipped, should be included in this or subsequent story
+        - **Testing Setup**: Auth test suite initialized at `tests/integration/auth.test.js` - follow patterns established there
+        - **Pending Review Items**: Rate limiting mentioned in review - consider for this story
+
+        [Source: stories/{{previous_story_key}}.md#Dev-Agent-Record]
+        ```
+    </action>
+
+    <template-output file="{default_output_file}">change_log</template-output>
+  </step>
+
+  <step n="8" goal="Validate, save, and mark story drafted" tag="sprint-status">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
+
+    <!-- Mark story as drafted in sprint status -->
+    <action>Update {{output_folder}}/sprint-status.yaml</action>
+    <action>Load the FULL file and read all development_status entries</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "drafted"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Could not update story status: {{story_key}} not found in sprint-status.yaml
+
+Story file was created successfully, but sprint-status.yaml was not updated.
+You may need to run sprint-planning to refresh tracking, or manually set the story row status to `drafted`.
+      </output>
+    </check>
+
+    <action>Report created/updated story path</action>
+    <output>**✅ Story Created Successfully, {user_name}!**
+
+**Story Details:**
+
+- Story ID: {{story_id}}
+- Story Key: {{story_key}}
+- File: {{story_file}}
+- Status: drafted (was backlog)
+
+**⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command.
+
+**Next Steps:**
+
+1. Review the drafted story in {{story_file}}
+2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step)
+3. Or run `story-ready` to manually mark the story ready without generating technical context
+    </output>
+  </step>
+
+</workflow>
+````

package/bmad/bmm/workflows/4-implementation/create-story/template.md

@@ -0,0 +1,51 @@
+# Story {{epic_num}}.{{story_num}}: {{story_title}}
+
+Status: drafted
+
+## 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]
+
+## 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}}
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

package/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -0,0 +1,74 @@
+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/4-implementation/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
+  architecture_file: "{output_folder}/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: |
+    - architecture.md
+    - infrastructure-architecture.md
+  story_title: "" # Will be elicited if not derivable
+  epic_num: 1
+  story_num: 1
+  non_interactive: true # Generate without elicitation; avoid interactive prompts
+
+# Output configuration
+# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
+default_output_file: "{story_dir}/{{story_key}}.md"
+
+recommended_inputs:
+  - epics: "Epic breakdown (epics.md)"
+  - prd: "PRD document"
+  - architecture: "Architecture (optional)"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  tech_spec:
+    whole: "{output_folder}/tech-spec.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+standalone: true