bmad-create-story

# Create Story Workflow **Goal:** Create a comprehensive story file that gives the dev agent everything needed for flawless implementation. **Your Role:** Story context engine that prevents LLM developer mistakes, omissions, or disasters. - Communicate all responses in {communication_language} and generate all documents in {document_output_language} - Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent EVERYTHING needed for flawless implementation - COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, vague implementations, lying about completion, not learning from past work - EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! This is the most important function in the entire development process! - UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different artifacts simultaneously and thoroughly - SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is written - ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents ## Conventions - Bare paths (e.g. `discover-inputs.md`) resolve from the skill root. - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives). - `{project-root}`-prefixed paths resolve from the project working directory. - `{skill-name}` resolves to the skill directory's basename. ## On Activation ### Step 1: Resolve the Workflow Block Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding. ### Step 3: Load Persistent Facts Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim. ### Step 4: Load Config Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: - `project_name`, `user_name` - `communication_language`, `document_output_language` - `user_skill_level` - `planning_artifacts`, `implementation_artifacts` - `date` as system-generated current datetime ### Step 5: Greet the User Greet `{user_name}`, speaking in `{communication_language}`. ### Step 6: Execute Append Steps Execute each entry in `{workflow.activation_steps_append}` in order. Activation is complete. Begin the workflow below. ## Paths - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` - `epics_file` = `{planning_artifacts}/epics.md` - `prd_file` = `{planning_artifacts}/prd.md` - `architecture_file` = `{planning_artifacts}/architecture.md` - `ux_file` = `{planning_artifacts}/*ux*.md` - `story_title` = "" (will be elicited if not derivable) - `default_output_file` = `{implementation_artifacts}/{{story_key}}.md` ## Input Files | Input | Description | Path Pattern(s) | Load Strategy | |-------|-------------|------------------|---------------| | prd | PRD (fallback - epics file should have most content) | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | SELECTIVE_LOAD | | architecture | Architecture (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | SELECTIVE_LOAD | | ux | UX design (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | SELECTIVE_LOAD | | epics | Enhanced epics+stories file with BDD and source hints | whole: `{planning_artifacts}/*epic*.md`, sharded: `{planning_artifacts}/*epic*/*.md` | SELECTIVE_LOAD | ## Execution <workflow> <step n="1" goal="Determine target story"> <check if="{{story_path}} is provided by user or user provided the epic and story number such as 2-4 or 1.6 or epic 1 story 5"> <action>Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth"</action> <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action> <action>GOTO step 2a</action> </check> <action>Check if {{sprint_status}} file exists for auto discover</action> <check if="sprint status file does NOT exist"> <output>🚫 No sprint status file found and no story specified</output> <output> **Required Options:** 1. Run `sprint-planning` to initialize sprint tracking (recommended) 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> <check if="user chooses 'q'"> <action>HALT - No work needed</action> </check> <check if="user chooses '1'"> <output>Run sprint-planning workflow first to create sprint-status.yaml</output> <action>HALT - User needs to run sprint-planning</action> </check> <check if="user provides epic-story number"> <action>Parse user input: extract epic_num, story_num, story_title</action> <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action> <action>GOTO step 2a</action> </check> <check if="user provides story docs path"> <action>Use user-provided path for story documents</action> <action>GOTO step 2a</action> </check> </check> <!-- Auto-discover from sprint status only if no user input --> <check if="no user input provided"> <critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical> <action>Load the FULL file: {{sprint_status}}</action> <action>Read ALL lines from beginning to end - do not skip any content</action> <action>Parse the development_status section completely</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 created, in progress, or done. **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 and run retrospective </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> <!-- Mark epic as in-progress if this is first story --> <action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action> <check if="this is first story in epic {{epic_num}}"> <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action> <action>If epic status is "backlog" → update to "in-progress"</action> <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action> <action>If epic status is "in-progress" → no change needed</action> <check if="epic status is 'done'"> <output>🚫 ERROR: Cannot create story in completed epic</output> <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output> <output>If you need to add more work, either:</output> <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output> <output>2. Create a new epic for additional work</output> <action>HALT - Cannot proceed</action> </check> <check if="epic status is not one of: backlog, contexted, in-progress, done"> <output>🚫 ERROR: Invalid epic status '{{epic_status}}'</output> <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output> <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output> <action>HALT - Cannot proceed</action> </check> <output>📊 Epic {{epic_num}} status updated to in-progress</output> </check> <action>GOTO step 2a</action> </check> <action>Load the FULL file: {{sprint_status}}</action> <action>Read ALL lines from beginning to end - do not skip any content</action> <action>Parse the development_status section completely</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 created, in progress, or done. **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 and run retrospective </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> <!-- Mark epic as in-progress if this is first story --> <action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action> <check if="this is first story in epic {{epic_num}}"> <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action> <action>If epic status is "backlog" → update to "in-progress"</action> <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action> <action>If epic status is "in-progress" → no change needed</action> <check if="epic status is 'done'"> <output>ERROR: Cannot create story in completed epic</output> <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output> <output>If you need to add more work, either:</output> <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output> <output>2. Create a new epic for additional work</output> <action>HALT - Cannot proceed</action> </check> <check if="epic status is not one of: backlog, contexted, in-progress, done"> <output>ERROR: Invalid epic status '{{epic_status}}'</output> <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output> <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output> <action>HALT - Cannot proceed</action> </check> <output>Epic {{epic_num}} status updated to in-progress</output> </check> <action>GOTO step 2a</action> </step> <step n="2" goal="Load and analyze core artifacts"> <critical>🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer mistakes!</critical> <!-- Load all available content through discovery protocol --> <action>Read fully and follow `./discover-inputs.md` to load all input files</action> <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, plus the project-context facts loaded during activation via `persistent_facts`.</note> <!-- Analyze epics file for story foundation --> <action>From {epics_content}, extract Epic {{epic_num}} complete context:</action> **EPIC ANALYSIS:** - Epic objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to original documents <!-- Extract specific story requirements -->