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
This commit is contained in:
Jonah Schulte
parent
7f3b62eb98
commit
5ea139d7be
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
<action>Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis</action>
|
||||
<action>Parameters: story_key={{story_key}}</action>
|
||||
<output>
|
||||
⚠️ STORY CREATION REQUIRES MANUAL WORKFLOW EXECUTION
|
||||
|
||||
<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>
|
||||
**Story:** {{story_key}}
|
||||
**Status:** File missing or incomplete
|
||||
|
||||
<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>
|
||||
**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.**
|
||||
</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>
|
||||
<action>Backup existing file to {{file_path}}.backup</action>
|
||||
<action>Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis</action>
|
||||
<action>Parameters: story_key={{story_key}}</action>
|
||||
<output>
|
||||
⚠️ STORY REGENERATION REQUIRES MANUAL WORKFLOW EXECUTION
|
||||
|
||||
<check if="regeneration succeeded">
|
||||
<output>✅ Story {{story_key}} regenerated successfully (12/12 sections)</output>
|
||||
<action>Mark story as validated</action>
|
||||
</check>
|
||||
**Story:** {{story_key}}
|
||||
**Status:** File incomplete or invalid ({{sections_found}}/12 sections)
|
||||
|
||||
<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>
|
||||
**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.**
|
||||
</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`
|
||||
|
|
|
|||
Loading…
Reference in New Issue