From 66186e1438a2ca7f9d2e14a0d8c946b57f85aba4 Mon Sep 17 00:00:00 2001 From: Caleb <46907094+rotationalphysics495@users.noreply.github.com> Date: Thu, 1 Jan 2026 11:24:21 -0600 Subject: [PATCH] feat: add epic-execute and epic-chain workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add two new implementation workflows for the Scrum Master agent: - epic-execute: Sequential story execution with isolated dev/review phases - epic-chain: Multi-epic execution with dependency detection Includes orchestration scripts and SM agent menu items. πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- scripts/epic-chain.sh | 541 +++++++++++++++ scripts/epic-execute.sh | 642 ++++++++++++++++++ src/modules/bmm/agents/sm.agent.yaml | 8 + .../epic-chain/epic-chain-launcher.md | 133 ++++ .../epic-chain/instructions.md | 322 +++++++++ .../4-implementation/epic-chain/workflow.md | 229 +++++++ .../4-implementation/epic-chain/workflow.yaml | 52 ++ .../epic-execute/INSTALLATION.md | 285 ++++++++ .../4-implementation/epic-execute/README.md | 122 ++++ .../epic-execute/config/default-config.yaml | 124 ++++ .../epic-execute/epic-execute-launcher.md | 59 ++ .../epic-execute/steps/step-01-init.md | 119 ++++ .../epic-execute/steps/step-02-dev-story.md | 162 +++++ .../epic-execute/steps/step-03-code-review.md | 255 +++++++ .../steps/step-04-generate-uat.md | 262 +++++++ .../epic-execute/steps/step-05-summary.md | 198 ++++++ .../epic-execute/templates/uat-template.md | 167 +++++ .../4-implementation/epic-execute/workflow.md | 138 ++++ 18 files changed, 3818 insertions(+) create mode 100755 scripts/epic-chain.sh create mode 100755 scripts/epic-execute.sh create mode 100644 src/modules/bmm/workflows/4-implementation/epic-chain/epic-chain-launcher.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-chain/instructions.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-chain/workflow.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-chain/workflow.yaml create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/INSTALLATION.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/README.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/config/default-config.yaml create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/epic-execute-launcher.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-01-init.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-02-dev-story.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-03-code-review.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-04-generate-uat.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-05-summary.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/templates/uat-template.md create mode 100644 src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md diff --git a/scripts/epic-chain.sh b/scripts/epic-chain.sh new file mode 100755 index 000000000..29b0ef683 --- /dev/null +++ b/scripts/epic-chain.sh @@ -0,0 +1,541 @@ +#!/bin/bash +# +# BMAD Epic Chain - Execute Multiple Epics with Analysis and Context Sharing +# +# Usage: ./epic-chain.sh [options] +# +# Examples: +# ./epic-chain.sh 36 37 38 +# ./epic-chain.sh 36 37 38 --dry-run --verbose +# ./epic-chain.sh 36 37 38 --analyze-only +# ./epic-chain.sh 36 37 38 --start-from 37 +# +# Options: +# --dry-run Show what would be executed without running +# --analyze-only Run analysis phase only, don't execute +# --verbose Show detailed output +# --start-from ID Start from a specific epic (skip earlier ones) +# --skip-done Skip epics/stories with Status: Done +# --no-handoff Don't generate context handoffs between epics +# --no-combined-uat Skip combined UAT generation at end +# + +set -e + +# ============================================================================= +# Configuration +# ============================================================================= + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" +BMAD_DIR="$PROJECT_ROOT/.bmad" + +STORIES_DIR="$PROJECT_ROOT/docs/stories" +SPRINT_ARTIFACTS_DIR="$PROJECT_ROOT/docs/sprint-artifacts" +EPICS_DIR="$PROJECT_ROOT/docs/epics" +UAT_DIR="$PROJECT_ROOT/docs/uat" +HANDOFF_DIR="$PROJECT_ROOT/docs/handoffs" + +LOG_FILE="/tmp/bmad-epic-chain-$$.log" +CHAIN_PLAN_FILE="$SPRINT_ARTIFACTS_DIR/chain-plan.yaml" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +CYAN='\033[0;36m' +BOLD='\033[1m' +NC='\033[0m' # No Color + +# ============================================================================= +# Helper Functions +# ============================================================================= + +log() { + echo -e "${BLUE}[CHAIN]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE" +} + +log_success() { + echo -e "${GREEN}[βœ“]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] [SUCCESS] $1" >> "$LOG_FILE" +} + +log_error() { + echo -e "${RED}[βœ—]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] $1" >> "$LOG_FILE" +} + +log_warn() { + echo -e "${YELLOW}[!]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] [WARN] $1" >> "$LOG_FILE" +} + +log_header() { + echo "" + echo -e "${CYAN}${BOLD}═══════════════════════════════════════════════════════════${NC}" + echo -e "${CYAN}${BOLD} $1${NC}" + echo -e "${CYAN}${BOLD}═══════════════════════════════════════════════════════════${NC}" + echo "" +} + +log_section() { + echo "" + echo -e "${BOLD}───────────────────────────────────────────────────────────${NC}" + echo -e "${BOLD} $1${NC}" + echo -e "${BOLD}───────────────────────────────────────────────────────────${NC}" +} + +# ============================================================================= +# Argument Parsing +# ============================================================================= + +EPIC_IDS=() +DRY_RUN=false +ANALYZE_ONLY=false +VERBOSE=false +START_FROM="" +SKIP_DONE=false +NO_HANDOFF=false +NO_COMBINED_UAT=false + +while [[ $# -gt 0 ]]; do + case $1 in + --dry-run) + DRY_RUN=true + shift + ;; + --analyze-only) + ANALYZE_ONLY=true + shift + ;; + --verbose) + VERBOSE=true + shift + ;; + --start-from) + START_FROM="$2" + shift 2 + ;; + --skip-done) + SKIP_DONE=true + shift + ;; + --no-handoff) + NO_HANDOFF=true + shift + ;; + --no-combined-uat) + NO_COMBINED_UAT=true + shift + ;; + -*) + echo "Unknown option: $1" + exit 1 + ;; + *) + EPIC_IDS+=("$1") + shift + ;; + esac +done + +if [ ${#EPIC_IDS[@]} -eq 0 ]; then + echo "Usage: $0 [epic-id...] [options]" + echo "" + echo "Examples:" + echo " $0 36 37 38 # Execute epics 36, 37, 38 in order" + echo " $0 36 37 38 --dry-run # Show what would happen" + echo " $0 36 37 38 --analyze-only # Just analyze, don't execute" + echo " $0 36 37 38 --start-from 37 # Resume from epic 37" + echo "" + echo "Options:" + echo " --dry-run Show execution plan without running" + echo " --analyze-only Analyze dependencies only" + echo " --verbose Detailed output" + echo " --start-from ID Start from specific epic" + echo " --skip-done Skip completed stories" + echo " --no-handoff Skip context handoffs between epics" + echo " --no-combined-uat Skip combined UAT at end" + exit 1 +fi + +# ============================================================================= +# Setup +# ============================================================================= + +log_header "EPIC CHAIN EXECUTION" +log "Epics to chain: ${EPIC_IDS[*]}" +log "Project root: $PROJECT_ROOT" + +# Ensure directories exist +mkdir -p "$UAT_DIR" +mkdir -p "$HANDOFF_DIR" +mkdir -p "$SPRINT_ARTIFACTS_DIR" + +# ============================================================================= +# Phase 1: Validate Epics +# ============================================================================= + +log_section "Phase 1: Validating Epics" + +# Bash 3.2 compatible: use indexed arrays with matching indices +EPIC_FILES_LIST=() +EPIC_STORIES_LIST=() +EPIC_DEPS_LIST=() + +for i in "${!EPIC_IDS[@]}"; do + epic_id="${EPIC_IDS[$i]}" + + # Find epic file + epic_file="" + for pattern in "epic-${epic_id}.md" "epic-${epic_id}-"*.md "epic-0${epic_id}-"*.md "${epic_id}.md"; do + found=$(find "$EPICS_DIR" -name "$pattern" 2>/dev/null | head -1) + if [ -n "$found" ]; then + epic_file="$found" + break + fi + done + + if [ -z "$epic_file" ] || [ ! -f "$epic_file" ]; then + log_error "Epic $epic_id: File not found in $EPICS_DIR" + exit 1 + fi + + EPIC_FILES_LIST[$i]="$epic_file" + log_success "Epic $epic_id: Found $(basename "$epic_file")" + + # Find stories for this epic + story_count=0 + for search_dir in "$STORIES_DIR" "$SPRINT_ARTIFACTS_DIR"; do + if [ -d "$search_dir" ]; then + count=$(find "$search_dir" -name "${epic_id}-*-*.md" 2>/dev/null | wc -l) + story_count=$((story_count + count)) + fi + done + + if [ "$story_count" -eq 0 ]; then + log_warn "Epic $epic_id: No story files found (will check epic file for story definitions)" + else + log "Epic $epic_id: Found $story_count story files" + fi + + EPIC_STORIES_LIST[$i]=$story_count +done + +log_success "All ${#EPIC_IDS[@]} epics validated" + +# ============================================================================= +# Phase 2: Analyze Dependencies +# ============================================================================= + +log_section "Phase 2: Analyzing Dependencies" + +# Simple dependency detection: check for ## Dependencies section in epic files +for i in "${!EPIC_IDS[@]}"; do + epic_id="${EPIC_IDS[$i]}" + epic_file="${EPIC_FILES_LIST[$i]}" + + # Look for Dependencies section + deps=$(grep -A 10 "^## Dependencies" "$epic_file" 2>/dev/null | grep -oE "Epic [0-9]+" | grep -oE "[0-9]+" || true) + + if [ -n "$deps" ]; then + EPIC_DEPS_LIST[$i]="$deps" + log "Epic $epic_id depends on: $deps" + else + EPIC_DEPS_LIST[$i]="" + log "Epic $epic_id: No explicit dependencies" + fi +done + +# ============================================================================= +# Phase 3: Determine Execution Order +# ============================================================================= + +log_section "Phase 3: Determining Execution Order" + +# For now, use order as provided (user presumably knows the right order) +# Future enhancement: topological sort based on dependencies + +EXECUTION_ORDER=("${EPIC_IDS[@]}") + +log "Execution order: ${EXECUTION_ORDER[*]}" + +# ============================================================================= +# Phase 4: Generate Chain Plan +# ============================================================================= + +log_section "Phase 4: Generating Chain Plan" + +cat > "$CHAIN_PLAN_FILE" << EOF +# Epic Chain Execution Plan +# Generated: $(date '+%Y-%m-%d %H:%M:%S') + +epics: [${EPIC_IDS[*]}] +total_epics: ${#EPIC_IDS[@]} + +execution_order: +EOF + +total_stories=0 +for i in "${!EXECUTION_ORDER[@]}"; do + epic_id="${EXECUTION_ORDER[$i]}" + story_count=${EPIC_STORIES_LIST[$i]} + total_stories=$((total_stories + story_count)) + deps="${EPIC_DEPS_LIST[$i]}" + + cat >> "$CHAIN_PLAN_FILE" << EOF + - epic: $epic_id + file: $(basename "${EPIC_FILES_LIST[$i]}") + stories: $story_count + dependencies: [$deps] +EOF +done + +cat >> "$CHAIN_PLAN_FILE" << EOF + +total_stories: $total_stories + +options: + dry_run: $DRY_RUN + skip_done: $SKIP_DONE + context_handoff: $([ "$NO_HANDOFF" = true ] && echo "false" || echo "true") + combined_uat: $([ "$NO_COMBINED_UAT" = true ] && echo "false" || echo "true") +EOF + +log_success "Chain plan saved to: $CHAIN_PLAN_FILE" + +# ============================================================================= +# Display Summary +# ============================================================================= + +log_header "CHAIN EXECUTION PLAN" + +echo " Epics: ${EPIC_IDS[*]}" +echo " Total Stories: $total_stories" +echo " Dry Run: $DRY_RUN" +echo " Skip Done: $SKIP_DONE" +echo "" +echo " Execution Order:" +for i in "${!EXECUTION_ORDER[@]}"; do + epic_id="${EXECUTION_ORDER[$i]}" + deps="${EPIC_DEPS_LIST[$i]}" + echo " $((i+1)). Epic $epic_id (${EPIC_STORIES_LIST[$i]} stories) ${deps:+← depends on: $deps}" +done +echo "" + +if [ "$ANALYZE_ONLY" = true ]; then + log_success "Analysis complete (--analyze-only specified)" + echo "" + echo "To execute this chain, run:" + echo " $0 ${EPIC_IDS[*]}" + echo "" + exit 0 +fi + +# ============================================================================= +# Phase 5: Execute Chain +# ============================================================================= + +log_header "EXECUTING EPIC CHAIN" + +COMPLETED_EPICS=0 +FAILED_EPICS=0 +SKIPPED_EPICS=0 +START_TIME=$(date +%s) +STARTED=false +PREVIOUS_EPIC="" +PREVIOUS_IDX=-1 + +for current_idx in "${!EXECUTION_ORDER[@]}"; do + epic_id="${EXECUTION_ORDER[$current_idx]}" + # Handle --start-from + if [ -n "$START_FROM" ] && [ "$STARTED" = false ]; then + if [ "$epic_id" = "$START_FROM" ]; then + STARTED=true + else + log_warn "Skipping Epic $epic_id (waiting for --start-from $START_FROM)" + ((SKIPPED_EPICS++)) + continue + fi + fi + + log_section "Executing Epic $epic_id" + + # Generate context handoff from previous epic + if [ -n "$PREVIOUS_EPIC" ] && [ "$NO_HANDOFF" = false ]; then + handoff_file="$HANDOFF_DIR/epic-${PREVIOUS_EPIC}-to-${epic_id}-handoff.md" + if [ -f "$handoff_file" ]; then + log "Loading context handoff from Epic $PREVIOUS_EPIC" + fi + fi + + # Build epic-execute command + exec_cmd="$SCRIPT_DIR/epic-execute.sh $epic_id" + + if [ "$DRY_RUN" = true ]; then + exec_cmd="$exec_cmd --dry-run" + fi + + if [ "$SKIP_DONE" = true ]; then + exec_cmd="$exec_cmd --skip-done" + fi + + if [ "$VERBOSE" = true ]; then + exec_cmd="$exec_cmd --verbose" + fi + + log "Running: $exec_cmd" + + # Execute epic + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would execute: $exec_cmd" + ((COMPLETED_EPICS++)) + else + if $exec_cmd; then + log_success "Epic $epic_id completed" + ((COMPLETED_EPICS++)) + + # Generate handoff for next epic + if [ "$NO_HANDOFF" = false ]; then + next_idx=$((current_idx + 1)) + + if [ $next_idx -lt ${#EXECUTION_ORDER[@]} ]; then + next_epic="${EXECUTION_ORDER[$next_idx]}" + handoff_file="$HANDOFF_DIR/epic-${epic_id}-to-${next_epic}-handoff.md" + + log "Generating context handoff: Epic $epic_id β†’ Epic $next_epic" + + story_count=${EPIC_STORIES_LIST[$current_idx]} + cat > "$handoff_file" << EOF +# Epic $epic_id β†’ Epic $next_epic Handoff + +## Generated +$(date '+%Y-%m-%d %H:%M:%S') + +## Epic $epic_id Completion Summary + +Epic $epic_id has been completed. Key context for Epic $next_epic: + +### Patterns Established +- Review code changes in Epic $epic_id for established patterns +- Check \`docs/stories/${epic_id}-*\` for implementation details + +### Files Modified +$(git diff --name-only HEAD~${story_count} HEAD 2>/dev/null | head -20 || echo "Unable to determine - check git log") + +### Notes for Next Epic +- Continue following patterns established in this epic +- Reference UAT document at \`docs/uat/epic-${epic_id}-uat.md\` for context + +EOF + log_success "Handoff saved to: $handoff_file" + fi + fi + else + log_error "Epic $epic_id failed" + ((FAILED_EPICS++)) + + # Ask whether to continue or abort + echo "" + echo "Epic $epic_id failed. Continue with remaining epics? (y/n)" + read -r continue_choice + if [ "$continue_choice" != "y" ]; then + log_error "Chain execution aborted by user" + break + fi + fi + fi + + PREVIOUS_EPIC="$epic_id" + PREVIOUS_IDX=$current_idx +done + +# ============================================================================= +# Phase 6: Generate Combined UAT +# ============================================================================= + +if [ "$NO_COMBINED_UAT" = false ] && [ "$DRY_RUN" = false ] && [ $COMPLETED_EPICS -gt 1 ]; then + log_section "Generating Combined UAT Document" + + combined_uat_file="$UAT_DIR/chain-${EPIC_IDS[*]// /-}-uat.md" + + cat > "$combined_uat_file" << EOF +# Combined UAT: Epics ${EPIC_IDS[*]} + +## Generated +$(date '+%Y-%m-%d %H:%M:%S') + +## Overview + +This document combines User Acceptance Testing for epics: ${EPIC_IDS[*]} + +## Individual Epic UATs + +EOF + + for epic_id in "${EPIC_IDS[@]}"; do + uat_file="$UAT_DIR/epic-${epic_id}-uat.md" + if [ -f "$uat_file" ]; then + echo "### Epic $epic_id" >> "$combined_uat_file" + echo "" >> "$combined_uat_file" + echo "See: [epic-${epic_id}-uat.md](epic-${epic_id}-uat.md)" >> "$combined_uat_file" + echo "" >> "$combined_uat_file" + fi + done + + cat >> "$combined_uat_file" << EOF + +## Cross-Epic Integration Testing + +After individual epic testing, verify these cross-epic scenarios: + +1. [ ] Features from earlier epics still work after later epic changes +2. [ ] Data flows correctly between features from different epics +3. [ ] No regression in previously tested functionality + +## Sign-off + +| Epic | Tester | Date | Status | +|------|--------|------|--------| +EOF + + for epic_id in "${EPIC_IDS[@]}"; do + echo "| $epic_id | | | Pending |" >> "$combined_uat_file" + done + + log_success "Combined UAT saved to: $combined_uat_file" +fi + +# ============================================================================= +# Summary +# ============================================================================= + +END_TIME=$(date +%s) +DURATION=$((END_TIME - START_TIME)) + +log_header "EPIC CHAIN COMPLETE" + +echo " Epics in Chain: ${#EPIC_IDS[@]}" +echo " Completed: $COMPLETED_EPICS" +echo " Failed: $FAILED_EPICS" +echo " Skipped: $SKIPPED_EPICS" +echo " Duration: ${DURATION}s" +echo "" +echo " Artifacts:" +echo " - Chain Plan: $CHAIN_PLAN_FILE" +echo " - Handoffs: $HANDOFF_DIR/" +echo " - UAT Documents: $UAT_DIR/" +echo " - Log: $LOG_FILE" +echo "" + +if [ $FAILED_EPICS -gt 0 ]; then + log_warn "$FAILED_EPICS epic(s) failed - check log for details" + exit 1 +fi + +log_success "All epics completed successfully" +echo "" +echo "Next step: Review UAT documents and run manual testing" +echo "" diff --git a/scripts/epic-execute.sh b/scripts/epic-execute.sh new file mode 100755 index 000000000..ea90acac3 --- /dev/null +++ b/scripts/epic-execute.sh @@ -0,0 +1,642 @@ +#!/bin/bash +# +# BMAD Epic Execute - Automated Story Execution with Context Isolation +# +# Usage: ./epic-execute.sh [options] +# +# Options: +# --dry-run Show what would be executed without running +# --skip-review Skip code review phase (not recommended) +# --no-commit Stage changes but don't commit +# --parallel Run independent stories in parallel (experimental) +# --verbose Show detailed output +# --start-from ID Start from a specific story (e.g., 31-2) +# --skip-done Skip stories with Status: Done +# + +set -e + +# ============================================================================= +# Configuration +# ============================================================================= + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" +BMAD_DIR="$PROJECT_ROOT/bmad" + +STORIES_DIR="$PROJECT_ROOT/docs/stories" +SPRINT_ARTIFACTS_DIR="$PROJECT_ROOT/docs/sprint-artifacts" +SPRINTS_DIR="$PROJECT_ROOT/docs/sprints" +EPICS_DIR="$PROJECT_ROOT/docs/epics" +UAT_DIR="$PROJECT_ROOT/docs/uat" + +LOG_FILE="/tmp/bmad-epic-execute-$$.log" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# ============================================================================= +# Helper Functions +# ============================================================================= + +log() { + echo -e "${BLUE}[BMAD]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE" +} + +log_success() { + echo -e "${GREEN}[βœ“]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] [SUCCESS] $1" >> "$LOG_FILE" +} + +log_error() { + echo -e "${RED}[βœ—]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] $1" >> "$LOG_FILE" +} + +log_warn() { + echo -e "${YELLOW}[!]${NC} $1" + echo "[$(date '+%Y-%m-%d %H:%M:%S')] [WARN] $1" >> "$LOG_FILE" +} + +# ============================================================================= +# Argument Parsing +# ============================================================================= + +EPIC_ID="" +DRY_RUN=false +SKIP_REVIEW=false +NO_COMMIT=false +PARALLEL=false +VERBOSE=false +START_FROM="" +SKIP_DONE=false + +while [[ $# -gt 0 ]]; do + case $1 in + --dry-run) + DRY_RUN=true + shift + ;; + --skip-review) + SKIP_REVIEW=true + shift + ;; + --no-commit) + NO_COMMIT=true + shift + ;; + --parallel) + PARALLEL=true + shift + ;; + --verbose) + VERBOSE=true + shift + ;; + --start-from) + START_FROM="$2" + shift 2 + ;; + --skip-done) + SKIP_DONE=true + shift + ;; + -*) + echo "Unknown option: $1" + exit 1 + ;; + *) + EPIC_ID="$1" + shift + ;; + esac +done + +if [ -z "$EPIC_ID" ]; then + echo "Usage: $0 [options]" + echo "" + echo "Options:" + echo " --dry-run Show what would be executed" + echo " --skip-review Skip code review phase" + echo " --no-commit Don't commit after stories" + echo " --parallel Parallel execution (experimental)" + echo " --verbose Detailed output" + echo " --start-from ID Start from a specific story (e.g., 31-2)" + echo " --skip-done Skip stories with Status: Done" + exit 1 +fi + +# ============================================================================= +# Setup +# ============================================================================= + +log "Starting epic execution for: $EPIC_ID" +log "Project root: $PROJECT_ROOT" + +# Ensure directories exist +mkdir -p "$UAT_DIR" +mkdir -p "$SPRINTS_DIR" + +# Find epic file (supports both epic-39-*.md and epic-039-*.md formats) +EPIC_FILE="" +# Pad epic ID with leading zero for 3-digit format (e.g., 40 -> 040) +EPIC_ID_PADDED=$(printf "%03d" "$EPIC_ID" 2>/dev/null || echo "$EPIC_ID") +for pattern in "epic-${EPIC_ID}.md" "epic-${EPIC_ID}-"*.md "epic-${EPIC_ID_PADDED}-"*.md "epic-0${EPIC_ID}-"*.md "${EPIC_ID}.md"; do + found=$(find "$EPICS_DIR" -name "$pattern" 2>/dev/null | head -1) + if [ -n "$found" ]; then + EPIC_FILE="$found" + break + fi +done + +if [ -z "$EPIC_FILE" ] || [ ! -f "$EPIC_FILE" ]; then + log_error "Epic file not found for: $EPIC_ID" + log_error "Searched in: $EPICS_DIR" + exit 1 +fi + +log "Found epic file: $EPIC_FILE" + +# ============================================================================= +# Discover Stories +# ============================================================================= + +log "Discovering stories..." + +# Search multiple locations for story files +STORY_LOCATIONS=("$STORIES_DIR" "$SPRINT_ARTIFACTS_DIR" "$SPRINTS_DIR") +STORIES=() + +for search_dir in "${STORY_LOCATIONS[@]}"; do + if [ ! -d "$search_dir" ]; then + continue + fi + + # Method 1: Stories that reference this epic in content + while IFS= read -r -d '' file; do + if [[ ! " ${STORIES[*]} " =~ " ${file} " ]]; then + STORIES+=("$file") + fi + done < <(grep -l -Z "Epic.*:.*${EPIC_ID}\|epic-${EPIC_ID}\|Epic.*${EPIC_ID}" "$search_dir"/*.md 2>/dev/null || true) + + # Method 2: {EpicNumber}-{StoryNumber}-{description}.md (e.g., 1-1-user-registration.md) + while IFS= read -r -d '' file; do + if [[ ! " ${STORIES[*]} " =~ " ${file} " ]]; then + STORIES+=("$file") + fi + done < <(find "$search_dir" -name "${EPIC_ID}-*-*.md" -print0 2>/dev/null || true) + + # Method 3: story-{epic}.{seq}-*.md (BMAD standard) + while IFS= read -r -d '' file; do + if [[ ! " ${STORIES[*]} " =~ " ${file} " ]]; then + STORIES+=("$file") + fi + done < <(find "$search_dir" -name "story-${EPIC_ID}.*-*.md" -print0 2>/dev/null || true) + + # Method 4: story-{epic}-*.md (BMAD alternate) + while IFS= read -r -d '' file; do + if [[ ! " ${STORIES[*]} " =~ " ${file} " ]]; then + STORIES+=("$file") + fi + done < <(find "$search_dir" -name "story-${EPIC_ID}-*.md" -print0 2>/dev/null || true) +done + +if [ ${#STORIES[@]} -eq 0 ]; then + log_error "No stories found for epic: $EPIC_ID" + log_error "Searched in: ${STORY_LOCATIONS[*]}" + log_error "Looking for:" + log_error " - Files containing 'Epic: $EPIC_ID'" + log_error " - Files named: ${EPIC_ID}-*-*.md (e.g., ${EPIC_ID}-1-description.md)" + log_error " - Files named: story-${EPIC_ID}.*.md or story-${EPIC_ID}-*.md" + exit 1 +fi + +log "Found ${#STORIES[@]} stories" + +# Sort stories for consistent execution order +IFS=$'\n' STORIES=($(sort -V <<<"${STORIES[*]}")); unset IFS + +# Show which directories stories came from +if [ "$VERBOSE" = true ]; then + for story in "${STORIES[@]}"; do + echo " - $story" + done +fi + +# ============================================================================= +# Execution Functions +# ============================================================================= + +execute_dev_phase() { + local story_file="$1" + local story_id=$(basename "$story_file" .md) + + log ">>> DEV PHASE: $story_id" + + local story_contents=$(cat "$story_file") + + # Build the dev prompt + local dev_prompt="You are the Dev agent executing a BMAD story implementation. + +## Your Task + +Implement story: $story_id + +## Story Specification + + +$story_contents + + +## Implementation Requirements + +1. Read the story file completely before writing any code +2. Follow existing patterns in the codebase +3. Implement ALL acceptance criteria +4. Write tests for each criterion +5. Run tests and fix any failures +6. Update documentation as needed + +## When Complete + +1. Update the story file: + - Change Status to: In Review + - Fill in the Dev Agent Record section with: + - Implementation Summary + - Files Created/Modified + - Key Decisions + - Tests Added + - Test Results (summary of test run) + - Notes for Reviewer + - Acceptance Criteria Status (checklist with file references) + +2. Stage changes: git add -A + +3. Output exactly: IMPLEMENTATION COMPLETE: $story_id + +If blocked, output: IMPLEMENTATION BLOCKED: $story_id - [reason]" + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would execute dev phase for $story_id" + return 0 + fi + + # Execute in isolated context + local result + result=$(claude --dangerously-skip-permissions -p "$dev_prompt" 2>&1) || true + + echo "$result" >> "$LOG_FILE" + + if echo "$result" | grep -q "IMPLEMENTATION COMPLETE"; then + log_success "Dev phase complete: $story_id" + return 0 + elif echo "$result" | grep -q "IMPLEMENTATION BLOCKED"; then + log_error "Dev phase blocked: $story_id" + echo "$result" | grep "IMPLEMENTATION BLOCKED" + return 1 + else + log_error "Dev phase did not complete cleanly: $story_id" + return 1 + fi +} + +execute_review_phase() { + local story_file="$1" + local story_id=$(basename "$story_file" .md) + + log ">>> REVIEW PHASE: $story_id (fresh context)" + + local story_contents=$(cat "$story_file") + + # Build the review prompt with severity-based fix logic + local review_prompt="You are a Senior Code Reviewer performing a BMAD code review. + +## Your Task + +Review the implementation of story: $story_id + +You are seeing this code for the first time. You have no knowledge of the implementation process. + +## Story Specification and Dev Context + + +$story_contents + + +The story file contains: +- Acceptance criteria (what must be verified) +- Dev Agent Record (implementation notes from the developer) +- Notes for Reviewer (areas of concern flagged by dev) + +## Review Process + +1. Run: git diff --staged +2. Verify each acceptance criterion is implemented and tested +3. Check code quality, security, and patterns +4. Collect and categorize all issues by severity + +## Issue Severity Definitions + +- **HIGH**: Security vulnerabilities, missing error handling, no tests for new code, N+1 queries, exposed credentials +- **MEDIUM**: Pattern violations, missing edge cases, hardcoded config values, code duplication +- **LOW**: Naming inconsistencies, minor style issues, missing comments + +## Issue Fix Policy (IMPORTANT) + +Apply this logic after collecting all issues: + +\`\`\` +1. Always fix ALL HIGH severity issues +2. If TOTAL issues > 5, also fix ALL MEDIUM severity issues +3. LOW severity issues: document only, do NOT fix +\`\`\` + +## Review Checklist + +### Acceptance Criteria +For each criterion: implemented? tested? matches requirement? + +### Code Quality +- Follows existing patterns (MEDIUM) +- No security issues (HIGH) +- Error handling appropriate (HIGH) +- Tests exist and meaningful (HIGH) +- No hardcoded secrets (HIGH) + +## After Review + +1. Compile issues found with severity +2. Count: HIGH=?, MEDIUM=?, LOW=?, TOTAL=? +3. Apply fix policy: fix HIGH always, fix MEDIUM if total > 5 +4. For each fix: make change, run tests, verify +5. Stage any fixes: git add -A + +## Update Story File + +Add Code Review Record section: + +\`\`\`markdown +## Code Review Record + +**Reviewer**: Code Review Agent +**Date**: $(date '+%Y-%m-%d %H:%M') + +### Issues Found +| # | Description | Severity | Status | +|---|-------------|----------|--------| + +**Totals**: X HIGH, Y MEDIUM, Z LOW + +### Fixes Applied +[List what was fixed] + +### Remaining Issues +[Low severity items for future cleanup] + +### Final Status +Approved / Approved with fixes / Rejected +\`\`\` + +## Completion + +If PASSED (no unfixed HIGH/MEDIUM issues): +1. Update story Status to: Done +2. Output: REVIEW PASSED: $story_id + or: REVIEW PASSED WITH FIXES: $story_id - Fixed N issues + +If FAILED (unfixable issues or missing acceptance criteria): +1. Update story Status to: Blocked +2. Output: REVIEW FAILED: $story_id - [reason]" + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would execute review phase for $story_id" + return 0 + fi + + # Execute in isolated context + local result + result=$(claude --dangerously-skip-permissions -p "$review_prompt" 2>&1) || true + + echo "$result" >> "$LOG_FILE" + + if echo "$result" | grep -q "REVIEW PASSED"; then + log_success "Review passed: $story_id" + return 0 + elif echo "$result" | grep -q "REVIEW FAILED"; then + log_error "Review failed: $story_id" + echo "$result" | grep "REVIEW FAILED" + return 1 + else + log_warn "Review did not complete cleanly: $story_id" + return 1 + fi +} + +commit_story() { + local story_id="$1" + + if [ "$NO_COMMIT" = true ]; then + log "Skipping commit (--no-commit)" + return 0 + fi + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would commit: feat(epic-$EPIC_ID): complete $story_id" + return 0 + fi + + git add -A + git commit -m "feat(epic-$EPIC_ID): complete $story_id" || { + log_warn "Nothing to commit for $story_id" + } + + log_success "Committed: $story_id" +} + +generate_uat() { + log ">>> GENERATING UAT DOCUMENT (fresh context)" + + local epic_contents=$(cat "$EPIC_FILE") + local all_stories="" + + for story_file in "${STORIES[@]}"; do + local story_id=$(basename "$story_file" .md) + all_stories+=" + +$(cat "$story_file") + +" + done + + local uat_prompt="You are a QA Specialist creating a User Acceptance Testing document. + +## Your Task + +Generate a UAT document for Epic: $EPIC_ID + +## Epic Definition + + +$epic_contents + + +## Completed Stories + +$all_stories + +## Requirements + +Create a UAT document for NON-TECHNICAL users with: + +1. **Overview**: What was built (plain language) +2. **Prerequisites**: Test environment, accounts, setup +3. **Test Scenarios**: Step-by-step instructions with expected results +4. **Success Criteria**: Checklist of what must work +5. **Sign-off Section**: For human approval + +Write for someone who can use the software but doesn't know how it's built. + +## Output + +Save to: $UAT_DIR/epic-${EPIC_ID}-uat.md + +When complete, output: UAT GENERATED: $UAT_DIR/epic-${EPIC_ID}-uat.md" + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would generate UAT document" + return 0 + fi + + local result + result=$(claude --dangerously-skip-permissions -p "$uat_prompt" 2>&1) || true + + echo "$result" >> "$LOG_FILE" + + if echo "$result" | grep -q "UAT GENERATED"; then + log_success "UAT document generated" + else + log_warn "UAT generation may not have completed cleanly" + fi + + # Commit UAT document + if [ "$NO_COMMIT" = false ]; then + git add "$UAT_DIR/epic-${EPIC_ID}-uat.md" 2>/dev/null || true + git commit -m "docs(epic-$EPIC_ID): add UAT document" 2>/dev/null || true + fi +} + +# ============================================================================= +# Main Execution Loop +# ============================================================================= + +log "==========================================" +log "Starting execution of ${#STORIES[@]} stories" +log "==========================================" + +COMPLETED=0 +FAILED=0 +SKIPPED=0 +START_TIME=$(date +%s) +STARTED=false + +for story_file in "${STORIES[@]}"; do + story_id=$(basename "$story_file" .md) + + # --start-from: Skip stories until we reach the specified one + if [ -n "$START_FROM" ] && [ "$STARTED" = false ]; then + if [[ "$story_id" == *"$START_FROM"* ]]; then + STARTED=true + else + log_warn "Skipping $story_id (waiting for $START_FROM)" + ((SKIPPED++)) + continue + fi + fi + + # --skip-done: Skip stories with Status: Done + if [ "$SKIP_DONE" = true ]; then + if grep -q "^Status:.*Done" "$story_file" 2>/dev/null; then + log_warn "Skipping $story_id (Status: Done)" + ((SKIPPED++)) + continue + fi + fi + + echo "" + log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + log "Story: $story_id" + log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + + # DEV PHASE (Context 1) + if ! execute_dev_phase "$story_file"; then + log_error "Dev phase failed for $story_id" + ((FAILED++)) + continue + fi + + # REVIEW PHASE (Context 2 - Fresh) + if [ "$SKIP_REVIEW" = false ]; then + if ! execute_review_phase "$story_file"; then + log_error "Review phase failed for $story_id" + ((FAILED++)) + continue + fi + fi + + # COMMIT + commit_story "$story_id" + + ((COMPLETED++)) + log_success "Story complete: $story_id ($COMPLETED/${#STORIES[@]})" +done + +# ============================================================================= +# UAT Generation (Context 3 - Fresh) +# ============================================================================= + +echo "" +log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +log "UAT Document Generation" +log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + +generate_uat + +# ============================================================================= +# Summary +# ============================================================================= + +END_TIME=$(date +%s) +DURATION=$((END_TIME - START_TIME)) + +echo "" +log "==========================================" +log "EPIC EXECUTION COMPLETE" +log "==========================================" +echo "" +echo " Epic: $EPIC_ID" +echo " Duration: ${DURATION}s" +echo " Stories: ${#STORIES[@]}" +echo " Skipped: $SKIPPED" +echo " Completed: $COMPLETED" +echo " Failed: $FAILED" +echo "" +echo " Deliverables:" +echo " - Stories: $STORIES_DIR/" +echo " - UAT: $UAT_DIR/epic-${EPIC_ID}-uat.md" +echo " - Log: $LOG_FILE" +echo "" + +if [ $FAILED -gt 0 ]; then + log_warn "$FAILED stories failed - check log for details" + exit 1 +fi + +log_success "All stories completed successfully" +echo "" +echo "Next step: Run UAT document with a human tester" +echo "" diff --git a/src/modules/bmm/agents/sm.agent.yaml b/src/modules/bmm/agents/sm.agent.yaml index aebba89a6..3d414d8a8 100644 --- a/src/modules/bmm/agents/sm.agent.yaml +++ b/src/modules/bmm/agents/sm.agent.yaml @@ -45,3 +45,11 @@ agent: - trigger: CC or fuzzy match on correct-course workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml" description: "[CC] Execute correct-course task (When implementation is off-track)" + + - trigger: EE or fuzzy match on epic-execute + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/epic-execute/workflow.md" + description: "[EE] Execute all stories in an epic sequentially with isolated dev/review phases and UAT generation" + + - trigger: EC or fuzzy match on epic-chain + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/epic-chain/workflow.yaml" + description: "[EC] Analyze and execute multiple epics in sequence with dependency detection" diff --git a/src/modules/bmm/workflows/4-implementation/epic-chain/epic-chain-launcher.md b/src/modules/bmm/workflows/4-implementation/epic-chain/epic-chain-launcher.md new file mode 100644 index 000000000..d6a388ece --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-chain/epic-chain-launcher.md @@ -0,0 +1,133 @@ +# Epic Chain Launcher + +This workflow orchestrates the execution of multiple epics in sequence with cross-epic analysis and context sharing. + +## Instructions + +When the user invokes `*epic-chain`, follow these steps: + +### Step 1: Gather Epic IDs + +Ask the user which epics to chain. Accept input in any of these formats: +- Space-separated: `36 37 38` +- Comma-separated: `36, 37, 38` +- Range: `36-38` (expands to 36, 37, 38) + +Validate each epic ID: +1. Check that epic file exists at `docs/epics/epic-{id}-*.md` +2. Check that stories exist for each epic + +### Step 2: Run Analysis Phase + +Before execution, analyze all epics to understand: + +1. **Load all epic files** - Read the full content of each epic +2. **Load all story files** - Read stories for each epic +3. **Detect dependencies**: + - Look for explicit `## Dependencies` sections in epic files + - Scan for shared patterns (database tables, API endpoints, components) + - Identify stories that reference other epics' outputs + +4. **Build execution plan**: + - Determine optimal epic order (respecting dependencies) + - Identify cross-cutting concerns + - Flag risk areas + - Note parallel execution opportunities within epics + +### Step 3: Present Chain Plan + +Display the analysis results to the user: + +``` +═══════════════════════════════════════════════════════════ + EPIC CHAIN ANALYSIS +═══════════════════════════════════════════════════════════ + +Epics to Execute: 36, 37, 38 +Total Stories: 24 + +EXECUTION ORDER +─────────────────────────────────────────────────────────── +1. Epic 36: Content Management (8 stories) + Dependencies: None + Complexity: Medium + +2. Epic 37: Search Enhancement (3 stories) + Dependencies: Epic 36 (uses content patterns) + Complexity: Low + +3. Epic 38: Security Hardening (4 stories) + Dependencies: Epic 36, 37 + Complexity: High + +CROSS-CUTTING CONCERNS +─────────────────────────────────────────────────────────── +β€’ Database migrations span epics 36, 37 +β€’ API versioning affects epics 36, 38 + +RISK AREAS +─────────────────────────────────────────────────────────── +β€’ Story 38-3: Complex search integration + Mitigation: Comprehensive test coverage + +═══════════════════════════════════════════════════════════ +``` + +### Step 4: Get User Approval + +Ask the user to confirm: +- **Approve**: Proceed with execution +- **Modify**: Reorder epics or exclude some +- **Analyze Only**: Save plan but don't execute + +### Step 5: Provide Execution Command + +If approved, provide the shell command: + +**Dry run (recommended first):** +```bash +./.bmad/scripts/epic-chain.sh 36 37 38 --dry-run --verbose +``` + +**Full execution:** +```bash +./.bmad/scripts/epic-chain.sh 36 37 38 +``` + +**Resume from specific epic:** +```bash +./.bmad/scripts/epic-chain.sh 36 37 38 --start-from 37 +``` + +### Step 6: Explain Execution Flow + +The chain execution will: + +1. **For each epic in order:** + - Load context handoff from previous epic (if any) + - Execute all stories via `epic-execute.sh` + - Generate epic completion summary + - Create context handoff for next epic + +2. **After all epics complete:** + - Generate combined UAT document + - Update `sprint-status.yaml` + - Display chain execution summary + +### Context Handoff + +Between epics, the workflow generates a handoff document containing: +- Patterns established (coding conventions, architectural decisions) +- Key decisions made during implementation +- Gotchas and lessons learned +- Files to reference for the next epic + +This ensures each subsequent epic benefits from learnings without context window pollution. + +## Analysis Depth Options + +- **quick**: Basic dependency check, file existence validation +- **standard**: Full epic/story analysis, pattern detection, risk assessment +- **thorough**: Deep code analysis, test coverage review, performance considerations + +Set via: `./.bmad/scripts/epic-chain.sh 36 37 38 --analysis thorough` diff --git a/src/modules/bmm/workflows/4-implementation/epic-chain/instructions.md b/src/modules/bmm/workflows/4-implementation/epic-chain/instructions.md new file mode 100644 index 000000000..9c428b665 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-chain/instructions.md @@ -0,0 +1,322 @@ +# Epic Chain - Analysis and Execution Instructions + +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/epic-chain/workflow.yaml + +## Overview + +This workflow analyzes multiple epics to understand their relationships, then chains their execution with context sharing between epics. + + + + +Communicate in {communication_language} with {user_name} +Ask which epics to chain if not already provided + +**Accept input formats:** +- Space-separated: `36 37 38` +- Comma-separated: `36, 37, 38` +- Range notation: `36-38` (expand to individual IDs) +- Mixed: `36-38, 40` (expand ranges, keep individuals) + +**For each epic ID, validate:** +1. Epic file exists at `{epics_location}/epic-{id}*.md` +2. At least one story exists for the epic in `{stories_location}/` + +**Output:** List of validated epic IDs in order provided + +Report which epic IDs failed validation and ask user to correct + + + +For each validated epic, load: + +1. **Epic file**: Read full content from `{epics_location}/epic-{id}*.md` +2. **Story files**: Find all stories matching patterns: + - `{stories_location}/{id}-*-*.md` (e.g., `36-1-user-auth.md`) + - `{stories_location}/story-{id}.*-*.md` + - Files containing `Epic: {id}` in content + +**Extract from each epic:** +- Title and description +- User stories listed +- Any `## Dependencies` section +- Technical context or requirements +- Mentioned patterns, components, or integrations + +**Extract from each story:** +- Story ID and title +- Status (Draft, Ready, In Progress, Done) +- Acceptance criteria +- Technical implementation notes +- References to shared code, APIs, or components + +Structured data for all epics and stories + + + +Perform dependency analysis across all loaded epics: + +**3.1 Explicit Dependencies** +- Check each epic for `## Dependencies` section +- Parse references like "Depends on Epic 36" or "Requires 36-3 complete" +- Build explicit dependency graph + +**3.2 Implicit Dependencies (Pattern Detection)** + +Scan story content for shared resources: + +| Pattern | Detection Method | Dependency Type | +|---------|------------------|-----------------| +| Database tables | Look for `CREATE TABLE`, model names, migrations | Schema dependency | +| API endpoints | Look for `/api/`, route definitions | API dependency | +| Components | Look for `import` from shared paths | Code dependency | +| Configuration | Look for env vars, feature flags | Config dependency | +| Types/Interfaces | Look for shared type definitions | Type dependency | + +**3.3 Build Dependency Matrix** + +``` +Epic | Depends On | Required By +--------|------------|------------ +36 | - | 37, 38 +37 | 36 | 38 +38 | 36, 37 | - +``` + +dependency_graph with edges and reasons + + + +Using dependency graph, determine execution order: + +**4.1 Topological Sort** +- Epics with no dependencies execute first +- Epics are ordered so dependencies are satisfied +- Circular dependencies β†’ error and ask user to resolve + +**4.2 Story-Level Ordering (within epic)** +- Stories execute in numerical order by default +- Detect story-level dependencies if specified +- Identify parallelizable stories (no shared resources) + +**4.3 Risk Assessment** + +For each epic/story, assess complexity: +- **High**: Multiple integrations, new patterns, security-sensitive +- **Medium**: Extends existing patterns, moderate scope +- **Low**: Simple CRUD, isolated changes + +execution_order list with risk annotations + + + +Detect concerns that span multiple epics: + +**5.1 Database Migrations** +- If multiple epics modify schema, flag migration order requirements +- Recommend: Run all migrations before story execution, or sequence carefully + +**5.2 API Versioning** +- If epics add/modify APIs, check for versioning consistency +- Flag breaking changes that affect other epics + +**5.3 Shared Component Changes** +- If early epic modifies shared code, flag impact on later epics +- Recommend: Review shared code changes before proceeding + +**5.4 Test Dependencies** +- If tests in later epics depend on fixtures from earlier epics +- Recommend: Ensure test data setup is consistent + +cross_cutting_concerns list with recommendations + + + +Find stories that can execute in parallel: + +**Within an epic:** +- Stories with no shared files or dependencies +- Stories that only read (don't modify) shared resources +- Stories flagged as `parallel-safe` in story file + +**Across epics (advanced):** +- Independent epics with no dependency relationship +- Requires `--parallel-epics` flag to enable + +parallel_opportunities list + + + +Create chain-plan.yaml with all analysis results: + +```yaml +# chain-plan.yaml +generated: {date} +epics: [{epic_ids}] +total_stories: {story_count} +analysis_depth: {analysis_depth} + +execution_order: + - epic: {id} + title: "{epic_title}" + stories: [{story_ids}] + story_count: {count} + estimated_complexity: {low|medium|high} + dependencies: [] + # OR + dependencies: + - epic: {dep_id} + reason: "{why}" + +cross_cutting_concerns: + - name: "{concern_name}" + affects: [{epic_ids}] + recommendation: "{action}" + +parallel_opportunities: + - scope: "within-epic" + epic: {id} + stories: [{story_ids}] + reason: "{why_parallel}" + +risk_areas: + - epic: {id} + story: "{story_id}" + risk: "{description}" + severity: {low|medium|high} + mitigation: "{recommendation}" + +estimated_execution: + total_stories: {count} + complex_stories: {count} + low_risk_stories: {count} +``` + +Save to {chain_plan_file} + + + +Display formatted analysis to {user_name}: + +``` +═══════════════════════════════════════════════════════════ + EPIC CHAIN ANALYSIS +═══════════════════════════════════════════════════════════ + +Epics: {epic_list} +Total Stories: {total_stories} + +EXECUTION ORDER +─────────────────────────────────────────────────────────── +{For each epic in execution_order:} +{n}. Epic {id}: {title} ({story_count} stories) + Dependencies: {deps or "None"} + Complexity: {complexity} +{end for} + +CROSS-CUTTING CONCERNS +─────────────────────────────────────────────────────────── +{For each concern:} +β€’ {name} + Affects: {epic_ids} + Action: {recommendation} +{end for} + +RISK AREAS +─────────────────────────────────────────────────────────── +{For each risk:} +β€’ Story {story_id}: {risk} + Severity: {severity} + Mitigation: {mitigation} +{end for} + +═══════════════════════════════════════════════════════════ +``` + +Ask user to choose: +1. **Approve** - Proceed with execution +2. **Modify** - Change order or exclude epics +3. **Analyze Only** - Save plan, don't execute +4. **Cancel** - Abort workflow + +Proceed to step 9 +Return to step 1 with modifications +Save plan, display shell command for later, end workflow +End workflow + + + +Display the shell command for execution: + +**The epic chain requires shell orchestration for context isolation.** + +Provide commands: + +```bash +# Dry run (recommended first) +./.bmad/scripts/epic-chain.sh {epic_ids} --dry-run --verbose + +# Full execution +./.bmad/scripts/epic-chain.sh {epic_ids} + +# With specific options +./.bmad/scripts/epic-chain.sh {epic_ids} --skip-done --verbose +``` + +Explain what will happen: + +1. For each epic in order: + - Load context handoff from previous epic (if any) + - Execute via `epic-execute.sh` (dev β†’ review β†’ commit per story) + - Generate context handoff for next epic + +2. After all epics: + - Generate combined UAT document + - Update sprint-status.yaml + - Display execution summary + +Remind user: +- Use `--dry-run` first to validate +- Use `--start-from {epic_id}` to resume after interruption +- Use `--skip-done` to skip already-completed stories +- Check logs at `{chain_log_file}` if issues occur + + + + +## Context Handoff Template + +After each epic completes, generate handoff: + +```markdown +# Epic {id} β†’ Epic {next_id} Handoff + +## Generated +{timestamp} + +## Patterns Established +{List coding patterns, conventions, architectural decisions made} + +## Key Decisions +{Major technical decisions with rationale} + +## Gotchas & Lessons Learned +{Issues encountered, workarounds applied, things to watch for} + +## Files to Reference +{Key files that establish patterns for next epic} + +## Test Patterns +{Testing conventions, fixture patterns, coverage expectations} +``` + +## Error Handling + +| Scenario | Behavior | +|----------|----------| +| Epic not found | Report missing epic, ask user to correct | +| Circular dependency | Report cycle, ask user to resolve | +| Story execution fails | Log failure, continue to next story, report in summary | +| Epic fails completely | Pause chain, ask user whether to continue or abort | +| Context handoff fails | Log warning, continue without handoff | diff --git a/src/modules/bmm/workflows/4-implementation/epic-chain/workflow.md b/src/modules/bmm/workflows/4-implementation/epic-chain/workflow.md new file mode 100644 index 000000000..68c42cf5c --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-chain/workflow.md @@ -0,0 +1,229 @@ +# Epic Chain Workflow + +## Metadata + +| Field | Value | +|-------|-------| +| Version | 1.0.0 | +| Trigger | `epic-chain` | +| Agent | SM (Scrum Master) | +| Category | Implementation | +| Complexity | High | + +## Purpose + +Analyze multiple epics to understand cross-epic dependencies, shared patterns, and optimal execution order, then execute them in sequence with coordinated context sharing. Unlike single-epic execution, this workflow: + +1. **Analyzes** all epics before execution to identify relationships +2. **Plans** optimal story ordering across epic boundaries +3. **Shares context** between epics (patterns learned, decisions made) +4. **Chains** execution seamlessly from one epic to the next + +## When to Use + +- Executing multiple related epics (e.g., Epic 36, 37, 38) +- Epics that build on each other's foundations +- Release planning where multiple epics form a cohesive delivery +- When you want analysis before committing to execution + +## Workflow Phases + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ EPIC CHAIN FLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ PHASE 1: ANALYSIS β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Load Epics β”‚β†’ β”‚ Detect β”‚β†’ β”‚ Build β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ & Stories β”‚ β”‚ Dependenciesβ”‚ β”‚ Chain Plan β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ ↓ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ PHASE 2: APPROVAL β”‚ β”‚ +β”‚ β”‚ Present chain plan β†’ User reviews β†’ Approve/Modify β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ ↓ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ PHASE 3: EXECUTION β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ For each epic in chain: β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Execute via epic-execute.sh β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”œβ”€ Dev Phase (per story) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”œβ”€ Review Phase (per story) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ └─ Commit (per story) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ ↓ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Generate cross-epic context handoff β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Patterns learned, decisions made, gotchas) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ ↓ β”‚ β”‚ +β”‚ β”‚ Next epic receives handoff context... β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ ↓ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ PHASE 4: WRAP-UP β”‚ β”‚ +β”‚ β”‚ β”œβ”€ Generate combined UAT document β”‚ β”‚ +β”‚ β”‚ β”œβ”€ Chain execution summary β”‚ β”‚ +β”‚ β”‚ └─ Update sprint-status.yaml β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Analysis Capabilities + +The analysis phase examines: + +### 1. Cross-Epic Dependencies +- Shared database models/migrations +- Shared API endpoints +- Shared components or utilities +- Feature flags or configuration dependencies + +### 2. Story Ordering Optimization +- Stories that create foundations used by later stories +- Parallel execution opportunities +- Natural break points + +### 3. Pattern Recognition +- Similar implementation patterns across epics +- Reusable code opportunities +- Consistency requirements + +### 4. Risk Assessment +- Complex stories that might block others +- Integration points between epics +- Testing dependencies + +## Chain Plan Output + +The analysis produces a chain plan document: + +```yaml +# chain-plan.yaml +generated: 2024-01-15T10:30:00 +epics: [36, 37, 38] +total_stories: 24 + +execution_order: + - epic: 36 + stories: [36-1, 36-2, 36-3, 36-4, 36-5, 36-6, 36-7, 36-8] + estimated_complexity: medium + dependencies: [] + + - epic: 37 + stories: [37-1, 37-2, 37-3] + estimated_complexity: low + dependencies: + - epic: 36 + reason: "Uses content management patterns from 36" + + - epic: 38 + stories: [38-1, 38-2, 38-3, 38-4] + estimated_complexity: high + dependencies: + - epic: 36 + reason: "Extends search functionality" + - epic: 37 + reason: "Integrates with content workflow" + +cross_cutting_concerns: + - name: "Database migrations" + affects: [36, 37] + recommendation: "Run all migrations before story execution" + + - name: "API versioning" + affects: [36, 38] + recommendation: "Maintain backwards compatibility" + +parallel_opportunities: + - stories: [37-2, 37-3] + reason: "Independent features with no shared code" + +risk_areas: + - story: 38-3 + risk: "Complex search integration" + mitigation: "Extensive test coverage, staged rollout" +``` + +## Orchestration + +This workflow uses shell orchestration similar to epic-execute: + +```bash +# Analyze and plan (no execution) +./.bmad/scripts/epic-chain.sh 36 37 38 --analyze-only + +# Execute with analysis +./.bmad/scripts/epic-chain.sh 36 37 38 + +# Resume from specific epic +./.bmad/scripts/epic-chain.sh 36 37 38 --start-from 37 + +# Skip already-done epics +./.bmad/scripts/epic-chain.sh 36 37 38 --skip-done +``` + +## Context Handoff Between Epics + +After each epic completes, a handoff document is generated: + +```markdown +# Epic 36 β†’ Epic 37 Handoff + +## Patterns Established +- Content validation using Zod schemas in `lib/validators/` +- API routes follow RESTful conventions with `/api/v1/` prefix +- All database queries use connection pooling + +## Key Decisions Made +- Used PostgreSQL full-text search instead of Elasticsearch +- Implemented soft deletes for all content types + +## Gotchas for Next Epic +- Rate limiting middleware must be added before auth middleware +- Content types require explicit registration in `types/content.ts` + +## Files to Reference +- `lib/content/manager.ts` - Core content operations +- `lib/search/index.ts` - Search implementation patterns +``` + +## Usage + +Via SM Agent: +``` +/sm +*epic-chain +``` + +Via Shell (after planning): +```bash +./.bmad/scripts/epic-chain.sh 36 37 38 +``` + +## Configuration + +Optional settings in `bmad/_cfg/epic-chain.yaml`: + +```yaml +# Analysis depth: quick | standard | thorough +analysis_depth: standard + +# Auto-approve chain plan without user confirmation +auto_approve: false + +# Generate combined UAT at end +combined_uat: true + +# Share context between epics +context_handoff: true + +# Parallel story execution within epics +parallel_within_epic: false +``` diff --git a/src/modules/bmm/workflows/4-implementation/epic-chain/workflow.yaml b/src/modules/bmm/workflows/4-implementation/epic-chain/workflow.yaml new file mode 100644 index 000000000..537d4bda4 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-chain/workflow.yaml @@ -0,0 +1,52 @@ +name: epic-chain +description: "Analyze and execute multiple epics in sequence with intelligent dependency detection, cross-epic analysis, and coordinated implementation planning" +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/.bmad/bmm/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" + +# Workflow components +installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/epic-chain" +instructions: "{installed_path}/instructions.md" +launcher: "{installed_path}/epic-chain-launcher.md" + +# Variables and inputs +variables: + # Project context + project_context: "**/project-context.md" + project_name: "{config_source}:project_name" + + # Epic sources + epics_location: "{output_folder}" + epics_pattern: "epic*.md" + stories_location: "{sprint_artifacts}" + + # Chain configuration (can be overridden by user) + chain_mode: "sequential" # sequential | parallel | dependency-aware + analysis_depth: "standard" # quick | standard | thorough + + # Output locations + chain_plan_file: "{sprint_artifacts}/chain-plan.yaml" + chain_log_file: "{sprint_artifacts}/chain-execution.log" + +# Input file patterns +input_file_patterns: + epics: + description: "All epics to potentially include in chain" + whole: "{output_folder}/*epic*.md" + sharded: "{output_folder}/*epic*/*.md" + load_strategy: "FULL_LOAD" + stories: + description: "All story files for analysis" + whole: "{stories_location}/*.md" + load_strategy: "METADATA_ONLY" + +# Output configuration +default_output_file: "{chain_plan_file}" + +standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/INSTALLATION.md b/src/modules/bmm/workflows/4-implementation/epic-execute/INSTALLATION.md new file mode 100644 index 000000000..dbb0b82d7 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/INSTALLATION.md @@ -0,0 +1,285 @@ +# Epic Execute Workflow - Installation Guide + +## Overview + +The Epic Execute workflow automates the execution of all stories in an epic with context isolation between development and review phases, producing a User Acceptance Testing document for human validation. + +## Prerequisites + +- BMAD v6 installed in your project +- Claude Code CLI (`claude`) available in PATH +- Git repository initialized +- Node.js 18+ (for Claude Code) + +## Installation + +### Option 1: Copy to Existing BMAD Installation + +Copy the workflow files to your project's BMAD installation: + +```bash +# From the bmad-epic-execute directory +cp -r workflows/epic-execute /path/to/your/project/bmad/bmm/workflows/4-implementation/ + +# Copy the shell script +cp scripts/epic-execute.sh /path/to/your/project/bmad/scripts/ + +# Make executable +chmod +x /path/to/your/project/bmad/scripts/epic-execute.sh +``` + +### Option 2: Manual Installation + +1. Create the workflow directory structure: + +```bash +mkdir -p bmad/bmm/workflows/4-implementation/epic-execute/steps +mkdir -p bmad/bmm/workflows/4-implementation/epic-execute/templates +mkdir -p bmad/bmm/workflows/4-implementation/epic-execute/config +mkdir -p bmad/scripts +``` + +2. Copy all workflow files to the appropriate locations + +3. Make the script executable: + +```bash +chmod +x bmad/scripts/epic-execute.sh +``` + +## Directory Structure + +After installation, you should have: + +``` +your-project/ +β”œβ”€β”€ bmad/ +β”‚ β”œβ”€β”€ bmm/ +β”‚ β”‚ └── workflows/ +β”‚ β”‚ └── 4-implementation/ +β”‚ β”‚ └── epic-execute/ +β”‚ β”‚ β”œβ”€β”€ workflow.md +β”‚ β”‚ β”œβ”€β”€ config/ +β”‚ β”‚ β”‚ └── default-config.yaml +β”‚ β”‚ β”œβ”€β”€ steps/ +β”‚ β”‚ β”‚ β”œβ”€β”€ step-01-init.md +β”‚ β”‚ β”‚ β”œβ”€β”€ step-02-dev-story.md +β”‚ β”‚ β”‚ β”œβ”€β”€ step-03-code-review.md +β”‚ β”‚ β”‚ β”œβ”€β”€ step-04-generate-uat.md +β”‚ β”‚ β”‚ └── step-05-summary.md +β”‚ β”‚ └── templates/ +β”‚ β”‚ └── uat-template.md +β”‚ β”œβ”€β”€ scripts/ +β”‚ β”‚ └── epic-execute.sh +β”‚ └── _cfg/ +β”‚ └── epic-execute.yaml (optional customization) +β”œβ”€β”€ docs/ +β”‚ β”œβ”€β”€ epics/ +β”‚ β”‚ └── epic-1.md +β”‚ β”œβ”€β”€ stories/ (stories can be here) +β”‚ β”‚ β”œβ”€β”€ story-1.1-feature.md +β”‚ β”‚ └── story-1.2-feature.md +β”‚ β”œβ”€β”€ sprints/ (OR stories can be here) +β”‚ β”‚ β”œβ”€β”€ story-1.1-feature.md +β”‚ β”‚ └── story-1.2-feature.md +β”‚ └── uat/ (created during execution) +``` + +## Configuration + +### Custom Configuration + +To customize the workflow behavior, copy the default config: + +```bash +cp bmad/bmm/workflows/4-implementation/epic-execute/config/default-config.yaml \ + bmad/_cfg/epic-execute.yaml +``` + +Edit `bmad/_cfg/epic-execute.yaml` to change settings. + +### Key Configuration Options + +| Setting | Default | Description | +|---------|---------|-------------| +| `execution.auto_commit` | `true` | Commit after each story | +| `review.mode` | `standard` | Review strictness level | +| `review.auto_fix_enabled` | `true` | Allow reviewer to fix issues | +| `context.isolate_phases` | `true` | Fresh context per phase | +| `uat.enabled` | `true` | Generate UAT document | +| `git.auto_push` | `false` | Push after commits | + +## Usage + +### Basic Usage + +```bash +./bmad/scripts/epic-execute.sh + +# Example +./bmad/scripts/epic-execute.sh 1 +``` + +### With Options + +```bash +# Dry run - see what would execute +./bmad/scripts/epic-execute.sh 1 --dry-run + +# Skip code review (not recommended) +./bmad/scripts/epic-execute.sh 1 --skip-review + +# Don't commit (stage only) +./bmad/scripts/epic-execute.sh 1 --no-commit + +# Verbose output +./bmad/scripts/epic-execute.sh 1 --verbose +``` + +### Via SM Agent + +You can also initiate via the SM agent: + +``` +/sm +*epic-execute 1 +``` + +The agent will validate the epic and provide the shell command to run. + +## Epic and Story Requirements + +### Epic File Format + +Your epic file should include: + +```markdown +# Epic 1: Feature Name + +## Goal +[What this epic delivers] + +## Success Criteria +- [ ] Users can do X +- [ ] System handles Y + +## Stories +- story-1.1: First feature +- story-1.2: Second feature +``` + +### Story File Format + +Stories should include: + +```markdown +# Story 1.1: Feature Name + +## Status: Ready + +## Epic: 1 + +## Description +As a [user], I can [action] so that [benefit] + +## Acceptance Criteria +- [ ] Criterion 1 +- [ ] Criterion 2 + +## Technical Context +[Implementation guidance] + +## Files +- path/to/file.ts + +## Dependencies +- None (or list story IDs) + +## Dev Agent Record + +``` + +## Output + +After execution, you'll have: + +| Output | Location | Description | +|--------|----------|-------------| +| Updated Stories | `docs/stories/` | Marked Done with Dev Agent Record + Code Review Record | +| UAT Document | `docs/uat/epic-{id}-uat.md` | Human testing script | +| Execution Log | `docs/sprints/` | Detailed run log | + +## Issue Fix Policy + +The code review phase automatically fixes issues based on severity: + +| Severity | Action | +|----------|--------| +| HIGH | Always fix (security, missing tests, error handling) | +| MEDIUM | Fix if total issues > 5 (pattern violations, edge cases) | +| LOW | Document only (naming, style) | + +## Troubleshooting + +### "Epic file not found" + +Ensure your epic file matches one of these patterns: +- `docs/epics/epic-{id}.md` +- `docs/epics/{id}.md` + +### "No stories found" + +Stories are discovered from **both** `docs/stories/` and `docs/sprints/` by: +1. Grep for `Epic: {id}` in story files +2. Naming convention: `story-{epic}.{seq}-*.md` or `story-{epic}-*.md` + +Check both locations: +```bash +# See what's in both directories +ls docs/stories/*.md docs/sprints/*.md 2>/dev/null + +# Check if stories reference the epic +grep -l "Epic.*1" docs/stories/*.md docs/sprints/*.md 2>/dev/null +``` + +Ensure your stories reference the epic or follow the naming convention. + +### "Claude command not found" + +Install Claude Code CLI: +```bash +npm install -g @anthropic/claude-code +``` + +### Context Not Clearing + +Each `claude -p` invocation creates a fresh context. If you're seeing context bleed, ensure you're using the shell script (not running steps manually in one session). + +## Integration with BMAD Workflow + +This workflow fits into the BMAD methodology as: + +``` +Phase 3: Solutioning + └── create-epics-and-stories β†’ Epic + Story files + +Phase 4: Implementation + └── epic-execute β†’ Automated execution + β”œβ”€β”€ dev-story (per story) + β”œβ”€β”€ code-review (per story) + └── generate-uat + +Human Testing + └── Execute UAT document + +Deployment + └── Standard deployment process +``` + +## Support + +For issues with this workflow: +- Check the execution log in `docs/sprints/` +- Review story files for Dev Agent Record / Code Review Record +- Ensure prerequisites are met +- Verify epic/story file formats diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/README.md b/src/modules/bmm/workflows/4-implementation/epic-execute/README.md new file mode 100644 index 000000000..a5b4a004a --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/README.md @@ -0,0 +1,122 @@ +# BMAD Epic Execute Workflow + +Automated story execution with context isolation and UAT generation. + +## What It Does + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Epic β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚Story 1β”‚ β”‚Story 2β”‚ β”‚Story Nβ”‚ β”‚ +β”‚ β””β”€β”€β”€β”¬β”€β”€β”€β”˜ β””β”€β”€β”€β”¬β”€β”€β”€β”˜ β””β”€β”€β”€β”¬β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Dev β”‚ β”‚ Dev β”‚ β”‚ Dev β”‚ β”‚ +β”‚ β”‚ Context A β”‚ β”‚ Context C β”‚ β”‚ Context E β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ git staged β”‚ git staged β”‚ git staged β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Review β”‚ β”‚ Review β”‚ β”‚ Review β”‚ β”‚ +β”‚ β”‚ Context B β”‚ β”‚ Context D β”‚ β”‚ Context F β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ commit β”‚ commit β”‚ commit β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ UAT Generation β”‚ β”‚ +β”‚ β”‚ (Context G) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ UAT Document β”‚ β”‚ +β”‚ β”‚ (For Humans) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Key Features + +- **Context Isolation**: Dev and Review phases run in separate Claude sessions +- **Clean Reviews**: Reviewer sees only the diff and story file, not the implementation journey +- **Severity-Based Fixes**: HIGH always fixed, MEDIUM fixed if >5 total issues, LOW documented only +- **Automated Commits**: Each story committed after passing review +- **UAT Generation**: Human-readable test script produced automatically +- **Story File as Single Source**: Dev Agent Record and Code Review Record live in the story file + +## Quick Start + +```bash +# Execute all stories in epic 1 +./bmad/scripts/epic-execute.sh 1 +``` + +## Files + +``` +epic-execute/ +β”œβ”€β”€ workflow.md # Main workflow definition +β”œβ”€β”€ INSTALLATION.md # Setup guide +β”œβ”€β”€ config/ +β”‚ └── default-config.yaml # Configuration options +β”œβ”€β”€ steps/ +β”‚ β”œβ”€β”€ step-01-init.md # Discover epic and stories +β”‚ β”œβ”€β”€ step-02-dev-story.md # Development phase prompt +β”‚ β”œβ”€β”€ step-03-code-review.md # Review phase prompt +β”‚ β”œβ”€β”€ step-04-generate-uat.md # UAT generation prompt +β”‚ └── step-05-summary.md # Execution report +└── templates/ + └── uat-template.md # UAT document template +``` + +## Why Context Isolation? + +Without isolation: +- Review phase "knows" about implementation struggles +- Reviewer is biased by seeing the journey +- Context window fills with debugging noise + +With isolation: +- Reviewer sees the code cold (like a real PR review) +- Each phase has full context window available +- State passes via git staging and story file updates + +**How state transfers:** +- Code changes β†’ git staging +- Implementation notes β†’ story file's Dev Agent Record +- Review findings β†’ story file's Code Review Record +- Story status β†’ Status field in story file + +## Output + +| Artifact | Location | +|----------|----------| +| Completed Stories | `docs/stories/*.md` (with Dev Agent Record + Code Review Record) | +| UAT Document | `docs/uat/epic-{id}-uat.md` | +| Execution Log | `docs/sprints/epic-{id}-execution.md` | + +## Issue Fix Policy + +| Severity | Examples | Action | +|----------|----------|--------| +| HIGH | Security issues, no tests, missing error handling | Always fix | +| MEDIUM | Pattern violations, missing edge cases | Fix if total issues > 5 | +| LOW | Naming, style, comments | Document only | + +## Requirements + +- BMAD v6 +- Claude Code CLI +- Git + +## See Also + +- [Installation Guide](./INSTALLATION.md) +- [Workflow Definition](./workflow.md) +- [Configuration Options](./config/default-config.yaml) diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/config/default-config.yaml b/src/modules/bmm/workflows/4-implementation/epic-execute/config/default-config.yaml new file mode 100644 index 000000000..4e49ecbce --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/config/default-config.yaml @@ -0,0 +1,124 @@ +# Epic Execute Workflow Configuration +# +# Copy this file to bmad/_cfg/epic-execute.yaml to customize +# + +# Story Execution Settings +execution: + # Automatically commit after each story completes + auto_commit: true + + # Run tests before transitioning to review phase + run_tests_before_review: true + + # Maximum retries for failed phases + max_retries: 2 + + # Timeout per phase in seconds (0 = no timeout) + phase_timeout: 0 + +# Review Settings +review: + # Review strictness: lenient | standard | strict + # lenient - Only block on missing acceptance criteria + # standard - Block on acceptance criteria, security, major quality + # strict - Block on any quality issue, no auto-fixing + mode: standard + + # Allow reviewer to auto-fix issues + auto_fix_enabled: true + + # Require all tests pass before approval + require_passing_tests: true + + # Issue fix policy thresholds + fix_policy: + # Always fix HIGH severity issues + always_fix_high: true + + # Fix MEDIUM severity if total issues exceed this threshold + medium_fix_threshold: 5 + + # Never auto-fix LOW severity (just document) + fix_low: false + +# Context Isolation +context: + # Clear context between phases (recommended) + isolate_phases: true + + # Include architecture doc in dev context + include_architecture: true + + # Include PRD in dev context + include_prd: false + + # Max lines of code context to include + max_code_context: 500 + +# UAT Generation +uat: + # Generate UAT after all stories complete + enabled: true + + # UAT output location (relative to project root) + output_dir: docs/uat + + # Include edge case scenarios + include_edge_cases: true + + # Minimum scenarios to generate + min_scenarios: 3 + + # Maximum scenarios to generate + max_scenarios: 10 + +# Git Settings +git: + # Commit message prefix + commit_prefix: "feat" + + # Include epic ID in commit message + include_epic_in_commit: true + + # Push after each commit + auto_push: false + + # Branch naming pattern (use {epic_id} and {story_id} as placeholders) + branch_pattern: "feature/epic-{epic_id}" + +# Parallel Execution (Experimental) +parallel: + # Enable parallel story execution + enabled: false + + # Maximum concurrent stories + max_concurrent: 3 + + # Only parallelize independent stories (no dependencies) + respect_dependencies: true + +# Logging +logging: + # Log level: debug | info | warn | error + level: info + + # Save execution log + save_log: true + + # Log output location + log_dir: docs/sprints + + # Include Claude responses in log (verbose) + log_responses: false + +# Notifications (Future) +notifications: + # Notify on completion + on_complete: false + + # Notify on failure + on_failure: false + + # Notification method: slack | email | none + method: none diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/epic-execute-launcher.md b/src/modules/bmm/workflows/4-implementation/epic-execute/epic-execute-launcher.md new file mode 100644 index 000000000..10ebfeaa1 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/epic-execute-launcher.md @@ -0,0 +1,59 @@ +# Epic Execute Launcher + +This workflow requires **shell orchestration** for context isolation between dev and review phases. + +## Instructions + +When the user invokes `*epic-execute`, follow these steps: + +### Step 1: Get Epic ID + +Ask the user which epic to execute if not provided as an argument. Valid epic IDs can be found in `docs/epics/`. + +### Step 2: Validate Prerequisites + +Before running, verify: +1. Epic file exists at `docs/epics/epic-{id}-*.md` +2. Stories exist for the epic (check `docs/stories/` and `docs/sprint-artifacts/`) +3. Git working directory is clean (no uncommitted changes) + +### Step 3: Provide the Command + +Tell the user to run one of these commands: + +**Dry run (recommended first):** +```bash +./.bmad/scripts/epic-execute.sh {epic_id} --dry-run --verbose +``` + +**Full execution:** +```bash +./.bmad/scripts/epic-execute.sh {epic_id} +``` + +**With verbose output:** +```bash +./.bmad/scripts/epic-execute.sh {epic_id} --verbose +``` + +### Step 4: Explain What Happens + +The workflow will: +1. Find all stories for the epic +2. For each story: + - **Dev Phase** (isolated context): Implement the story + - **Review Phase** (fresh context): Code review the changes + - **Commit**: Auto-commit if review passes +3. **UAT Generation**: Create human testing document at `docs/uat/epic-{id}-uat.md` + +### Why Shell Orchestration? + +Context isolation ensures: +- Reviewer sees code "cold" (like a real PR review) +- Each phase has full context window available +- No bias from seeing implementation struggles + +State transfers via: +- Code changes β†’ git staging +- Implementation notes β†’ story file's Dev Agent Record +- Review findings β†’ story file's Code Review Record diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-01-init.md b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-01-init.md new file mode 100644 index 000000000..097c9391e --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-01-init.md @@ -0,0 +1,119 @@ +# Step 1: Initialize Epic Execution + +## Objective + +Validate the epic exists, discover all associated stories, verify prerequisites, and prepare the execution plan. + +## Inputs + +- `epic_id`: The epic identifier (e.g., "1", "auth", "epic-1") + +## Actions + +### 1.1 Locate Epic File + +Search for the epic definition: + +``` +docs/epics/epic-{epic_id}.md +docs/epics/{epic_id}.md +docs/epics/epic-{epic_id}*.md +``` + +**If not found**: Stop and report. Cannot proceed without epic definition. + +### 1.2 Parse Epic Metadata + +Extract from epic file: + +- Epic title/name +- Epic goal/description +- Success criteria (if defined) +- Story references + +### 1.3 Discover Stories + +Find all stories belonging to this epic: + +```bash +# Stories reference epic in frontmatter or body +grep -l "Epic: {epic_id}\|epic-{epic_id}" docs/stories/*.md +``` + +Or parse story naming convention: +``` +docs/stories/story-{epic_id}.1-*.md +docs/stories/story-{epic_id}.2-*.md +``` + +### 1.4 Validate Story Readiness + +For each discovered story, verify: + +| Check | Required | +|-------|----------| +| Status is `Ready` or `Draft` | Yes | +| Acceptance criteria defined | Yes | +| Technical context present | Recommended | +| File paths identified | Recommended | +| Dependencies listed | If applicable | + +### 1.5 Resolve Dependencies + +Build execution order: + +1. Parse `Dependencies` section of each story +2. Topological sort to determine order +3. Flag circular dependencies as blockers + +### 1.6 Generate Execution Plan + +Create `docs/handoff/epic-{epic_id}-plan.md`: + +```markdown +# Epic {epic_id} Execution Plan + +**Generated**: {timestamp} +**Stories**: {count} +**Estimated Phases**: {count * 2} (dev + review per story) + +## Execution Order + +| Order | Story | Dependencies | Status | +|-------|-------|--------------|--------| +| 1 | story-1.1 | None | Ready | +| 2 | story-1.2 | story-1.1 | Ready | +| 3 | story-1.3 | story-1.1 | Ready | +| 4 | story-1.4 | story-1.2, story-1.3 | Ready | + +## Prerequisites Check + +- [ ] Architecture doc available +- [ ] Test framework configured +- [ ] Git working tree clean + +## Ready to Execute + +Run: `./bmad/scripts/epic-execute.sh {epic_id}` +``` + +## Outputs + +- Execution plan document +- Ordered list of story IDs for shell script +- Any blockers identified + +## Next Step + +If all validations pass, provide user with shell command to begin execution. + +**Transition**: User runs `./bmad/scripts/epic-execute.sh {epic_id}` + +## Error States + +| Error | Resolution | +|-------|------------| +| Epic not found | Ask user for correct epic ID or path | +| No stories found | Verify story naming convention, check epic references | +| Stories not Ready | List stories needing prep, offer to run story creation | +| Circular dependency | Display cycle, ask user to resolve | diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-02-dev-story.md b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-02-dev-story.md new file mode 100644 index 000000000..c2b47de71 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-02-dev-story.md @@ -0,0 +1,162 @@ +# Step 2: Development Phase (Isolated Context) + +## Context Isolation + +**IMPORTANT**: This step executes in a fresh Claude context, separate from initialization and review phases. This ensures the dev agent has full context window for implementation without pollution from other phases. + +## Objective + +Implement a single story completely: code, tests, and documentation updates. + +## Inputs + +- `story_id`: The story to implement +- `story_file`: Path to story markdown file + +## Prompt Template + +This prompt is passed to an isolated Claude session: + +``` +You are the Dev agent executing a BMAD story implementation. + +## Your Task + +Implement story: {story_id} + +## Story Specification + + +{story_file_contents} + + +## Reference Documents + +Read these for context (do not load unless needed): +- Architecture: docs/architecture.md (or shards in docs/architecture/) +- PRD: docs/prd.md (or shards in docs/prd/) +- Related stories: {dependency_story_files} + +## Implementation Requirements + +1. **Read the story file completely** before writing any code + +2. **Follow existing patterns**: + - Check existing code in the directories you'll modify + - Match naming conventions, file structure, code style + - Use established patterns for similar functionality + +3. **Implement all acceptance criteria**: + - Each criterion must have corresponding code + - Each criterion must have at least one test + +4. **Write tests**: + - Unit tests for new functions/methods + - Integration tests for API endpoints + - Follow existing test patterns in the codebase + +5. **Run tests**: + - Execute: `npm test` or appropriate test command + - All tests must pass before completion + - Fix any failures before proceeding + +6. **Update documentation**: + - Add JSDoc/docstrings to new code + - Update README if adding new features/commands + +## Completion Checklist + +Before marking complete, verify: + +- [ ] All acceptance criteria implemented +- [ ] Tests written and passing +- [ ] No linting errors +- [ ] Code follows existing patterns +- [ ] No hardcoded secrets or test data + +## Update Story File + +When implementation is complete, update the story file: + +1. Change Status to: `In Review` + +2. Fill in the Dev Agent Record section: + +```markdown +## Dev Agent Record + +### Implementation Summary +[Brief description of what was implemented] + +### Files Created +- path/to/new/file.ts - [purpose] +- path/to/another/file.ts - [purpose] + +### Files Modified +- path/to/existing/file.ts - [what changed] + +### Key Decisions +- [Any architectural or implementation decisions made] +- [Deviations from the story spec and why] + +### Tests Added +- path/to/test.spec.ts - [what it tests] + +### Notes for Reviewer +- [Anything the reviewer should pay attention to] +- [Areas of uncertainty] + +### Test Results +[Summary of test run output] + +### Acceptance Criteria Status +- [x] Criterion 1 - implemented in {file} +- [x] Criterion 2 - implemented in {file} +``` + +## Git Operations + +Stage your changes (do NOT commit): + +```bash +git add -A +``` + +## Completion Signal + +When finished, output exactly: + +``` +IMPLEMENTATION COMPLETE: {story_id} +``` + +This signals the orchestration script to proceed to review phase. + +## Error Handling + +If you encounter a blocker you cannot resolve: + +1. Document the blocker in the story file's Dev Agent Record +2. Stage any partial work +3. Output: `IMPLEMENTATION BLOCKED: {story_id} - {reason}` +``` + +## Orchestration Integration + +The shell script captures this prompt and passes it to Claude: + +```bash +claude -p "$(cat step-02-dev-story.md | envsubst)" +``` + +The `envsubst` replaces `{story_id}`, `{story_file_contents}`, etc. with actual values. + +## Success Criteria + +Phase complete when: + +- All acceptance criteria have code +- All tests pass +- Changes are staged in git +- Story file updated with Dev Agent Record +- IMPLEMENTATION COMPLETE signal output diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-03-code-review.md b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-03-code-review.md new file mode 100644 index 000000000..40228704a --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-03-code-review.md @@ -0,0 +1,255 @@ +# Step 3: Code Review Phase (Isolated Context) + +## Context Isolation + +**IMPORTANT**: This step executes in a completely fresh Claude context. The reviewer has no knowledge of the implementation journeyβ€”only the final diff, story spec, and Dev Agent Record. This simulates a real code review where the reviewer sees the PR cold. + +## Objective + +Review the staged changes with fresh eyes, verify acceptance criteria, ensure code quality, fix issues based on severity thresholds, and either approve or escalate. + +## Inputs + +- `story_id`: The story being reviewed +- `story_file`: Path to story markdown file (contains Dev Agent Record from dev phase) + +## Issue Fix Policy + +| Severity | Action | +|----------|--------| +| **HIGH** | Always fix immediately | +| **MEDIUM** | Fix if total issues > 5, otherwise note for later | +| **LOW** | Document only, do not fix | + +## Prompt Template + +``` +You are a Senior Code Reviewer performing a BMAD code review. + +## Your Task + +Review the implementation of story: {story_id} + +You are seeing this code for the first time. You have no knowledge of the implementation process. + +## Story Specification and Dev Context + + +{story_file_contents} + + +The story file contains: +- Acceptance criteria (what must be verified) +- Dev Agent Record (implementation notes from the developer) +- Notes for Reviewer (areas of concern flagged by dev) + +## Review the Diff + +Run this command and analyze the output: + +```bash +git diff --staged +``` + +## Review Checklist + +### 1. Acceptance Criteria Verification + +For EACH acceptance criterion in the story: + +- [ ] Criterion is implemented +- [ ] Implementation matches the requirement (not just technically works) +- [ ] Test exists that verifies this criterion + +### 2. Code Quality + +| Check | Status | Severity if Failed | +|-------|--------|-------------------| +| Follows existing patterns | | MEDIUM | +| No code duplication | | LOW | +| Functions are focused (single responsibility) | | MEDIUM | +| Naming is clear and consistent | | LOW | +| No hardcoded values that should be config | | MEDIUM | +| Error handling is appropriate | | HIGH | +| No security issues (SQL injection, XSS, etc.) | | HIGH | +| No exposed secrets or credentials | | HIGH | + +### 3. Test Quality + +| Check | Status | Severity if Failed | +|-------|--------|-------------------| +| Tests exist for new functionality | | HIGH | +| Tests are meaningful (not just coverage) | | MEDIUM | +| Edge cases considered | | MEDIUM | +| Tests are independent (no order dependency) | | LOW | + +### 4. Performance & Security + +| Check | Status | Severity if Failed | +|-------|--------|-------------------| +| No N+1 queries | | HIGH | +| No blocking operations in async code | | HIGH | +| Inputs are validated | | HIGH | +| Authentication/authorization correct | | HIGH | + +## Issue Collection + +After completing the checklist, compile all issues found: + +```markdown +### Issues Found + +| # | Description | Severity | File:Line | Fixable | +|---|-------------|----------|-----------|---------| +| 1 | [issue] | HIGH/MEDIUM/LOW | path:123 | Yes/No | +| 2 | [issue] | HIGH/MEDIUM/LOW | path:456 | Yes/No | +``` + +Count totals: +- HIGH: {count} +- MEDIUM: {count} +- LOW: {count} +- TOTAL: {count} + +## Fix Decision Logic + +Apply this logic: + +``` +IF any HIGH severity issues exist: + β†’ Fix ALL HIGH severity issues + +IF total issues > 5: + β†’ Also fix ALL MEDIUM severity issues + +LOW severity issues: + β†’ Document only, do not fix +``` + +## Fixing Issues + +For each issue you're fixing: + +1. Make the code change +2. Run tests to verify fix doesn't break anything +3. Log the fix: + +```markdown +### Fixes Applied + +| Issue # | Fix Description | Verified | +|---------|-----------------|----------| +| 1 | [what you changed] | Tests pass | +| 2 | [what you changed] | Tests pass | +``` + +After all fixes: +```bash +git add -A +``` + +## Update Story File + +Add the Code Review Record section to the story file: + +```markdown +## Code Review Record + +**Reviewer**: Code Review Agent +**Date**: {timestamp} +**Diff Size**: {lines_changed} lines + +### Checklist Results +- Acceptance Criteria: PASS/FAIL +- Code Quality: PASS/FAIL +- Test Coverage: PASS/FAIL +- Security: PASS/FAIL + +### Issues Found + +| # | Description | Severity | Status | +|---|-------------|----------|--------| +| 1 | [issue] | HIGH | Fixed | +| 2 | [issue] | MEDIUM | Fixed | +| 3 | [issue] | LOW | Documented | + +**Totals**: {high} HIGH, {medium} MEDIUM, {low} LOW + +### Fixes Applied +[List of fixes made during review] + +### Remaining Issues (Low Severity) +[List of issues not fixed, for future cleanup] + +### Final Status +{Approved / Approved with fixes / Rejected} +``` + +## Completion Criteria + +### APPROVE if: +- All acceptance criteria pass +- No HIGH severity issues remain +- No MEDIUM severity issues remain (either fixed or < 5 total issues) + +Update story Status to: `Done` + +Output: `REVIEW PASSED: {story_id}` +or: `REVIEW PASSED WITH FIXES: {story_id} - Fixed {n} issues` + +### REJECT if: +- Acceptance criteria not met +- HIGH severity issues cannot be fixed +- Fundamental architectural problems + +Update story Status to: `Blocked` + +Output: `REVIEW FAILED: {story_id} - {reason}` + +## Example Scenarios + +### Scenario A: Clean Code +- 0 issues found +- Action: Approve immediately +- Output: `REVIEW PASSED: story-1.1` + +### Scenario B: Minor Issues Only +- 3 issues: 0 HIGH, 2 MEDIUM, 1 LOW +- Action: Document all, fix nothing (total ≀ 5) +- Output: `REVIEW PASSED: story-1.1` + +### Scenario C: Security Issue +- 4 issues: 1 HIGH (SQL injection), 2 MEDIUM, 1 LOW +- Action: Fix the HIGH issue, document MEDIUM and LOW +- Output: `REVIEW PASSED WITH FIXES: story-1.1 - Fixed 1 issues` + +### Scenario D: Many Issues +- 8 issues: 1 HIGH, 5 MEDIUM, 2 LOW +- Action: Fix HIGH (1) + all MEDIUM (5), document LOW +- Output: `REVIEW PASSED WITH FIXES: story-1.1 - Fixed 6 issues` + +### Scenario E: Unfixable Problem +- Missing acceptance criterion, requires re-implementation +- Action: Document, reject +- Output: `REVIEW FAILED: story-1.1 - Acceptance criterion 3 not implemented` + +## Git Operations + +If review passes: +- All changes (original + fixes) should be staged +- Do NOT commit (shell script handles this) + +``` + +## Orchestration Integration + +```bash +# Fresh context - no shared state with dev phase +claude -p "$(cat step-03-code-review.md | envsubst)" +``` + +## Notes + +- The Dev Agent Record in the story file provides implementation context without polluting the review +- Severity-based fixing prevents over-engineering while ensuring critical issues are resolved +- Low severity issues are tracked for future cleanup sprints diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-04-generate-uat.md b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-04-generate-uat.md new file mode 100644 index 000000000..3df28b3d6 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-04-generate-uat.md @@ -0,0 +1,262 @@ +# Step 4: Generate User Acceptance Testing Document (Isolated Context) + +## Context Isolation + +**IMPORTANT**: This step executes in a completely fresh context after all stories are complete. The UAT generator sees only the finished epic and story specificationsβ€”not implementation details. This produces a user-focused testing document, not a technical test plan. + +## Objective + +Generate a comprehensive User Acceptance Testing document that a non-technical stakeholder can use to verify the epic delivers its intended value. + +## Inputs + +- `epic_id`: The completed epic +- `epic_file`: Path to epic definition +- `completed_stories`: List of all story files in the epic + +## Prompt Template + +``` +You are a QA Specialist creating a User Acceptance Testing document. + +## Your Task + +Generate a UAT document for Epic: {epic_id} + +## Epic Definition + + +{epic_file_contents} + + +## Completed Stories + +{for each story} + +{story_file_contents} + +{end for} + +## Your Goal + +Create a testing document that: + +1. **Is written for humans, not developers** + - No technical jargon + - Step-by-step instructions anyone can follow + - Clear expected outcomes + +2. **Covers the user journey, not implementation** + - Focus on what users can DO, not how code works + - Scenarios flow like real usage patterns + - Test the experience, not the functions + +3. **Provides clear success criteria** + - Binary pass/fail for each scenario + - Obvious what "working" looks like + - No ambiguity in expected results + +## Output Format + +Generate the document following this structure: + +```markdown +# {Epic Title} - User Acceptance Testing + +**Epic**: {epic_id} +**Version**: 1.0 +**Generated**: {date} +**Stories Covered**: {story_count} + +--- + +## Overview + +### What Was Built +[2-3 sentences describing what this epic delivers in plain language. +Focus on user value, not technical implementation.] + +### Who Should Test +[Who is the right person to test this? What role/knowledge do they need?] + +### Time Estimate +[How long should testing take? e.g., "30-45 minutes"] + +--- + +## Prerequisites + +### Before You Begin + +1. **Environment** + - URL: {test_environment_url} + - Browser: {recommended_browser} + +2. **Test Account** + - Username: {test_username} + - Password: {test_password} + - Or: [How to create a test account] + +3. **Test Data Setup** + [Any data that needs to exist before testing] + ```bash + # If setup script needed + npm run seed:test + ``` + +4. **Clean State** + [How to reset to clean state between test runs] + +--- + +## Test Scenarios + +{Generate 3-8 scenarios that cover the epic's functionality} + +### Scenario 1: {Descriptive Name} + +**Purpose**: {What this scenario validates} + +**Starting Point**: {Where/what state to begin} + +**Steps**: + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | {Do this} | {See this} | +| 2 | {Do this} | {See this} | +| 3 | {Do this} | {See this} | + +**Success Criteria**: {One sentence summary of pass condition} + +**Result**: ☐ Pass ☐ Fail + +**Notes**: _________________________________ + +--- + +### Scenario 2: {Descriptive Name} + +[Same structure...] + +--- + +### Scenario N: {Edge Case or Error Handling} + +**Purpose**: Verify system handles errors gracefully + +**Steps**: + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | {Attempt invalid action} | {Appropriate error message} | +| 2 | {Verify no data corruption} | {System state unchanged} | + +--- + +## Success Criteria Summary + +This epic is **successful** when a user can: + +- [ ] {High-level capability 1} +- [ ] {High-level capability 2} +- [ ] {High-level capability 3} +- [ ] {Error handling works gracefully} + +**Minimum passing**: All checkboxes marked + +--- + +## Issues Log + +| # | Scenario | Issue Description | Severity | Screenshot | +|---|----------|-------------------|----------|------------| +| 1 | | | Critical/Major/Minor | | +| 2 | | | | | + +### Severity Definitions + +- **Critical**: Blocks core functionality, cannot proceed +- **Major**: Significant issue but workaround exists +- **Minor**: Cosmetic or minor inconvenience + +--- + +## Sign-off + +### Testing Summary + +| Metric | Value | +|--------|-------| +| Scenarios Tested | /__ | +| Scenarios Passed | /__ | +| Critical Issues | | +| Major Issues | | +| Minor Issues | | + +### Recommendation + +☐ **Accept** - All criteria met, ready for production +☐ **Accept with conditions** - Minor issues noted, can proceed +☐ **Reject** - Critical/major issues must be resolved + +### Signatures + +**Tested By**: _______________________ +**Date**: _______________________ + +**Approved By**: _______________________ +**Date**: _______________________ + +--- + +## Appendix + +### Test Data Reference +[Any reference data used in testing] + +### Environment Details +[Technical details if needed for troubleshooting] +``` + +## Document Location + +Save to: `docs/uat/epic-{epic_id}-uat.md` + +## Completion Signal + +Output: `UAT GENERATED: docs/uat/epic-{epic_id}-uat.md` +``` + +## Scenario Generation Guidelines + +### Good Scenarios +- Follow realistic user workflows +- Build on each other (Scenario 2 assumes Scenario 1 completed) +- Include at least one "happy path" and one "error path" +- Test the boundaries (empty inputs, maximum values, etc.) + +### Avoid +- Testing implementation details +- Requiring technical knowledge to execute +- Ambiguous expected results +- Overlapping scenarios that test the same thing + +## Synthesis from Stories + +Map story acceptance criteria to UAT scenarios: + +| Story Criterion | UAT Scenario | +|----------------|--------------| +| "User can register with email" | Scenario 1: New User Registration | +| "Invalid email shows error" | Scenario 5: Registration Validation | +| "Session persists across browser restart" | Scenario 4: Session Persistence | + +Not every criterion needs its own scenarioβ€”group related criteria into coherent user journeys. + +## Orchestration Integration + +```bash +# Completely fresh context - knows nothing about dev or review +claude -p "$(cat step-04-generate-uat.md | envsubst)" +``` diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-05-summary.md b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-05-summary.md new file mode 100644 index 000000000..d4eb049af --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/steps/step-05-summary.md @@ -0,0 +1,198 @@ +# Step 5: Execution Summary + +## Objective + +Generate a comprehensive summary of the epic execution, including statistics, any issues encountered, and next steps. + +## Inputs + +- `epic_id`: The executed epic +- Execution log from shell script +- All story files (with their final status) +- UAT document location + +## Prompt Template + +``` +You are summarizing the execution of Epic: {epic_id} + +## Execution Data + + +{execution_log_contents} + + +## Story Final States + +{for each story} + +### Dev Agent Record +{dev_agent_record} + +### Code Review Record +{code_review_record} + +{end for} + +## Generate Execution Report + +Create: `docs/sprints/epic-{epic_id}-execution.md` + +```markdown +# Epic {epic_id} Execution Report + +**Executed**: {timestamp} +**Duration**: {total_time} +**Mode**: Automated (BMAD epic-execute) + +--- + +## Summary + +| Metric | Value | +|--------|-------| +| Total Stories | {count} | +| Completed | {count} | +| Blocked | {count} | +| Failed | {count} | +| Total Commits | {count} | +| Lines Added | {count} | +| Lines Removed | {count} | +| Tests Added | {count} | + +## Execution Timeline + +| Time | Story | Phase | Result | Duration | +|------|-------|-------|--------|----------| +| {time} | story-1.1 | Dev | Complete | {duration} | +| {time} | story-1.1 | Review | Passed | {duration} | +| {time} | story-1.1 | Commit | Success | - | +| {time} | story-1.2 | Dev | Complete | {duration} | +| ... | ... | ... | ... | ... | + +## Stories Completed + +### story-{epic_id}.1 - {title} +- **Status**: Done βœ“ +- **Files Changed**: {count} +- **Tests Added**: {count} +- **Review**: Passed on first attempt + +### story-{epic_id}.2 - {title} +- **Status**: Done βœ“ +- **Files Changed**: {count} +- **Tests Added**: {count} +- **Review**: Passed with fixes (minor style issues) + +{continue for each story} + +## Issues Encountered + +### Resolved During Execution + +| Story | Phase | Issue | Resolution | +|-------|-------|-------|------------| +| story-1.2 | Review | Missing input validation | Added validation, re-reviewed | +| story-1.4 | Dev | Test flakiness | Fixed timing issue | + +### Unresolved (Requires Human Attention) + +| Story | Phase | Issue | Impact | +|-------|-------|-------|--------| +| {story} | {phase} | {description} | {impact} | + +## Code Quality Summary + +### Patterns Used +- [Patterns established or followed during implementation] + +### Technical Debt Introduced +- [Any shortcuts taken that should be addressed later] + +### Recommendations +- [Suggestions for future development] + +## Test Coverage + +| Area | Before | After | Delta | +|------|--------|-------|-------| +| Statements | {%} | {%} | +{%} | +| Branches | {%} | {%} | +{%} | +| Functions | {%} | {%} | +{%} | +| Lines | {%} | {%} | +{%} | + +## Deliverables + +| Artifact | Location | Status | +|----------|----------|--------| +| Completed Stories | docs/stories/ | βœ“ | +| Handoff Notes | docs/handoff/ | βœ“ | +| UAT Document | docs/uat/epic-{epic_id}-uat.md | βœ“ | +| This Report | docs/sprints/epic-{epic_id}-execution.md | βœ“ | + +## Next Steps + +1. **Human Testing**: Execute UAT document at `docs/uat/epic-{epic_id}-uat.md` +2. **Address Issues**: {count} items need human review +3. **Merge**: Once UAT passes, merge to main branch +4. **Deploy**: Follow deployment checklist + +--- + +## Git Log + +``` +{git log --oneline for this epic's commits} +``` + +--- + +*Generated by BMAD epic-execute workflow* +``` + +## Completion Signal + +Output: `EPIC EXECUTION COMPLETE: {epic_id}` +``` + +## Orchestration Integration + +This step can run in the same context as the shell script wrap-up, or as a final isolated context. + +```bash +# Generate summary +claude -p "$(cat step-05-summary.md | envsubst)" + +# Final output +echo "" +echo "==========================================" +echo "Epic $EPIC_ID execution complete" +echo "==========================================" +echo "" +echo "Deliverables:" +echo " - Stories: docs/stories/" +echo " - UAT: docs/uat/epic-${EPIC_ID}-uat.md" +echo " - Report: docs/sprints/epic-${EPIC_ID}-execution.md" +echo "" +echo "Next: Run UAT with a human tester" +echo "" +``` + +## Cleanup + +After summary generation: + +1. Remove temporary handoff files (optional): + ```bash + rm -f docs/handoff/*-dev.md + ``` + +2. Archive execution log: + ```bash + mv /tmp/epic-${EPIC_ID}-log.txt docs/sprints/ + ``` + +3. Update sprint status if applicable: + ```bash + # Mark stories as done in sprint tracker + ``` diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/templates/uat-template.md b/src/modules/bmm/workflows/4-implementation/epic-execute/templates/uat-template.md new file mode 100644 index 000000000..e23866a91 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/templates/uat-template.md @@ -0,0 +1,167 @@ +# {{epic_title}} - User Acceptance Testing + +**Epic**: {{epic_id}} +**Version**: 1.0 +**Generated**: {{date}} +**Stories Covered**: {{story_count}} + +--- + +## Overview + +### What Was Built + +{{epic_summary}} + +### Who Should Test + +{{tester_profile}} + +### Time Estimate + +{{time_estimate}} + +--- + +## Prerequisites + +### Before You Begin + +1. **Environment** + - URL: {{test_url}} + - Browser: Chrome (recommended) or Firefox + +2. **Test Account** + - {{test_account_instructions}} + +3. **Test Data Setup** + {{test_data_setup}} + +4. **Clean State** + {{clean_state_instructions}} + +--- + +## Test Scenarios + +{{#each scenarios}} + +### Scenario {{number}}: {{name}} + +**Purpose**: {{purpose}} + +**Starting Point**: {{starting_point}} + +**Steps**: + +| Step | Action | Expected Result | +|------|--------|-----------------| +{{#each steps}} +| {{step_number}} | {{action}} | {{expected}} | +{{/each}} + +**Success Criteria**: {{success_summary}} + +**Result**: ☐ Pass ☐ Fail + +**Notes**: _________________________________ + +--- + +{{/each}} + +## Edge Cases & Error Handling + +{{#each edge_cases}} + +### {{name}} + +**Purpose**: {{purpose}} + +| Step | Action | Expected Result | +|------|--------|-----------------| +{{#each steps}} +| {{step_number}} | {{action}} | {{expected}} | +{{/each}} + +**Result**: ☐ Pass ☐ Fail + +--- + +{{/each}} + +## Success Criteria Summary + +This epic is **successful** when a user can: + +{{#each success_criteria}} +- [ ] {{criterion}} +{{/each}} + +**Minimum passing**: All checkboxes marked + +--- + +## Issues Log + +| # | Scenario | Issue Description | Severity | Screenshot | +|---|----------|-------------------|----------|------------| +| 1 | | | | | +| 2 | | | | | +| 3 | | | | | + +### Severity Definitions + +- **Critical**: Blocks core functionality, cannot proceed +- **Major**: Significant issue but workaround exists +- **Minor**: Cosmetic or minor inconvenience + +--- + +## Sign-off + +### Testing Summary + +| Metric | Value | +|--------|-------| +| Scenarios Tested | __ / __ | +| Scenarios Passed | __ / __ | +| Critical Issues | | +| Major Issues | | +| Minor Issues | | + +### Recommendation + +☐ **Accept** - All criteria met, ready for production +☐ **Accept with conditions** - Minor issues noted, can proceed +☐ **Reject** - Critical/major issues must be resolved + +### Signatures + +| Role | Name | Date | Signature | +|------|------|------|-----------| +| Tester | | | | +| Product Owner | | | | +| Tech Lead | | | | + +--- + +## Appendix + +### Test Data Reference + +{{test_data_reference}} + +### Environment Details + +{{environment_details}} + +### Related Documentation + +- Epic: `docs/epics/epic-{{epic_id}}.md` +- Architecture: `docs/architecture.md` +- Stories: `docs/stories/story-{{epic_id}}.*` + +--- + +*Generated by BMAD epic-execute workflow* diff --git a/src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md b/src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md new file mode 100644 index 000000000..25efbe600 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md @@ -0,0 +1,138 @@ +# Epic Execute Workflow + +## Metadata + +| Field | Value | +|-------|-------| +| Version | 1.0.0 | +| Trigger | `epic-execute` | +| Agent | SM (Scrum Master) | +| Category | Implementation | +| Complexity | High | + +## Purpose + +Automatically execute all stories in an epic sequentially with context isolation between development and review phases, then generate a User Acceptance Testing document for human validation. + +## Prerequisites + +- Epic file exists with defined stories +- Story files created (at minimum: title, acceptance criteria, technical context) +- Architecture document available for reference +- Git repository initialized + +## Workflow Phases + +This workflow orchestrates multiple isolated agent sessions: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ EPIC EXECUTE FLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Phase 1 β”‚ β”‚ Phase 2 β”‚ β”‚ Phase 3 β”‚ β”‚ +β”‚ β”‚ Dev │───►│ Review │───►│ Commit β”‚ β”‚ +β”‚ β”‚ (Context A)β”‚ β”‚ (Context B) β”‚ β”‚ (Shell) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ └──────────── Per Story Loop β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Phase 4 β”‚ β”‚ +β”‚ β”‚ UAT Generation (Context C) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Steps + +| Step | File | Description | +|------|------|-------------| +| 1 | step-01-init.md | Discover epic and validate stories | +| 2 | step-02-dev-story.md | Development phase prompt (isolated context) | +| 3 | step-03-code-review.md | Review phase prompt (isolated context) | +| 4 | step-04-generate-uat.md | UAT document generation (isolated context) | +| 5 | step-05-summary.md | Final execution summary | + +## Outputs + +| Output | Location | Description | +|--------|----------|-------------| +| Updated Stories | `docs/stories/` | Stories marked Done with Dev Agent Records and Code Review Records | +| UAT Document | `docs/uat/epic-{id}-uat.md` | Human testing script | +| Execution Log | `docs/sprints/epic-{id}-execution.md` | Run summary | + +## Issue Fix Policy + +During code review, issues are categorized by severity and fixed based on thresholds: + +| Severity | Criteria | Action | +|----------|----------|--------| +| **HIGH** | Security, missing error handling, no tests, exposed secrets | Always fix | +| **MEDIUM** | Pattern violations, missing edge cases, hardcoded config | Fix if total issues > 5 | +| **LOW** | Naming, style, missing comments | Document only | + +This ensures critical issues are always resolved while avoiding over-engineering on minor items. + +## Orchestration Script + +This workflow requires shell orchestration to clear context between phases. +See: `scripts/epic-execute.sh` + +## Usage + +```bash +# From project root +./bmad/scripts/epic-execute.sh + +# Example +./bmad/scripts/epic-execute.sh 1 +``` + +Or invoke steps manually: + +``` +/sm +*epic-execute 1 +``` + +When invoked via agent, SM will guide through setup then provide the shell command. + +## Configuration + +Optional settings in `bmad/_cfg/epic-execute.yaml`: + +```yaml +# Auto-commit after each story (default: true) +auto_commit: true + +# Run tests before review (default: true) +run_tests_before_review: true + +# Generate handoff notes between phases (default: true) +generate_handoffs: true + +# Parallel story execution for independent stories (default: false) +parallel_execution: false + +# Review strictness: lenient | standard | strict +review_mode: standard +``` + +## Error Handling + +| Scenario | Behavior | +|----------|----------| +| Dev fails to complete | Log failure, skip to next story, mark blocked | +| Review finds critical issues | Attempt fix, re-review once, then flag for human | +| Tests fail | Attempt fix, re-run, fail after 3 attempts | +| Story dependency not met | Skip story, continue, report in summary | + +## Notes + +- Each phase runs in isolated Claude context for clean separation +- Git staging passes code between contexts (not context window) +- Story files pass notes between contexts (Dev Agent Record section) +- Human intervention only required at UAT testing phase