BMAD-METHOD/src/modules/bmm/workflows/4-implementation/autonomous-epic/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}</critical>
  <critical>🤖 AUTONOMOUS EPIC PROCESSING - Full automation of epic completion!</critical>
  <critical>This workflow orchestrates super-dev-pipeline for each story in an epic</critical>
  <critical>TASK-BASED COMPLETION: A story is ONLY complete when it has ZERO unchecked tasks (- [ ])</critical>

  <!-- AUTONOMOUS MODE INSTRUCTIONS - READ THESE CAREFULLY -->
  <critical>⚡ AUTONOMOUS MODE: When auto_accept_gap_analysis=true in workflow.yaml, you MUST:
    - NEVER ask the user to approve gap analysis refinements
    - AUTOMATICALLY accept all gap analysis proposals
    - PROCEED immediately without waiting for user input on gap analysis
    - Only ask for user input at the START of the workflow (epic selection, Y/D/n choice)
  </critical>
  <critical>⚡ INVOKING SUB-WORKFLOWS: When you see invoke-workflow, you must:
    1. Load the referenced workflow.yaml file
    2. Load its instructions.xml file
    3. Execute that workflow completely
    4. Return to this workflow and continue
  </critical>

  <step n="1" goal="Initialize and validate epic">
    <check if="{{validation_only}} == true">
      <output>🔍 **Epic Status Validation Mode**

This will:
1. Scan ALL story files for task completion (count checkboxes)
2. Validate story file quality (>=10KB, proper task lists)
3. Update sprint-status.yaml to match REALITY (task completion)
4. Report suspicious stories (poor quality, false positives)

**NO code will be generated** - validation only.
      </output>
    </check>

    <check if="{{validation_only}} != true">
      <output>🤖 **Autonomous Epic Processing**

This workflow will automatically:
1. Develop each story using super-dev-pipeline
2. **Verify completion** by checking ALL tasks are done (- [x])
3. Commit and push after each story (integrated in super-dev-pipeline)
4. Generate epic completion report

**super-dev-pipeline includes:**
- Pre-gap analysis (understand existing code)
- Smart task batching (group related work)
- Implementation (systematic execution)
- **Post-implementation validation** (catches false positives!)
- Code review (adversarial, multi-agent)
- Completion (commit + push)

**Key Improvement:** Stories in "review" status with unchecked tasks
WILL be processed - we check actual task completion, not just status!
      </output>
    </check>

    <check if="{{epic_num}} provided">
      <action>Use provided epic number</action>
      <goto anchor="validate_epic" />
    </check>

    <ask>Enter epic number to process (e.g., "2" or "epic-3"), or [q] to quit:</ask>

    <check if="user provides epic number">
      <action>Parse epic number from input</action>
      <goto anchor="validate_epic" />
    </check>

    <check if="user says q">
      <output>👋 Autonomous epic processing cancelled.</output>
      <action>HALT</action>
    </check>

    <anchor id="validate_epic" />

    <action>Load {{sprint_status}} file</action>
    <action>Find epic-{{epic_num}} entry and all story entries for this epic</action>

    <!-- TASK-BASED ANALYSIS: Scan actual story files for unchecked tasks -->
    <action>For each story in epic:
      1. Read the story file from {{story_dir}}/{{story_key}}.md
      2. Check file exists (if missing, mark story as "backlog")
      3. Check file size (if <10KB, flag as poor quality)
      4. Count unchecked tasks: grep -c "^- \[ \]" or regex match "- \[ \]"
      5. Count checked tasks: grep -c "^- \[x\]" or regex match "- \[x\]"
      6. Count total tasks (unchecked + checked)
      7. Calculate completion rate: (checked / total * 100)
      8. Categorize story:
         - "truly_done": unchecked_tasks=0 AND file_size>=10KB AND total_tasks>=5
         - "in_progress": unchecked_tasks>0 AND checked_tasks>0
         - "ready_for_dev": unchecked_tasks=total_tasks (nothing checked yet)
         - "poor_quality": file_size<10KB OR total_tasks<5 (needs regeneration)
         - "needs_work": unchecked_tasks > 0 (regardless of status)
         - "backlog": status=backlog (file may not exist yet)
    </action>

    <output>
      📊 **Epic {{epic_num}} Status (Task-Based Analysis)**

      Total stories: {{total_story_count}}

      **By Actual Task Completion:**
      - ✅ Truly Done: {{truly_done_count}} (all tasks checked, will skip)
      - 🔧 Needs Work: {{needs_work_count}} (has unchecked tasks)
        {{list_needs_work_with_task_counts}}
      - 📝 Backlog: {{backlog_count}} (will create + develop)

      **By Status (for reference):**
      - done: {{done_status_count}}
      - review: {{review_status_count}}
      - in-progress: {{inprogress_status_count}}
      - ready-for-dev: {{ready_status_count}}
      - backlog: {{backlog_status_count}}

      **Work Remaining:** {{work_count}} stories with {{total_unchecked_tasks}} unchecked tasks
      **Estimated Time:** {{estimated_hours}} hours
      **Estimated Tokens:** ~{{estimated_tokens}}K
    </output>

    <ask>**Proceed with autonomous processing?**

      [Y] Yes - Use super-dev-pipeline (step-file architecture, brownfield-compatible)
      [n] No - Cancel

      Note: super-dev-pipeline uses disciplined step-file execution with smart batching!
    </ask>

    <check if="user says Y">
      <action>Set {{use_super_dev_pipeline}} = true</action>
    </check>

    <check if="user says n">
      <output>❌ Cancelled</output>
      <action>HALT</action>
    </check>
  </step>

  <step n="2" goal="Initialize tracking (optionally create branch)">
    <action>Get current branch name and store as {{current_branch}}</action>

    <check if="{{create_epic_branch}} == true">
      <action>Create new branch: auto-epic-{{epic_num}}</action>
      <output>📝 Created branch: auto-epic-{{epic_num}}</output>
    </check>

    <check if="{{create_epic_branch}} == false">
      <output>📝 Staying on current branch: {{current_branch}} (parallel epic mode)</output>
    </check>

    <!-- Backwards compatibility: Check for both new and legacy progress file formats -->
    <action>Check for existing progress file:
      1. New format: .autonomous-epic-{{epic_num}}-progress.yaml
      2. Legacy format: .autonomous-epic-progress-epic-{{epic_num}}.yaml
      Set {{progress_file_path}} to whichever exists, or new format if neither exist
    </action>

    <check if="progress file exists">
      <output>📋 Found existing progress file: {{progress_file_path}}</output>
      <output>⚠️  Resuming from last saved state</output>
      <action>Load existing progress from {{progress_file_path}}</action>
    </check>

    <check if="progress file does NOT exist">
      <output>📋 Creating new progress file: .autonomous-epic-{{epic_num}}-progress.yaml</output>
      <action>Initialize progress tracking file at: .autonomous-epic-{{epic_num}}-progress.yaml
        - epic_num
        - started timestamp
        - total_stories
        - completed_stories: []
        - current_story: null
        - status: running
      </action>
    </check>
  </step>

  <step n="3" goal="Process all stories in epic">
    <critical>🔄 STORY LOOP - Create and develop each story until ALL tasks complete</critical>

    <action>Build ordered list of stories needing work:
      1. All stories with unchecked tasks (regardless of status)
      2. All backlog stories
      3. Sort by story number (ascending)
    </action>
    <action>Initialize counters: success=0, failure=0</action>

    <!-- STORY LOOP -->
    <loop foreach="{{stories_needing_work}}">
      <action>Set {{current_story}}</action>
      <action>Read story file from {{story_dir}}/{{current_story.key}}.md</action>

      <check if="file not found">
        <output>  ❌ Story file missing: {{current_story.key}}.md</output>
        <action>Mark story as "backlog" in sprint-status.yaml</action>
        <action>Continue to next story</action>
      </check>

      <action>Get file size in KB</action>
      <action>Count unchecked tasks: grep -c "^- \[ \]"</action>
      <action>Count checked tasks: grep -c "^- \[x\]"</action>
      <action>Count total tasks</action>
      <action>Calculate completion_rate = (checked / total * 100)</action>

      <output>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Story {{counter}}/{{work_count}}: {{current_story.key}}
Size: {{file_size_kb}}KB | Tasks: {{checked}}/{{total}} ({{completion_rate}}%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      </output>

      <!-- VALIDATION-ONLY MODE: Just update status, don't implement -->
      <check if="{{validation_only}} == true">
        <action>Determine correct status:
          IF unchecked_tasks == 0 AND file_size >= 10KB AND total_tasks >= 5
            → correct_status = "done"
          ELSE IF unchecked_tasks > 0 AND checked_tasks > 0
            → correct_status = "in-progress"
          ELSE IF unchecked_tasks == total_tasks
            → correct_status = "ready-for-dev"
          ELSE IF file_size < 10KB OR total_tasks < 5
            → correct_status = "ready-for-dev" (needs regeneration)
        </action>

        <action>Update story status in sprint-status.yaml to {{correct_status}}</action>

        <check if="file_size < 10KB OR total_tasks < 5">
          <output>  ⚠️  POOR QUALITY - File too small or missing tasks (needs /create-story regeneration)</output>
        </check>

        <action>Continue to next story (skip super-dev-pipeline)</action>
      </check>

      <!-- NORMAL MODE: Run super-dev-pipeline -->
      <check if="{{validation_only}} != true">
        <!-- PROCESS STORY WITH SUPER-DEV-PIPELINE -->
        <check if="{{unchecked_count}} > 0 OR status == 'backlog'">
          <output>💻 Processing story with super-dev-pipeline ({{unchecked_count}} tasks remaining)...</output>

        <try>
          <invoke-workflow path="{project-root}/_bmad/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml">
            <input name="story_file" value="{{story_dir}}/{{current_story.key}}.md" />
            <input name="mode" value="batch" />
            <note>Full lifecycle: pre-gap → implement (batched) → post-validate → review → commit</note>
          </invoke-workflow>

          <!-- super-dev-pipeline handles verification internally, just check final status -->
          <output>✅ super-dev-pipeline completed</output>

          <!-- VERIFY COMPLETION: Re-check for unchecked tasks -->
          <action>Re-read story file and count unchecked tasks</action>

          <check if="{{remaining_unchecked}} > 0">
            <output>⚠️ Story still has {{remaining_unchecked}} unchecked tasks after pipeline</output>
            <action>Log incomplete tasks for review</action>
            <action>Mark as partial success</action>
          </check>

          <check if="{{remaining_unchecked}} == 0">
            <output>✅ Story complete - all tasks checked!</output>
            <action>Update story status to "done" in sprint-status.yaml</action>
          </check>

          <action>Increment success_count</action>
          <action>Update progress file: {{progress_file_path}}</action>
        </try>

        <catch>
          <output>❌ super-dev-pipeline failed: {{error}}</output>
          <action>Add to failed_stories with error details</action>
          <action>Increment failure_count</action>
        </catch>
      </check>
      </check>  <!-- Close validation_only != true check -->

      <output>Progress: {{success_count}} ✅ | {{failure_count}} ❌ | {{remaining}} pending</output>
    </loop>

    <action>Update progress file status to complete: {{progress_file_path}}</action>
  </step>

  <step n="4" goal="Epic completion and reporting">
    <!-- Final verification: scan all stories for unchecked tasks -->
    <action>Re-scan all epic stories for unchecked tasks</action>
    <action>Calculate: total_remaining_tasks across all stories</action>

    <output>
      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      🎉 EPIC {{epic_num}} PROCESSING COMPLETE!
      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

      **Results:**
      ✅ Stories processed: {{success_count}}/{{total_count}}
      {{if_failures}}❌ Stories failed: {{failure_count}}{{endif}}

      **Task Completion:**
      - Total tasks in epic: {{total_tasks}}
      - Completed: {{completed_tasks}} ✅
      - Remaining: {{remaining_tasks}} ⏳

      **Branch:** {{current_branch}}
      **All changes committed**

      {{if_all_tasks_complete}}
      ✅ **All tasks complete! Epic {{epic_num}} marked done in sprint-status.yaml**
      {{endif}}

      {{if_tasks_remaining}}
      ⚠️ **{{remaining_tasks}} tasks still unchecked - epic NOT marked complete**
      Stories with remaining work:
      {{list_incomplete_stories}}
      {{endif}}

      **Next Steps:**
      1. Review the work on branch {{current_branch}}
      2. Run human code review
      3. Merge when approved

      {{if_failures}}
      **Failed Stories Need Attention:**
      {{list_failed_stories}}
      {{endif}}
    </output>

    <check if="{{remaining_tasks}} == 0 AND {{failure_count}} == 0">
      <action>Update sprint-status: epic-{{epic_num}} = "done"</action>
    </check>

    <action>Remove progress file: {{progress_file_path}}</action>
  </step>

</workflow>