BMAD-METHOD/src/modules/bmm/workflows/4-implementation/batch-super-dev

Batch Super-Dev Workflow

Version: 1.2.0 (Added Story Validation & Auto-Creation) Created: 2026-01-06 Author: BMad

---

Overview

Interactive batch workflow for processing multiple ready-for-dev stories sequentially or in parallel using the super-dev-pipeline with full quality gates.

New in v1.2.0: Smart Story Validation & Auto-Creation - validates story files, creates missing stories, regenerates invalid ones automatically. New in v1.1.0: Smart Story Reconciliation - automatically verifies story accuracy after each implementation.

---

Features

Core Capabilities

1. 🆕 Smart Story Validation & Auto-Creation (NEW v1.2.0)

   • Validates all selected stories before processing
   • Checks for 12 required BMAD sections
   • Validates content quality (Current State ≥100 words, gap analysis present)
   • Auto-creates missing story files with codebase gap analysis
   • Auto-regenerates invalid stories (incomplete or stub files)
   • Interactive prompts (or fully automated with settings)
   • Backups existing files before regeneration

2. Interactive Story Selection

   • Lists all ready-for-dev stories from sprint-status.yaml
   • Shows story status icons (✅ file exists, ❌ missing, 🔄 needs status update)
   • Supports flexible selection syntax: single, ranges, comma-separated, "all"
   • Optional epic filtering (process only Epic 3 stories, etc.)

3. Execution Modes

   • Sequential: Process stories one-by-one in current session (easier monitoring)
   • Parallel: Spawn Task agents to process stories concurrently (faster, autonomous)
   • Configurable parallelism: 2, 4, or all stories at once

4. Full Quality Gates (from super-dev-pipeline)

   • Pre-gap analysis (validate story completeness)
   • Test-driven implementation
   • Post-validation (verify requirements met)
   • Multi-agent code review (4 specialized agents)
   • Targeted git commits
   • Definition of done verification

5. Smart Story Reconciliation (v1.1.0)

   • Automatically checks story accuracy after implementation
   • Verifies Acceptance Criteria checkboxes match Dev Agent Record
   • Verifies Tasks/Subtasks checkboxes match implementation
   • Verifies Definition of Done completion
   • Updates story status (done/review/in-progress) based on actual completion
   • Synchronizes sprint-status.yaml with story file status
   • Prevents "done" stories with unchecked items ✅

---

Smart Story Validation & Auto-Creation (NEW v1.2.0)

What It Does

Before processing any selected stories, the workflow automatically validates each story file:

1. File Existence Check - Verifies story file exists (tries multiple naming patterns)
2. Section Validation - Ensures all 12 BMAD sections are present
3. Content Quality Check - Validates sufficient content (not stubs):
   • Current State: ≥100 words
   • Gap analysis markers: ✅/❌ present
   • Acceptance Criteria: ≥3 items
   • Tasks: ≥5 items
4. Auto-Creation - Creates missing stories with codebase gap analysis
5. Auto-Regeneration - Regenerates invalid/incomplete story files

Why This Matters

Problem this solves:

Before v1.2.0:

User: "Process stories 3.1, 3.2, 3.3, 3.4"
Workflow: "Story 3.3 file missing - please create it first"
User: Ctrl+C → /create-story → /batch-super-dev again

After v1.2.0:

User: "Process stories 3.1, 3.2, 3.3, 3.4"
Workflow: "Story 3.3 missing - create it? (yes)"
User: "yes"
Workflow: Creates story 3.3 with gap analysis → Processes all 4 stories

Prevents:

• Incomplete story files being processed
• Missing gap analysis
• Stub files (< 100 words)
• Manual back-and-forth workflow interruptions

Validation Process

Load Sprint Status
       ↓
Display Available Stories
       ↓
🆕 VALIDATE EACH STORY  ← NEW STEP 2.5
       ↓
For each story:
  ┌─ File missing? → Prompt: "Create story with gap analysis?"
  │  └─ yes → /create-story-with-gap-analysis → ✅ Created
  │  └─ no → ⏭️ Skip story
  │
  ┌─ File exists but invalid?
  │  (< 12 sections OR < 100 words OR no gap analysis)
  │  → Prompt: "Regenerate story with codebase scan?"
  │  └─ yes → Backup original → /create-story-with-gap-analysis → ✅ Regenerated
  │  └─ no → ⏭️ Skip story
  │
  └─ File valid? → ✅ Ready to process
       ↓
Remove skipped stories
       ↓
Display Validated Stories
       ↓
User Selection (only validated stories)
       ↓
Process Stories

Configuration Options

In workflow.yaml:

# Story validation settings (NEW in v1.2.0)
validation:
  enabled: true                   # Enable/disable validation
  auto_create_missing: false      # Auto-create without prompting (use cautiously)
  auto_regenerate_invalid: false  # Auto-regenerate without prompting (use cautiously)
  min_sections: 12                # BMAD format requires all 12
  min_current_state_words: 100    # Minimum content length
  require_gap_analysis: true      # Must have ✅/❌ markers
  backup_before_regenerate: true  # Create .backup before regenerating

Interactive Mode (default):

• Prompts before creating/regenerating each story
• Safe, user retains control
• Recommended for most workflows

Fully Automated Mode:

validation:
  auto_create_missing: true
  auto_regenerate_invalid: true

• Creates/regenerates without prompting
• Faster for large batches
• Use with caution (may overwrite valid stories)

Example Session (v1.2.0)

🤖 /batch-super-dev

📊 Ready-for-Dev Stories (5)

1. **3-1-vehicle-card** ✅
   → Story file exists
2. **3-2-vehicle-search** ✅
   → Story file exists
3. **3-3-vehicle-compare** ❌
   → Story file missing
4. **3-4-vehicle-details** ⚠️
   → File exists (7/12 sections, stub content)
5. **3-5-vehicle-history** ✅
   → Story file exists

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 VALIDATING STORY FILES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Story 3-1-vehicle-card: ✅ Valid (12/12 sections, gap analysis present)

Story 3-2-vehicle-search: ✅ Valid (12/12 sections, gap analysis present)

📝 Story 3-3-vehicle-compare: File missing

Create story file with gap analysis? (yes/no): yes

Creating story 3-3-vehicle-compare with codebase gap analysis...
→ Scanning apps/frontend/web for existing components...
→ Scanning packages/widgets for related widgets...
→ Analyzing gap: 3 files exist, 5 need creation

✅ Story 3-3-vehicle-compare created successfully (12/12 sections)

⚠️ Story 3-4-vehicle-details: File incomplete or invalid
   - Sections: 7/12
   - Current State: stub (32 words, expected ≥100)
   - Gap analysis: missing

Regenerate story with codebase scan? (yes/no): yes

Regenerating story 3-4-vehicle-details with gap analysis...
→ Backing up to docs/sprint-artifacts/3-4-vehicle-details.md.backup
→ Scanning codebase for VehicleDetails implementation...
→ Found: packages/widgets/vehicle-details-v2 (partial)
→ Analyzing gap: 8 files exist, 3 need creation

✅ Story 3-4-vehicle-details regenerated successfully (12/12 sections)

Story 3-5-vehicle-history: ✅ Valid (12/12 sections, gap analysis present)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Story Validation Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Validated:** 5 stories ready to process
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Select stories to process: all

[Proceeds to process all 5 validated stories...]

---

Smart Story Reconciliation (v1.1.0)

What It Does

After each story completes, the workflow automatically:

1. Loads Dev Agent Record - Reads implementation summary, file list, test results
2. Analyzes Acceptance Criteria - Checks which ACs have evidence of completion
3. Analyzes Tasks - Verifies which tasks have been implemented
4. Analyzes Definition of Done - Confirms quality gates passed
5. Calculates Completion % - AC%, Tasks%, DoD% percentages
6. Determines Correct Status:
   • done: AC≥95% AND Tasks≥95% AND DoD≥95%
   • review: AC≥80% AND Tasks≥80% AND DoD≥80%
   • in-progress: Below 80% on any category
7. Updates Story File - Checks/unchecks boxes to match reality
8. Updates sprint-status.yaml - Synchronizes status entry

Why This Matters

Problem this solves:

Story 20.8 (before reconciliation):

• Dev Agent Record: "COMPLETE - 10 files created, 37 tests passing"
• Acceptance Criteria: All unchecked ❌
• Tasks: All unchecked ❌
• Definition of Done: All unchecked ❌
• sprint-status.yaml: ready-for-dev ❌
• Reality: Story was 100% complete but looked 0% complete!

After reconciliation:

• Acceptance Criteria: 17/18 checked ✅
• Tasks: 24/24 checked ✅
• Definition of Done: 24/25 checked ✅
• sprint-status.yaml: done ✅
• Accurate representation of actual completion ✅

Reconciliation Process

Implementation Complete
         ↓
Load Dev Agent Record
         ↓
Parse: Implementation Summary, File List, Test Results, Completion Notes
         ↓
For each checkbox in ACs/Tasks/DoD:
  - Search Dev Agent Record for evidence
  - Determine expected status (checked/unchecked/partial)
  - Compare actual vs expected
  - Record discrepancies
         ↓
Calculate completion percentages:
  - AC: X/Y checked (Z%)
  - Tasks: X/Y checked (Z%)
  - DoD: X/Y checked (Z%)
         ↓
Determine correct story status (done/review/in-progress)
         ↓
Apply changes (with user confirmation):
  - Update checkboxes in story file
  - Update story status header
  - Update sprint-status.yaml entry
         ↓
Report final completion statistics

Reconciliation Output

🔧 Story 20.8: Reconciling 42 issues

Changes to apply:
1. AC1: FlexibleGridSection component - CHECK (File created: FlexibleGridSection.tsx)
2. AC2: Screenshot automation - CHECK (File created: screenshot-pages.ts)
3. Task 1.3: Create page corpus generator - CHECK (File created: generate-page-corpus.ts)
... (39 more)

Apply these reconciliation changes? (yes/no): yes

✅ Story 20.8: Reconciliation complete (42 changes applied)

📊 Story 20.8 - Final Status

Acceptance Criteria: 17/18 (94%)
Tasks/Subtasks: 24/24 (100%)
Definition of Done: 24/25 (96%)

Story Status: done
sprint-status.yaml: done

✅ Story is COMPLETE and accurately reflects implementation

---

Usage

Basic Usage

# Process all ready-for-dev stories
/batch-super-dev

# Follow prompts:
# 1. See list of ready stories
# 2. Select stories to process (1,3-5,8 or "all")
# 3. Choose execution mode (sequential/parallel)
# 4. Confirm execution plan
# 5. Stories process automatically with reconciliation
# 6. Review batch summary

Epic Filtering

# Only process Epic 3 stories
/batch-super-dev filter_by_epic=3

Selection Syntax

Single: 1
Multiple: 1,3,5
Range: 1-5 (processes 1,2,3,4,5)
Mixed: 1,3-5,8 (processes 1,3,4,5,8)
All: all (processes all ready-for-dev stories)

Execution Modes

Sequential (Recommended for ≤5 stories):

• Processes one story at a time in current session
• Easier to monitor progress
• Lower resource usage
• Can pause/cancel between stories

Parallel (Recommended for >5 stories):

• Spawns autonomous Task agents
• Much faster (2-4x speedup)
• Choose parallelism: 2 (conservative), 4 (moderate), all (aggressive)
• Requires more system resources

---

Workflow Configuration

File: _bmad/bmm/workflows/4-implementation/batch-super-dev/workflow.yaml

Key Settings

# Safety limits
max_stories: 20  # Won't process more than 20 in one batch

# Pacing
pause_between_stories: 5  # Seconds between stories (sequential mode)

# Error handling
continue_on_failure: true  # Keep processing if one story fails

# Reconciliation (NEW v1.1.0)
reconciliation:
  enabled: true  # Auto-reconcile after each story
  require_confirmation: true  # Ask before applying changes
  update_sprint_status: true  # Sync sprint-status.yaml

---

Workflow Steps

1. Load Sprint Status

• Parses sprint-status.yaml
• Filters stories with status="ready-for-dev"
• Excludes epics and retrospectives
• Optionally filters by epic number

2. Display Available Stories

• Shows all ready-for-dev stories
• Verifies story files exist
• Displays status icons and comments

2.5. 🆕 Validate and Create/Regenerate Stories (NEW v1.2.0)

For each story:

• Check file existence (multiple naming patterns)
• Validate 12 BMAD sections present
• Check content quality (Current State ≥100 words, gap analysis)
• If missing: Prompt to create with gap analysis
• If invalid: Prompt to regenerate with codebase scan
• If valid: Mark ready to process
• Remove skipped stories from selection

3. Get User Selection

• Interactive story picker
• Supports flexible selection syntax
• Validates selection and confirms

3.5. Choose Execution Strategy

• Sequential vs Parallel
• If parallel: choose concurrency level
• Confirm execution plan

4. Process Stories

Sequential Mode:

• For each selected story:
  • Invoke super-dev-pipeline
  • Execute reconciliation (Step 4.5)
  • Report results
  • Pause between stories

Parallel Mode:

• Split stories into batches
• Spawn Task agents for each batch
• Wait for batch completion
• Execute reconciliation for each
• Report batch results

4.5. Smart Story Reconciliation (NEW)

Executed after each story completes:

• Load Dev Agent Record
• Analyze ACs/Tasks/DoD vs implementation
• Calculate completion percentages
• Determine correct story status
• Update checkboxes and status
• Sync sprint-status.yaml

See: step-4.5-reconcile-story-status.md for detailed algorithm

5. Display Batch Summary

• Shows completion statistics
• Lists failed stories (if any)
• Lists reconciliation warnings (if any)
• Provides next steps
• Saves batch log

---

Output Files

Batch Log

Location: docs/sprint-artifacts/batch-super-dev-{date}.log

Contains:

• Start/end timestamps
• Selected stories
• Completed stories
• Failed stories
• Reconciliation warnings
• Success rate
• Total duration

Reconciliation Results (per story)

Embedded in Dev Agent Record:

• Reconciliation summary
• Changes applied
• Final completion percentages
• Status determination reasoning

---

Error Handling

Story Implementation Fails

• Increments failed counter
• Adds to failed_stories list
• If continue_on_failure=true, continues with remaining stories
• If continue_on_failure=false, stops batch

Reconciliation Fails

• Story still marked as completed (implementation succeeded)
• Adds to reconciliation_warnings list
• User warned to manually verify story accuracy
• Does NOT fail the batch

Task Agent Fails (Parallel Mode)

• Collects error from TaskOutput
• Marks story as failed
• Continues with remaining stories in batch

---

Best Practices

Story Selection

• ✅ Start small: Process 2-3 stories first to verify workflow
• ✅ Group by epic: Related stories often share context
• ✅ Check file status: ✅ stories are ready, ❌ need creation first
• ❌ Don't process 20 stories at once on first run

Execution Mode

• Sequential for ≤5 stories (easier monitoring)
• Parallel for >5 stories (faster completion)
• Use parallelism=2 first, then increase if stable

During Execution

• Monitor progress output
• Check reconciliation reports
• Verify changes look correct
• Spot-check 1-2 completed stories

After Completion

1. Review batch summary
2. Check reconciliation warnings
3. Verify sprint-status.yaml updated
4. Run tests: pnpm test
5. Check coverage: pnpm test --coverage
6. Review commits: git log -<count>
7. Spot-check 2-3 stories for quality

---

Troubleshooting

Reconciliation Reports Many Warnings

Cause: Dev Agent Record may be incomplete or stories weren't fully implemented

Fix:

1. Review listed stories manually
2. Check Dev Agent Record has all required sections
3. Re-run super-dev-pipeline for problematic stories
4. Manually reconcile checkboxes if needed

Parallel Mode Hangs

Cause: Too many agents running concurrently, system resources exhausted

Fix:

1. Kill hung agents: /tasks then kill <task-id>
2. Reduce parallelism: Use 2 instead of 4
3. Process remaining stories sequentially

Story Marked "done" but has Unchecked Items

Cause: Reconciliation may have missed some checkboxes

Fix:

1. Review Dev Agent Record
2. Check which checkboxes should be checked
3. Manually check them or re-run reconciliation:
   • Load story file
   • Compare ACs/Tasks/DoD to Dev Agent Record
   • Update checkboxes to match reality

---

Version History

v1.2.0 (2026-01-06)

• NEW: Smart Story Validation & Auto-Creation (Step 2.5)
  • Validates story files before processing
  • Auto-creates missing stories with gap analysis
  • Auto-regenerates invalid/incomplete stories
  • Checks 12 BMAD sections, content quality
  • Interactive or fully automated modes
  • Backups before regeneration
• Removes friction: No more "story file missing" interruptions
• Ensures quality: Only valid stories with gap analysis proceed
• Configuration: New validation settings in workflow.yaml

v1.1.0 (2026-01-06)

• NEW: Smart Story Reconciliation (Step 4.5)
  • Auto-verifies story accuracy after implementation
  • Updates checkboxes based on Dev Agent Record
  • Synchronizes sprint-status.yaml
  • Prevents "done" stories with unchecked items
• Added reconciliation warnings to batch summary
• Added reconciliation statistics to output

v1.0.0 (2026-01-05)

• Initial release
• Interactive story selector
• Sequential and parallel execution modes
• Integration with super-dev-pipeline
• Batch summary and logging

---

Related Workflows

• super-dev-pipeline: Individual story implementation (invoked by batch-super-dev)
• create-story-with-gap-analysis: Create new stories with codebase scan
• sprint-status: View/update sprint status
• multi-agent-review: Standalone code review (part of super-dev-pipeline)

---

Support

Questions or Issues:

• Check workflow logs: docs/sprint-artifacts/batch-super-dev-*.log
• Review reconciliation step: step-4.5-reconcile-story-status.md
• Check story file format: Ensure 12-section BMAD format
• Verify Dev Agent Record populated: Required for reconciliation

---

Last Updated: 2026-01-06 Status: Active - Production-ready with reconciliation Maintained By: BMad