Merge branch 'main' of github.com:jschulte/BMAD-METHOD

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 <<EOF
+BMAD Story Format Validation Script
+
+Validates story files have proper BMAD format before batch execution.
+
+USAGE:
+    ./scripts/validate-all-stories.sh [OPTIONS] [FILE...]
+
+OPTIONS:
+    -h, --help      Show this help message
+    -v, --verbose   Show detailed validation for each story
+    -q, --quiet     Only show summary (no per-file output)
+
+ARGUMENTS:
+    FILE...         Specific story files to validate
+                    If not provided, validates all ready-for-dev stories
+
+EXAMPLES:
+    # Validate all ready-for-dev stories
+    ./scripts/validate-all-stories.sh
+
+    # Validate specific files
+    ./scripts/validate-all-stories.sh docs/sprint-artifacts/story-20-13a-1.md
+
+    # Verbose output
+    ./scripts/validate-all-stories.sh -v
+
+REQUIRED FORMAT:
+    - 12 BMAD sections present
+    - At least 3 unchecked tasks
+    - Story file exists
+
+SECTIONS CHECKED:
+    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
+
+EOF
+}
+
+# Parse arguments
+VERBOSE=false
+QUIET=false
+FILES=()
+
+while [[ $# -gt 0 ]]; do
+	case $1 in
+	-h | --help)
+		show_help
+		exit 0
+		;;
+	-v | --verbose)
+		VERBOSE=true
+		shift
+		;;
+	-q | --quiet)
+		QUIET=true
+		shift
+		;;
+	*)
+		FILES+=("$1")
+		shift
+		;;
+	esac
+done
+
+# Function to validate a single story file
+validate_story() {
+	local file="$1"
+	local story_key
+	local errors=()
+
+	# Extract story key from filename
+	story_key=$(basename "$file" .md | sed 's/^story-//')
+
+	# Check file exists
+	if [ ! -f "$file" ]; then
+		echo -e "${RED}FILE MISSING${NC}"
+		return 1
+	fi
+
+	# Count sections (look for ## headings)
+	local section_count=0
+	local missing_sections=()
+
+	for section in "${REQUIRED_SECTIONS[@]}"; do
+		if grep -qi "^## .*${section}" "$file" 2>/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

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.

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.</output>
       <ask>Create story file with gap analysis? (yes/no):</ask>
 
       <check if="response == 'yes'">
-        <output>Creating story {{story_key}} with codebase gap analysis...</output>
+        <output>
-        <action>Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis</action>
+⚠️ STORY CREATION REQUIRES MANUAL WORKFLOW EXECUTION
-        <action>Parameters: story_key={{story_key}}</action>
 
-        <check if="story creation succeeded">
+**Story:** {{story_key}}
-          <output>✅ Story {{story_key}} created successfully (12/12 sections)</output>
+**Status:** File missing or incomplete
-          <action>Update file_status_icon to ✅</action>
-          <action>Mark story as validated</action>
-        </check>
 
-        <check if="story creation failed">
+**Problem:**
-          <output>❌ Story creation failed: {{story_key}}</output>
+Agents cannot invoke /create-story-with-gap-analysis workflow autonomously.
-          <action>Mark story for removal from selection</action>
+This workflow requires:
-          <action>Add to skipped_stories list with reason: "Creation failed"</action>
+- Interactive user prompts
-        </check>
+- 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.**
+        </output>
+
+        <action>Mark story for removal from selection</action>
+        <action>Add to skipped_stories list with reason: "Story creation requires manual workflow (agents cannot invoke /create-story)"</action>
+        <action>Add to manual_actions_required list: "Regenerate {{story_key}} with /create-story-with-gap-analysis"</action>
       </check>
 
       <check if="response == 'no'">
-        <output>⏭️ Skipping story {{story_key}} (file missing)</output>
+        <output>⏭️ Skipping story {{story_key}} (file missing, user declined creation)</output>
         <action>Mark story for removal from selection</action>
-        <action>Add to skipped_stories list with reason: "User declined creation"</action>
+        <action>Add to skipped_stories list with reason: "User declined story creation"</action>
       </check>
     </check>
 
@@ -214,22 +243,51 @@ This story will be SKIPPED.
         <ask>Regenerate story with codebase scan? (yes/no):</ask>
 
         <check if="response == 'yes'">
-          <output>Regenerating story {{story_key}} with gap analysis...</output>
+          <output>
-          <action>Backup existing file to {{file_path}}.backup</action>
+⚠️ STORY REGENERATION REQUIRES MANUAL WORKFLOW EXECUTION
-          <action>Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis</action>
-          <action>Parameters: story_key={{story_key}}</action>
 
-          <check if="regeneration succeeded">
+**Story:** {{story_key}}
-            <output>✅ Story {{story_key}} regenerated successfully (12/12 sections)</output>
+**Status:** File incomplete or invalid ({{sections_found}}/12 sections)
-            <action>Mark story as validated</action>
-          </check>
 
-          <check if="regeneration failed">
+**Problem:**
-            <output>❌ Regeneration failed, using backup: {{story_key}}</output>
+Agents cannot invoke /create-story-with-gap-analysis workflow autonomously.
-            <action>Restore from backup</action>
+Story regeneration requires:
-            <action>Mark story for removal with warning</action>
+- Interactive user prompts
-            <action>Add to skipped_stories list with reason: "Regeneration failed"</action>
+- Context-heavy codebase scanning
-          </check>
+- 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.**
+          </output>
+
+          <action>Mark story for removal from selection</action>
+          <action>Add to skipped_stories list with reason: "Story regeneration requires manual workflow (agents cannot invoke /create-story)"</action>
+          <action>Add to manual_actions_required list: "Regenerate {{story_key}} with /create-story-with-gap-analysis"</action>
         </check>
 
         <check if="response == 'no'">
@@ -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`