From 5ea139d7be592e686d9d89bc3c5c2001674150ea Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Wed, 7 Jan 2026 21:09:06 -0500 Subject: [PATCH] fix(batch-super-dev): Apply agent limitation patches to Step 2.5 - Update instructions.md Step 2.5 to explicitly halt when story creation/regeneration is needed (agents cannot invoke workflows) - Add clear user guidance with manual action steps - Add manual_actions_required tracking to batch summary (Step 5) - Update README.md with Critical Prerequisites section - Create scripts/validate-all-stories.sh for pre-batch validation This addresses the root cause where batch-super-dev told agents to "Invoke workflow: /create-story-with-gap-analysis" which is not possible in batch mode. Agents now gracefully skip invalid stories and provide clear instructions for manual intervention. Follows recommendations from BMAD-WORKFLOW-IMPROVEMENTS.md --- scripts/validate-all-stories.sh | 331 ++++++++++++++++++ .../batch-super-dev/README.md | 71 +++- .../batch-super-dev/instructions.md | 135 +++++-- 3 files changed, 506 insertions(+), 31 deletions(-) create mode 100755 scripts/validate-all-stories.sh diff --git a/scripts/validate-all-stories.sh b/scripts/validate-all-stories.sh new file mode 100755 index 00000000..179f9a12 --- /dev/null +++ b/scripts/validate-all-stories.sh @@ -0,0 +1,331 @@ +#!/bin/bash +# ============================================================================= +# BMAD Story Format Validation Script +# ============================================================================= +# +# Validates all ready-for-dev stories have proper BMAD format before batch +# execution. Run this BEFORE /batch-super-dev to prevent wasted time. +# +# Usage: +# ./scripts/validate-all-stories.sh # Validate all ready-for-dev +# ./scripts/validate-all-stories.sh story-20-13a-1.md # Validate specific file +# ./scripts/validate-all-stories.sh --help # Show help +# +# Exit codes: +# 0 - All stories valid +# 1 - One or more stories invalid +# +# ============================================================================= + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Required BMAD sections (12 total) +REQUIRED_SECTIONS=( + "Business Context" + "Current State" + "Acceptance Criteria" + "Tasks" + "Technical Requirements" + "Architecture Compliance" + "Testing Requirements" + "Dev Agent Guardrails" + "Definition of Done" + "References" + "Dev Agent Record" + "Change Log" +) + +# Minimum requirements +MIN_TASKS=3 +MIN_SECTIONS=12 + +# Help message +show_help() { + cat </dev/null; then + ((section_count++)) + else + missing_sections+=("$section") + fi + done + + # Count unchecked tasks + local task_count + task_count=$(grep -c "^- \[ \]" "$file" 2>/dev/null || echo "0") + + # Build error list + if [ "$section_count" -lt "$MIN_SECTIONS" ]; then + errors+=("Only $section_count/$MIN_SECTIONS sections") + fi + + if [ "$task_count" -lt "$MIN_TASKS" ]; then + errors+=("Only $task_count tasks (need >=$MIN_TASKS)") + fi + + # Output results + if [ ${#errors[@]} -eq 0 ]; then + if [ "$QUIET" != "true" ]; then + echo -e "${GREEN}VALID${NC} - $section_count sections, $task_count tasks" + fi + return 0 + else + if [ "$QUIET" != "true" ]; then + echo -e "${RED}INVALID${NC} - ${errors[*]}" + if [ "$VERBOSE" == "true" ] && [ ${#missing_sections[@]} -gt 0 ]; then + echo " Missing sections: ${missing_sections[*]}" + fi + fi + return 1 + fi +} + +# Main execution +main() { + local total=0 + local valid=0 + local invalid=0 + local invalid_files=() + + echo "==========================================" + echo " BMAD Story Format Validation" + echo "==========================================" + echo "" + + # Determine which files to validate + if [ ${#FILES[@]} -gt 0 ]; then + # Validate specific files + for file in "${FILES[@]}"; do + ((total++)) + if [ "$QUIET" != "true" ]; then + printf "%-50s " "$file" + fi + if validate_story "$file"; then + ((valid++)) + else + ((invalid++)) + invalid_files+=("$file") + fi + done + else + # Find sprint-status.yaml and validate ready-for-dev stories + local sprint_status="" + + # Try common locations + for location in "docs/sprint-artifacts/sprint-status.yaml" "_bmad/docs/sprint-artifacts/sprint-status.yaml" "sprint-status.yaml"; do + if [ -f "$location" ]; then + sprint_status="$location" + break + fi + done + + if [ -z "$sprint_status" ]; then + echo -e "${YELLOW}Warning: sprint-status.yaml not found${NC}" + echo "Falling back to validating all story-*.md files in docs/sprint-artifacts/" + echo "" + + # Fallback: validate all story files + for file in docs/sprint-artifacts/story-*.md _bmad/docs/sprint-artifacts/story-*.md 2>/dev/null; do + if [ -f "$file" ]; then + ((total++)) + if [ "$QUIET" != "true" ]; then + printf "%-50s " "$(basename "$file")" + fi + if validate_story "$file"; then + ((valid++)) + else + ((invalid++)) + invalid_files+=("$file") + fi + fi + done + else + echo "Using: $sprint_status" + echo "" + + # Get ready-for-dev stories from sprint-status.yaml + local stories + stories=$(grep -E "^\s*\S+:.*ready-for-dev" "$sprint_status" 2>/dev/null | awk -F: '{print $1}' | tr -d ' ' || true) + + if [ -z "$stories" ]; then + echo -e "${YELLOW}No ready-for-dev stories found in sprint-status.yaml${NC}" + echo "" + echo "==========================================" + echo " Summary" + echo "==========================================" + echo "Total Stories: 0" + echo "" + echo -e "${GREEN}Nothing to validate!${NC}" + exit 0 + fi + + # Validate each story + for story in $stories; do + # Try multiple file naming patterns + local story_file="" + local base_dir + base_dir=$(dirname "$sprint_status") + + for pattern in "$base_dir/story-$story.md" "$base_dir/$story.md"; do + if [ -f "$pattern" ]; then + story_file="$pattern" + break + fi + done + + ((total++)) + if [ "$QUIET" != "true" ]; then + printf "%-50s " "$story" + fi + + if [ -z "$story_file" ]; then + if [ "$QUIET" != "true" ]; then + echo -e "${RED}FILE MISSING${NC}" + fi + ((invalid++)) + invalid_files+=("$story (file not found)") + else + if validate_story "$story_file"; then + ((valid++)) + else + ((invalid++)) + invalid_files+=("$story_file") + fi + fi + done + fi + fi + + # Summary + echo "" + echo "==========================================" + echo " Summary" + echo "==========================================" + echo "Total Stories: $total" + echo -e "Valid: ${GREEN}$valid${NC}" + echo -e "Invalid: ${RED}$invalid${NC}" + echo "" + + if [ "$invalid" -eq 0 ]; then + echo -e "${GREEN}All stories ready for batch execution!${NC}" + echo "" + echo "Next step: /batch-super-dev" + exit 0 + else + echo -e "${RED}$invalid stories need regeneration${NC}" + echo "" + echo "Invalid stories:" + for file in "${invalid_files[@]}"; do + echo " - $file" + done + echo "" + echo "Fix by running for each invalid story:" + echo " /create-story-with-gap-analysis" + echo "" + echo "Then re-run validation:" + echo " ./scripts/validate-all-stories.sh" + exit 1 + fi +} + +# Run main +main diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/README.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/README.md index c3f66521..b0c6ebaf 100644 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/README.md +++ b/src/modules/bmm/workflows/4-implementation/batch-super-dev/README.md @@ -1,12 +1,79 @@ # Batch Super-Dev Workflow -**Version:** 1.3.0 (Complexity Routing + Semaphore Pattern + Continuous Tracking) +**Version:** 1.3.1 (Agent Limitations Documentation) **Created:** 2026-01-06 -**Updated:** 2026-01-07 +**Updated:** 2026-01-08 **Author:** BMad --- +## Critical Prerequisites + +> **⚠️ IMPORTANT: Read before running batch-super-dev!** + +**BEFORE running batch-super-dev:** + +### ✅ 1. All stories must be properly generated + +- Run: `/create-story-with-gap-analysis` for each story +- Do NOT create skeleton/template files manually +- Validation: `./scripts/validate-all-stories.sh` + +**Why:** Agents CANNOT invoke `/create-story-with-gap-analysis` workflow. Story generation requires user interaction and context-heavy codebase scanning. + +### ✅ 2. All stories must have 12 BMAD sections + +Required sections: +1. Business Context +2. Current State +3. Acceptance Criteria +4. Tasks/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 + +### ✅ 3. All stories must have tasks + +- At least 3 unchecked tasks (minimum for valid story) +- Zero-task stories will be skipped +- Validation: `grep -c "^- \[ \]" story-file.md` + +### Common Failure Mode: Batch Regeneration + +**What you might try:** +``` +1. Create 20 skeleton story files (just headers + widget lists) +2. Run /batch-super-dev +3. Expect agents to regenerate them +``` + +**What happens:** +- Agents identify stories are incomplete +- Agents correctly halt per super-dev-pipeline validation +- Stories get skipped (not regenerated) +- You waste time + +**Solution:** +```bash +# 1. Generate all stories (1-2 days, manual) +/create-story-with-gap-analysis # For each story + +# 2. Validate (30 seconds, automated) +./scripts/validate-all-stories.sh + +# 3. Execute (4-8 hours, parallel autonomous) +/batch-super-dev +``` + +See: `AGENT-LIMITATIONS.md` for full documentation on what agents can and cannot do. + +--- + ## Overview Interactive batch workflow for processing multiple `ready-for-dev` stories sequentially or in parallel using the super-dev-pipeline with full quality gates. diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/instructions.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/instructions.md index ed87759c..be66012f 100644 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/batch-super-dev/instructions.md @@ -123,27 +123,56 @@ Run `/bmad:bmm:workflows:sprint-status` to see current status. Create story file with gap analysis? (yes/no): - Creating story {{story_key}} with codebase gap analysis... - Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis - Parameters: story_key={{story_key}} + +⚠️ STORY CREATION REQUIRES MANUAL WORKFLOW EXECUTION - - ✅ Story {{story_key}} created successfully (12/12 sections) - Update file_status_icon to ✅ - Mark story as validated - +**Story:** {{story_key}} +**Status:** File missing or incomplete - - ❌ Story creation failed: {{story_key}} - Mark story for removal from selection - Add to skipped_stories list with reason: "Creation failed" - +**Problem:** +Agents cannot invoke /create-story-with-gap-analysis workflow autonomously. +This workflow requires: +- Interactive user prompts +- Context-heavy codebase scanning +- Gap analysis decision-making + +**Required Action:** + +1. **Exit this batch execution:** + - Remaining stories will be skipped + - Batch will continue with valid stories only + +2. **Regenerate story manually:** + ``` + /create-story-with-gap-analysis + ``` + When prompted, provide: + - Story key: {{story_key}} + - Epic: {epic from parent story} + - Scope: {widget list or feature description} + +3. **Validate story format:** + ``` + ./scripts/validate-all-stories.sh + ``` + Must show: "✅ All stories ready for batch execution!" + +4. **Re-run batch-super-dev:** + - Story will now be properly formatted + - Can be executed in next batch run + +**Skipping story {{story_key}} from current batch execution.** + + + Mark story for removal from selection + Add to skipped_stories list with reason: "Story creation requires manual workflow (agents cannot invoke /create-story)" + Add to manual_actions_required list: "Regenerate {{story_key}} with /create-story-with-gap-analysis" - ⏭️ Skipping story {{story_key}} (file missing) + ⏭️ Skipping story {{story_key}} (file missing, user declined creation) Mark story for removal from selection - Add to skipped_stories list with reason: "User declined creation" + Add to skipped_stories list with reason: "User declined story creation" @@ -214,22 +243,51 @@ This story will be SKIPPED. 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}} + +⚠️ STORY REGENERATION REQUIRES MANUAL WORKFLOW EXECUTION - - ✅ Story {{story_key}} regenerated successfully (12/12 sections) - Mark story as validated - +**Story:** {{story_key}} +**Status:** File incomplete or invalid ({{sections_found}}/12 sections) - - ❌ Regeneration failed, using backup: {{story_key}} - Restore from backup - Mark story for removal with warning - Add to skipped_stories list with reason: "Regeneration failed" - +**Problem:** +Agents cannot invoke /create-story-with-gap-analysis workflow autonomously. +Story regeneration requires: +- Interactive user prompts +- Context-heavy codebase scanning +- Gap analysis decision-making + +**Required Action:** + +1. **Exit this batch execution:** + - This story will be skipped + - Batch will continue with valid stories only + +2. **Backup existing file (optional):** + ``` + cp {{file_path}} {{file_path}}.backup + ``` + +3. **Regenerate story manually:** + ``` + /create-story-with-gap-analysis + ``` + When prompted, provide: + - Story key: {{story_key}} + +4. **Validate story format:** + ``` + ./scripts/validate-all-stories.sh + ``` + +5. **Re-run batch-super-dev:** + - Story will now be properly formatted + +**Skipping story {{story_key}} from current batch execution.** + + + Mark story for removal from selection + Add to skipped_stories list with reason: "Story regeneration requires manual workflow (agents cannot invoke /create-story)" + Add to manual_actions_required list: "Regenerate {{story_key}} with /create-story-with-gap-analysis" @@ -836,6 +894,25 @@ Review these stories to ensure checkboxes and status are accurate. Check Dev Agent Record vs Acceptance Criteria/Tasks/DoD sections. {{/if}} +{{#if manual_actions_required.length > 0}} +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +⚠️ MANUAL ACTIONS REQUIRED +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**{{manual_actions_required.length}} stories require manual intervention:** + +{{#each manual_actions_required}} +{{@index}}. **{{story_key}}** + Action: Regenerate story with proper BMAD format + Command: `/create-story-with-gap-analysis` +{{/each}} + +**After completing these actions:** +1. Validate all stories: `./scripts/validate-all-stories.sh` +2. Re-run batch-super-dev for these stories +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +{{/if}} + **Next steps:** 1. Check sprint-status.yaml - stories should be marked "done" or "review" 2. Run tests: `pnpm test`