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

<workflow>
  <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>Communicate all responses in {communication_language} and generate all documents in {document_output_language}</critical>

  <critical>🔥 CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or
    disasters! 🔥</critical>
  <critical>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</critical>
  <critical>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</critical>
  <critical>🚨 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!</critical>
  <critical>🔬 UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly
    analyze different artifacts simultaneously and thoroughly</critical>
  <critical>❓ SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is
    written</critical>
  <critical>🎯 ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents</critical>

  <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 fuckups!</critical>

    <!-- Load all available content through discovery protocol -->
    <invoke-protocol
      name="discover_inputs" />
    <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content},
    {project_context}</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 -->
    <action>Extract our story ({{epic_num}}-{{story_num}}) details:</action> **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 <!-- Previous story analysis for context continuity -->
    <check if="story_num > 1">
      <action>Load previous story file: {{story_dir}}/{{epic_num}}-{{previous_story_num}}-*.md</action> **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 <action>Extract
    all learnings that could impact current story implementation</action>
    </check>

    <!-- Git intelligence for previous work patterns -->
    <check
      if="previous story exists AND git repository detected">
      <action>Get last 5 commit titles to understand recent work patterns</action>
      <action>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
      </action>
      <action>Extract actionable insights for current story implementation</action>
    </check>
  </step>

  <step n="3" goal="Architecture analysis for developer guardrails">
    <critical>🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow!</critical> **ARCHITECTURE DOCUMENT ANALYSIS:** <action>Systematically
    analyze architecture content for story-relevant requirements:</action>

    <!-- Load architecture - single file or sharded -->
    <check if="architecture file is single file">
      <action>Load complete {architecture_content}</action>
    </check>
    <check if="architecture is sharded to folder">
      <action>Load architecture index and scan all architecture files</action>
    </check> **CRITICAL ARCHITECTURE EXTRACTION:** <action>For
    each architecture section, determine if relevant to this story:</action> - **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 <action>Extract any story-specific requirements that the
    developer MUST follow</action>
    <action>Identify any architectural decisions that override previous patterns</action>
  </step>

  <step n="4" goal="Web research for latest technical specifics">
    <critical>🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations!</critical> **WEB INTELLIGENCE:** <action>Identify specific
    technical areas that require latest version knowledge:</action>

    <!-- Check for libraries/frameworks mentioned in architecture -->
    <action>From architecture analysis, identify specific libraries, APIs, or
    frameworks</action>
    <action>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
    </action>
    **EXTERNAL CONTEXT INCLUSION:** <action>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
    </action>
  </step>

  <step n="5" goal="Create comprehensive story file">
    <critical>📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide!</critical>

    <action>Initialize from template.md:
    {default_output_file}</action>
    <template-output file="{default_output_file}">story_header</template-output>

    <!-- Story foundation from epics analysis -->
    <template-output
      file="{default_output_file}">story_requirements</template-output>

    <!-- Developer context section - MOST IMPORTANT PART -->
    <template-output file="{default_output_file}">
    developer_context_section</template-output> **DEV AGENT GUARDRAILS:** <template-output file="{default_output_file}">
    technical_requirements</template-output>
    <template-output file="{default_output_file}">architecture_compliance</template-output>
    <template-output
      file="{default_output_file}">library_framework_requirements</template-output>
    <template-output file="{default_output_file}">
    file_structure_requirements</template-output>
    <template-output file="{default_output_file}">testing_requirements</template-output>

    <!-- Previous story intelligence -->
    <check
      if="previous story learnings available">
      <template-output file="{default_output_file}">previous_story_intelligence</template-output>
    </check>

    <!-- Git intelligence -->
    <check
      if="git analysis completed">
      <template-output file="{default_output_file}">git_intelligence_summary</template-output>
    </check>

    <!-- Latest technical specifics -->
    <check if="web research completed">
      <template-output file="{default_output_file}">latest_tech_information</template-output>
    </check>

    <!-- Project context reference -->
    <template-output
      file="{default_output_file}">project_context_reference</template-output>

    <!-- Final status update -->
    <template-output file="{default_output_file}">
    story_completion_status</template-output>

    <!-- CRITICAL: Set status to ready-for-dev -->
    <action>Set story Status to: "ready-for-dev"</action>
    <action>Add completion note: "Ultimate
    context engine analysis completed - comprehensive developer guide created"</action>
  </step>

  <step n="6" goal="Update sprint status and finalize">
    <invoke-task>Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml</invoke-task>
    <action>Save story document unconditionally</action>

    <!-- Update sprint status -->
    <check if="sprint status file exists">
      <action>Update {{sprint_status}}</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}}] = "ready-for-dev"</action>
      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
    </check>

    <action>Report completion</action>
    <output>**🎯 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)

      **The developer now has everything needed for flawless implementation!**
    </output>
  </step>

  <step n="7" goal="Create tracking item in external system">
    <critical>Create issue/work item in the configured tracking system after story file is created</critical>

    <!-- Check if tracking system is configured -->
    <check if="sprint status file exists">
      <action>Load {{sprint_status}} and extract tracking_system configuration</action>
      <action>Set {{tracking_system}} from sprint-status.yaml (default: github-issues)</action>
      <action>Extract milestone or iteration name if configured</action>
      <action>Extract epic parent reference (epic_issue_{{epic_num}} or epic_work_item_{{epic_num}})</action>
    </check>
    <check if="sprint status file does NOT exist OR tracking_system not configured">
      <action>Set {{tracking_system}} = "none"</action>
      <output>ℹ️ No tracking system configured - skipping external issue creation</output>
      <action>GOTO workflow end</action>
    </check>

    <!-- GitHub Issues Provider -->
    <check if="{{tracking_system}} == 'github-issues'">
      <action>Extract repo from sprint-status.yaml (format: owner/repo)</action>
      <action>Extract milestone name from sprint-status.yaml (if configured)</action>
      <action>Read story file content for issue body</action>
      
      <!-- Create issue with milestone if available -->
      <check if="milestone is configured">
        <action>Run: gh issue create --title "{{story_key}}: {{story_title}}" --body "$(cat {{story_file}})" --label "story,sprint" --milestone "{{milestone}}"</action>
      </check>
      <check if="milestone is NOT configured">
        <action>Run: gh issue create --title "{{story_key}}: {{story_title}}" --body "$(cat {{story_file}})" --label "story,sprint"</action>
      </check>
      
      <action>Capture issue number from command output</action>
      <action>Update sprint-status.yaml with tracking_ref: {{issue_number}} for this story key</action>
      
      <!-- Link to parent epic issue if available -->
      <check if="epic_issue_{{epic_num}} exists in sprint-status.yaml">
        <action>Add comment linking to parent epic: gh issue comment {{issue_number}} --body "Part of Epic #{{epic_issue_number}}"</action>
      </check>
      
      <output>✅ GitHub Issue created: #{{issue_number}} (linked to milestone: {{milestone}})</output>
    </check>

    <!-- Azure DevOps Provider -->
    <check if="{{tracking_system}} == 'azure-devops'">
      <action>Extract org_url and project from sprint-status.yaml</action>
      <action>Extract iteration path from sprint-status.yaml (if configured)</action>
      <action>Prepare description from story file (truncate if needed for Azure DevOps limits)</action>
      
      <!-- Create work item with iteration if available -->
      <check if="iteration is configured">
        <action>Run: az boards work-item create --title "{{story_key}}: {{story_title}}" --type "User Story" --description "{{story_description}}" --iteration "{{iteration_path}}" --org {{org_url}} --project {{project}}</action>
      </check>
      <check if="iteration is NOT configured">
        <action>Run: az boards work-item create --title "{{story_key}}: {{story_title}}" --type "User Story" --description "{{story_description}}" --org {{org_url}} --project {{project}}</action>
      </check>
      
      <action>Capture work_item_id from command output</action>
      <action>Update sprint-status.yaml with tracking_ref: {{work_item_id}} for this story key</action>
      
      <!-- Link to parent epic work item if available -->
      <check if="epic_work_item_{{epic_num}} exists in sprint-status.yaml">
        <action>Run: az boards work-item relation add --id {{work_item_id}} --relation-type "System.LinkTypes.Hierarchy-Reverse" --target-id {{epic_work_item_id}} --org {{org_url}}</action>
        <output>✅ Linked to parent Epic #{{epic_work_item_id}}</output>
      </check>
      
      <output>✅ Azure DevOps Work Item created: #{{work_item_id}} (in iteration: {{iteration}})</output>
    </check>

    <!-- Unknown provider -->
    <check if="{{tracking_system}} != 'github-issues' AND {{tracking_system}} != 'azure-devops' AND {{tracking_system}} != 'none'">
      <output>⚠️ Unknown tracking system: {{tracking_system}} - skipping external issue creation</output>
    </check>
  </step>

</workflow>