ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/src/bmm-skills/4-implementation/bmad-create-story/workflow.md

23 KiB
Raw Blame History

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

INITIALIZATION

Configuration Loading

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

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)
  • project_context = **/project-context.md (load if exists)
  • deferred_work_file = {implementation_artifacts}/deferred-work.md
  • 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
deferred_work Deferred items from code reviews (optional) {deferred_work_file} FULL_LOAD (optional)

EXECUTION

Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth" Set {{epic_num}}, {{story_num}}, {{story_key}} from user input GOTO step 2a

Check if {{sprint_status}} file exists for auto discover 🚫 No sprint status file found and no story specified 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 Choose option [1], provide epic-story number, path to story docs, or [q] to quit:

<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>
MUST read COMPLETE {sprint_status} file from start to end to preserve order Load the FULL file: {{sprint_status}} Read ALL lines from beginning to end - do not skip any content Parse the development_status section completely 
<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>
Load the FULL file: {{sprint_status}} Read ALL lines from beginning to end - do not skip any content Parse the development_status section completely

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"

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>

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") Set {{story_id}} = "{{epic_num}}.{{story_num}}" Store story_key for later use (e.g., "1-2-user-authentication")

Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern Load {{sprint_status}} and check epic-{{epic_num}} status If epic status is "backlog" → update to "in-progress" If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) If epic status is "in-progress" → no change needed ERROR: Cannot create story in completed epic Epic {{epic_num}} is marked as 'done'. All stories are complete. If you need to add more work, either: 1. Manually change epic status back to 'in-progress' in sprint-status.yaml 2. Create a new epic for additional work HALT - Cannot proceed ERROR: Invalid epic status '{{epic_status}}' Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done Please fix sprint-status.yaml manually or run sprint-planning to regenerate HALT - Cannot proceed Epic {{epic_num}} status updated to in-progress

GOTO step 2a

🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer mistakes!

Read fully and follow ./discover-inputs.md to load all input files Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, {project_context}

From {epics_content}, extract Epic {{epic_num}} complete context: 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 our story ({{epic_num}}-{{story_num}}) details: STORY FOUNDATION: - User story statement (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story - Business context and value - Success criteria Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}} Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md PREVIOUS STORY INTELLIGENCE: - Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established Extract all learnings that could impact current story implementation

Load {deferred_work_file} completely Parse all deferred items. The file uses level-2 headings produced by bmad-code-review: `## Deferred from: code review of story-X.Y (YYYY-MM-DD)` Each heading is followed by bullet items (one per deferred finding). 
  For each bullet item extract:
  - File paths mentioned (e.g., [src/foo.ts:42])
  - Originating review: the heading text above the bullet (e.g., "code review of story-2.3 (2026-03-18)")
  - Description text: the bullet content
  - Category: if the producer included an explicit category, use it; otherwise derive heuristically from keywords in the description:
    - "security" / "auth" / "injection" / "XSS" / "CSRF" → security
    - "bug" / "crash" / "error" / "null" / "undefined" / "NaN" → bug
    - "performance" / "slow" / "N+1" / "cache" → performance
    - "style" / "lint" / "formatting" / "naming" → style
    - otherwise → tech-debt
  - Set `inferred_category = true` when the category was derived heuristically
</action>

<action>From epics content and architecture analysis, build a list of files this story will likely touch:
  - Files explicitly mentioned in story requirements
  - Files in modules/directories related to the story's feature area
  - Files that share dependencies with story components
</action>

<action>Match deferred items against the story's file list:
  - EXACT match: deferred item references a file the story will modify
  - DIRECTORY match: deferred item is in the same directory/module
  - COMPONENT match: deferred item affects a component the story depends on
</action>

<check if="overlapping deferred items found">
  <action>Store {{matched_deferred_items}} for inclusion in the story file</action>
  <action>Set {{matched_count}} = number of items in {{matched_deferred_items}}</action>
  <action>Classify matches by priority:
    - HIGH: security fixes, bugs in files this story will modify
    - MEDIUM: tech-debt in the same module, performance issues in touched code
    - LOW: style issues, minor refactors in adjacent files
  </action>
  <output>📋 Found {{matched_count}} deferred work items relevant to this story from previous code reviews</output>
</check>

<check if="no overlapping deferred items found">
  <action>Set {{matched_deferred_items}} = empty</action>
</check>

Get last 5 commit titles to understand recent work patterns Analyze 1-5 most recent commits for relevance to current story: - Files created/modified - Code patterns and conventions used - Library dependencies added/changed - Architecture decisions implemented - Testing approaches used Extract actionable insights for current story implementation

🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow! **ARCHITECTURE DOCUMENT ANALYSIS:** Systematically analyze architecture content for story-relevant requirements: Load complete {architecture_content} Load architecture index and scan all architecture files **CRITICAL ARCHITECTURE EXTRACTION:** For each architecture section, determine if relevant to this story: - **Technical Stack:** Languages, frameworks, libraries with versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:** Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build processes - **Integration Patterns:** External service integrations, data flows Extract any story-specific requirements that the developer MUST follow Identify any architectural decisions that override previous patterns 🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations! **WEB INTELLIGENCE:** Identify specific technical areas that require latest version knowledge:

From architecture analysis, identify specific libraries, APIs, or frameworks For each critical technology, research latest stable version and key changes: - Latest API documentation and breaking changes - Security vulnerabilities or updates - Performance improvements or deprecations - Best practices for current version EXTERNAL CONTEXT INCLUSION: Include in story any critical latest information the developer needs: - Specific library versions and why chosen - API endpoints with parameters and authentication - Recent security patches or considerations - Performance optimization techniques - Migration considerations if upgrading

📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide!

Initialize from template.md: {default_output_file} story_header

story_requirements

developer_context_section **DEV AGENT GUARDRAILS:** technical_requirements architecture_compliance library_framework_requirements file_structure_requirements testing_requirements

previous_story_intelligence

git_intelligence_summary

In the Dev Notes section, add a subsection: ### Deferred Items to Address

The following items were deferred from previous code reviews and overlap with files/modules this story will touch. Address these during implementation where practical.

{{#each matched_deferred_items}}

  • [{{priority}}] {{description}} [{{file_ref}}] — from {{origin_review}} {{/each}}

    In the Tasks/Subtasks section, add corresponding subtasks for HIGH-priority deferred items: - [ ] [Deferred] {{description}} [{{file_ref}}] (from previous review)

    latest_tech_information

    project_context_reference

    story_completion_status

    Set story Status to: "ready-for-dev" Add completion note: "Ultimate context engine analysis completed - comprehensive developer guide created"

Validate the newly created story file {default_output_file} against `./checklist.md` and apply any required fixes before finalizing Save story document unconditionally Update {{sprint_status}} Load the FULL file and read all development_status entries Find development_status key matching {{story_key}} Verify current status is "backlog" (expected previous state) Update development_status[{{story_key}}] = "ready-for-dev" Update last_updated field to current date Save file, preserving ALL comments and structure including STATUS DEFINITIONS

Report completion 🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!

**Story Details:**
- Story ID: {{story_id}}
- Story Key: {{story_key}}
- File: {{story_file}}
- Status: ready-for-dev

**Next Steps:**
1. Review the comprehensive story in {{story_file}}
2. Run dev agents `dev-story` for optimized implementation
3. Run `code-review` when complete (auto-marks done)
4. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `dev-story` to generate guardrail tests

**The developer now has everything needed for flawless implementation!**