27 KiB

Raw Blame History

Batch Super-Dev - Interactive Story Selector

AKA: "Mend the Gap" 🚇

Primary Use Case: Gap analysis and reconciliation workflow

This workflow helps you "mind the gap" between story requirements and codebase reality, then "mend the gap" by building only what's truly missing.

What This Workflow Does

Scans codebase to verify what's actually implemented vs what stories claim
Finds the gap between story requirements and reality
Mends the gap by building ONLY what's truly missing (no duplicate work)
Updates tracking to reflect actual completion status (check boxes, sprint-status)

Common Use Cases

Reconciliation Mode (Most Common):

Work was done but not properly tracked
Stories say "build X" but X is 60-80% already done
Need second set of eyes to find real gaps
Update story checkboxes to match reality

Greenfield Mode:

Story says "build X", nothing exists
Build 100% from scratch with full quality gates

Brownfield Mode:

Story says "modify X", X exists
Refactor carefully, add only new requirements

Execution Modes

Sequential (Recommended for Gap Analysis):

Process stories ONE-BY-ONE in THIS SESSION
After each story: verify existing code → build only gaps → check boxes → move to next
Easier to monitor, can intervene if issues found
Best for reconciliation work

Parallel (For Greenfield Batch Implementation):

Spawn autonomous Task agents to process stories concurrently
Faster completion but harder to monitor
Best when stories are independent and greenfield

The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/batch-super-dev/workflow.yaml

Read {sprint_status} file Parse metadata: project, project_key, tracking_system Parse development_status map

Filter stories with status = "ready-for-dev" Exclude entries that are epics (keys starting with "epic-") or retrospectives (keys ending with "-retrospective")

Further filter stories to only include those starting with "{filter_by_epic}-" If filter_by_epic = "3", only include stories like "3-1-...", "3-2-...", etc.

Sort filtered stories by epic number, then story number (e.g., 1-1, 1-2, 2-1, 3-1) Store as: ready_for_dev_stories (list of story keys)

✅ No ready-for-dev stories found.

All stories are either in-progress, review, or done!

Run /bmad:bmm:workflows:sprint-status to see current status. Exit workflow

Read comment field for each story from sprint-status.yaml (text after # on the same line)

For each story, verify story file exists using multiple naming patterns: Try in order: 1) {sprint_artifacts}/{story_key}.md, 2) {sprint_artifacts}/story-{story_key}.md, 3) {sprint_artifacts}/{story_key_with_dots}.md Mark stories as: ✅ (file exists), ❌ (file missing), 🔄 (already implemented but not marked done)

## 📦 Ready-for-Dev Stories ({{count}})

{{#if filter_by_epic}} Filtered by Epic {{filter_by_epic}} {{/if}}

{{#each ready_for_dev_stories}} {{@index}}. {{key}} {{file_status_icon}} {{#if comment}}→ {{comment}}{{/if}} {{#if file_path}} File: {{file_path}}{{/if}} {{/each}}

Legend:

✅ Story file exists, ready to implement
🔄 Already implemented, just needs status update
❌ Story file missing, needs creation first

Total: {{count}} stories available Max batch size: {{max_stories}} stories

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

For each story in ready_for_dev_stories:

Check if story file exists (already done in Step 2)

<check if="file_status_icon == '❌' (file missing)">
  <output>

📝 Story {{story_key}}: File missing

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

  <check if="response == 'yes'">
    <output>Creating story {{story_key}} with codebase gap analysis...</output>
    <action>Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis</action>
    <action>Parameters: story_key={{story_key}}</action>

    <check if="story creation succeeded">
      <output>✅ Story {{story_key}} created successfully (12/12 sections)</output>
      <action>Update file_status_icon to ✅</action>
      <action>Mark story as validated</action>
    </check>

    <check if="story creation failed">
      <output>❌ Story creation failed: {{story_key}}</output>
      <action>Mark story for removal from selection</action>
      <action>Add to skipped_stories list with reason: "Creation failed"</action>
    </check>
  </check>

  <check if="response == 'no'">
    <output>⏭️ Skipping story {{story_key}} (file missing)</output>
    <action>Mark story for removal from selection</action>
    <action>Add to skipped_stories list with reason: "User declined creation"</action>
  </check>
</check>

<check if="file_status_icon == '✅' (file exists)">
  <action>Read story file: {{file_path}}</action>
  <action>Parse sections and validate BMAD format</action>

  <action>Check for all 12 required sections:
    1. Business Context
    2. Current State
    3. Acceptance Criteria
    4. Tasks and Subtasks
    5. Technical Requirements
    6. Architecture Compliance
    7. Testing Requirements
    8. Dev Agent Guardrails
    9. Definition of Done
    10. References
    11. Dev Agent Record
    12. Change Log
  </action>

  <action>Count sections present: sections_found</action>
  <action>Check Current State content length (word count)</action>
  <action>Check Acceptance Criteria item count</action>
  <action>Check Tasks item count</action>
  <action>Look for gap analysis markers (✅/❌) in Current State</action>

  <check if="sections_found < 12 OR Current State < 100 words OR no gap analysis markers">
    <output>

⚠️ Story {{story_key}}: File incomplete or invalid

Sections: {{sections_found}}/12 {{#if Current State < 100 words}}- Current State: stub ({{word_count}} words, expected ≥100){{/if}} {{#if no gap analysis}}- Gap analysis: missing{{/if}}

Regenerate story with codebase scan? (yes/no):
Regenerating story {{story_key}} with gap analysis... Backup existing file to {{file_path}}.backup Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis Parameters: story_key={{story_key}}
```
 <check if="regeneration succeeded">
   <output>✅ Story {{story_key}} regenerated successfully (12/12 sections)</output>
   <action>Mark story as validated</action>
 </check>

 <check if="regeneration failed">
   <output>❌ Regeneration failed, using backup: {{story_key}}</output>
   <action>Restore from backup</action>
   <action>Mark story for removal with warning</action>
   <action>Add to skipped_stories list with reason: "Regeneration failed"</action>
 </check>
```
⏭️ Skipping story {{story_key}} (file incomplete) Mark story for removal from selection Add to skipped_stories list with reason: "User declined regeneration" ✅ Story {{story_key}}: Valid (12/12 sections, gap analysis present) Mark story as validated

</check>

<check if="file_status_icon == '🔄' (already implemented)">
  <output>✅ Story {{story_key}}: Already implemented (will skip or reconcile only)</output>
  <action>Mark story as validated (already done)</action>
</check>

Remove skipped stories from ready_for_dev_stories Update count of available stories

⏭️ Skipped Stories ({{skipped_count}}): {{#each skipped_stories}} - {{story_key}}: {{reason}} {{/each}} ❌ No valid stories remaining after validation.

All stories were either:

Missing files (user declined creation)
Invalid/incomplete (user declined regeneration)
Already implemented

Run /bmad:bmm:workflows:sprint-status to see status. Exit workflow

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ Story Validation Complete ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Validated:** {{validated_count}} stories ready to process {{#if skipped_count > 0}}**Skipped:** {{skipped_count}} stories{{/if}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 SCORING STORY COMPLEXITY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For each validated story:

Read story file: {{file_path}}

<action>Count unchecked tasks ([ ]) at top level only in Tasks/Subtasks section → task_count
  (See workflow.yaml complexity.task_counting.method = "top_level_only")
</action>
<action>Extract file paths mentioned in tasks → file_count</action>
<action>Scan story title and task descriptions for risk keywords using rules from workflow.yaml:
  - Case insensitive matching (require_word_boundaries: true)
  - Include keyword variants (e.g., "authentication" matches "auth")
  - Scan: story_title, task_descriptions, subtask_descriptions
</action>

<action>Calculate complexity score:
  - Base score = task_count
  - Add 5 for each HIGH risk keyword match (auth, security, payment, migration, database, schema, encryption)
  - Add 2 for each MEDIUM risk keyword match (api, integration, external, third-party, cache)
  - Add 0 for LOW risk keywords (ui, style, config, docs, test)
  - Count each keyword only once (no duplicates)
</action>

<action>Assign complexity level using mutually exclusive decision tree (priority order):

  1. Check COMPLEX first (highest priority):
     IF (task_count ≥ 16 OR complexity_score ≥ 20 OR has ANY HIGH risk keyword)
     THEN level = COMPLEX

  2. Else check MICRO (lowest complexity):
     ELSE IF (task_count ≤ 3 AND complexity_score ≤ 5 AND file_count ≤ 5)
     THEN level = MICRO

  3. Else default to STANDARD:
     ELSE level = STANDARD

  This ensures no overlaps:
  - Story with HIGH keyword → COMPLEX (never MICRO or STANDARD)
  - Story with 4-15 tasks or >5 files → STANDARD (not MICRO or COMPLEX)
  - Story with ≤3 tasks, ≤5 files, no HIGH keywords → MICRO
</action>

<action>Store complexity_level for story: {{story_key}}.complexity = {level, score, task_count, risk_keywords}</action>

Group stories by complexity level

📊 **Complexity Analysis Complete**

{{#each complexity_groups}} {{level}} Stories ({{count}}): {{#each stories}}

{{story_key}}: {{task_count}} tasks, score {{score}}{{#if risk_keywords}}, risk: {{risk_keywords}}{{/if}} {{/each}} {{/each}}

Pipeline Routing:

🚀 MICRO ({{micro_count}}): Lightweight path - skip gap analysis + code review
⚙️ STANDARD ({{standard_count}}): Full pipeline with all quality gates
🔒 COMPLEX ({{complex_count}}): Enhanced validation + consider splitting

{{#if complex_count > 0}} ⚠️ Warning: {{complex_count}} complex stories detected. Consider:

Breaking into smaller stories before processing
Running these separately with extra attention {{/if}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Select stories to process:**

Enter story numbers to process (examples):

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 {{count}} stories)

Or:

cancel - Exit without processing

Your selection:

Parse user input

❌ Batch processing cancelled. Exit workflow Set selected_stories = all ready_for_dev_stories Parse selection (handle commas, ranges) Input "1,3-5,8" → indexes [1,3,4,5,8] → map to story keys Map selected indexes to story keys from ready_for_dev_stories Store as: selected_stories ⚠️ You selected {{count}} stories, but max_stories is {{max_stories}}.

Only the first {{max_stories}} will be processed. Truncate selected_stories to first max_stories entries

Display confirmation

📋 Selected Stories ({{count}})

{{#each selected_stories}} {{@index}}. {{key}} {{/each}}

Estimated time: {{count}} stories × 30-60 min/story = {{estimated_hours}} hours

**How should these stories be processed?**

Options:

sequential: Run stories one-by-one in this session (slower, easier to monitor)
parallel: Spawn Task agents to process stories concurrently (faster, autonomous)

Enter: sequential or parallel

Capture response as: execution_mode

Set parallel_count = 1 Set use_task_agents = false ✅ Sequential mode selected - stories will be processed one-by-one in this session Set use_task_agents = true

<ask>

How many agents should run in parallel?

Options:

2: Conservative (low resource usage, easier debugging)
4: Moderate (balanced performance, recommended)
8: Aggressive (higher throughput)
10: Maximum (10 agent limit for safety)
all: Use all stories (max 10 agents)

Enter number (2-10) or 'all':

<action>Capture response as: parallel_count</action>
<action>If parallel_count == 'all': set parallel_count = min(count of selected_stories, 10)</action>
<action>If parallel_count > 10: set parallel_count = 10 (safety limit)</action>

<check if="parallel_count was capped at 10">
  <output>⚠️ Requested {{original_count}} agents, capped at 10 (safety limit)</output>
</check>

## ⚙️ Execution Plan

Mode: {{execution_mode}} {{#if use_task_agents}} Task Agents: {{parallel_count}} running concurrently Agent Type: general-purpose (autonomous) {{else}} Sequential processing in current session {{/if}}

Stories to process: {{count}} Estimated total time: {{#if use_task_agents}}

With {{parallel_count}} agents: {{estimated_hours / parallel_count}} hours {{else}}
Sequential: {{estimated_hours}} hours {{/if}}

Confirm execution plan? (yes/no):
❌ Batch processing cancelled. Exit workflow

Initialize counters: completed=0, failed=0, failed_stories=[], reconciliation_warnings=[], reconciliation_warnings_count=0 Set start_time = current timestamp Jump to Step 4-Parallel (Task Agent execution) Continue to Step 4-Sequential (In-session execution) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚀 SEQUENTIAL BATCH PROCESSING STARTED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Stories:** {{count}} **Mode:** super-dev-pipeline (batch, sequential) **Continue on failure:** {{continue_on_failure}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For each story in selected_stories:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📦 Story {{current_index}}/{{total_count}}: {{story_key}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

<action>Invoke workflow: /bmad:bmm:workflows:super-dev-pipeline</action>
<action>Parameters: mode=batch, story_key={{story_key}}, complexity_level={{story_key}}.complexity.level</action>

<check if="super-dev-pipeline succeeded">
  <output>✅ Implementation complete: {{story_key}}</output>

  <action>Execute Step 4.5: Smart Story Reconciliation</action>
  <action>Load reconciliation instructions: {installed_path}/step-4.5-reconcile-story-status.md</action>
  <action>Execute reconciliation with story_key={{story_key}}</action>

  <check if="reconciliation succeeded">
    <output>✅ COMPLETED: {{story_key}} (reconciled)</output>
    <action>Increment completed counter</action>
  </check>

  <check if="reconciliation failed">
    <output>⚠️ WARNING: {{story_key}} completed but reconciliation failed</output>
    <action>Increment completed counter (implementation was successful)</action>
    <action>Add to reconciliation_warnings: {story_key: {{story_key}}, warning_message: "Reconciliation failed - manual verification needed"}</action>
    <action>Increment reconciliation_warnings_count</action>
  </check>
</check>

<check if="super-dev-pipeline failed">
  <output>❌ FAILED: {{story_key}}</output>
  <action>Increment failed counter</action>
  <action>Add story_key to failed_stories list</action>

  <check if="continue_on_failure == false">
    <output>⚠️ Stopping batch due to failure (continue_on_failure=false)</output>
    <action>Jump to Step 5 (Summary)</action>
  </check>
</check>

<check if="display_progress == true">
  <output>

Progress: {{completed}} completed, {{failed}} failed, {{remaining}} remaining

<check if="not last story AND pause_between_stories > 0">
  <output>⏸️ Pausing {{pause_between_stories}} seconds before next story...</output>
  <action>Wait {{pause_between_stories}} seconds</action>
</check>

After all stories processed, jump to Step 5 (Summary)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚀 PARALLEL BATCH PROCESSING STARTED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Stories:** {{count}} **Mode:** Task agents (autonomous, parallel) **Agents in parallel:** {{parallel_count}} **Continue on failure:** {{continue_on_failure}} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Split selected_stories into batches of size parallel_count Example: If 10 stories and parallel_count=4, create batches: [1-4], [5-8], [9-10]

For each batch of stories:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📦 Batch {{batch_index}}/{{total_batches}}: Spawning {{stories_in_batch}} agents ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Stories in this batch: {{#each stories_in_batch}} {{@index}}. {{story_key}} {{/each}}

Spawning Task agents in parallel...

<action>For each story in current batch, spawn Task agent with these parameters:</action>
<action>
  Task tool parameters:
  - subagent_type: "general-purpose"
  - description: "Implement story {{story_key}}"
  - prompt: "Execute super-dev-pipeline workflow for story {{story_key}}.

             CRITICAL INSTRUCTIONS:
             1. Load workflow.xml: _bmad/core/tasks/workflow.xml
             2. Load workflow config: _bmad/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml
             3. Execute in BATCH mode with story_key={{story_key}} and complexity_level={{story_key}}.complexity.level
             4. Follow all 7 pipeline steps (init, pre-gap, implement, post-validate, code-review, complete, summary)
             5. Commit changes when complete
             6. Report final status (done/failed) with file list

             Story file will be auto-resolved from multiple naming conventions."
  - run_in_background: false (wait for completion to track results)
</action>

<action>Store task IDs for this batch: task_ids[]</action>

<output>

✅ Spawned {{stories_in_batch}} Task agents

Agents will process stories autonomously with full quality gates:

Pre-gap analysis (validate tasks)
Implementation (TDD/refactor)
Post-validation (verify completion)
Code review (find 3-10 issues)
Git commit (targeted files only)

{{#if not last_batch}} Waiting for this batch to complete before spawning next batch... {{/if}}

<action>Wait for all agents in batch to complete</action>
<action>Collect results from each agent via TaskOutput</action>

<iterate>For each completed agent:</iterate>
<check if="agent succeeded">
  <output>✅ Implementation complete: {{story_key}}</output>

  <action>Execute Step 4.5: Smart Story Reconciliation</action>
  <action>Load reconciliation instructions: {installed_path}/step-4.5-reconcile-story-status.md</action>
  <action>Execute reconciliation with story_key={{story_key}}</action>

  <check if="reconciliation succeeded">
    <output>✅ COMPLETED: {{story_key}} (reconciled)</output>
    <action>Increment completed counter</action>
  </check>

  <check if="reconciliation failed">
    <output>⚠️ WARNING: {{story_key}} completed but reconciliation failed</output>
    <action>Increment completed counter (implementation was successful)</action>
    <action>Add to reconciliation_warnings: {story_key: {{story_key}}, warning_message: "Reconciliation failed - manual verification needed"}</action>
    <action>Increment reconciliation_warnings_count</action>
  </check>
</check>

<check if="agent failed">
  <output>❌ FAILED: {{story_key}}</output>
  <action>Increment failed counter</action>
  <action>Add story_key to failed_stories list</action>
</check>

<output>

Batch {{batch_index}} Complete: {{batch_completed}} succeeded, {{batch_failed}} failed Overall Progress: {{completed}}/{{total_count}} completed

After all batches processed, jump to Step 5 (Summary)

Calculate end_time and total_duration Calculate success_rate = (completed / total_count) * 100 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 BATCH SUMMARY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Total stories:** {{total_count}} **✅ Completed:** {{completed}} **❌ Failed:** {{failed}} **⚠️ Reconciliation warnings:** {{reconciliation_warnings_count}} **Success rate:** {{success_rate}}% **Duration:** {{total_duration}}

{{#if failed > 0}} Failed stories: {{#each failed_stories}}

{{this}} {{/each}}

Retry failed stories:

{{#each failed_stories}}
/bmad:bmm:workflows:super-dev-pipeline mode=batch story_key={{this}}
{{/each}}

{{#if reconciliation_warnings_count > 0}} ⚠️ Reconciliation warnings (stories completed but status may be inaccurate): {{#each reconciliation_warnings}}

{{story_key}}: {{warning_message}} {{/each}}

Manual reconciliation needed: Review these stories to ensure checkboxes and status are accurate. Check Dev Agent Record vs Acceptance Criteria/Tasks/DoD sections. {{/if}}

Next steps:

Check sprint-status.yaml - stories should be marked "done" or "review"
Run tests: pnpm test
Check coverage: pnpm test --coverage
Review commits: git log -{{completed}}
Spot-check 2-3 stories for quality

Run another batch? /bmad:bmm:workflows:batch-super-dev ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Save batch log to {batch_log} Log contents: start_time, end_time, total_duration, selected_stories, completed_stories, failed_stories, success_rate

27 KiB Raw Blame History Unescape Escape