claude-flow-novice 2.14.37 → 2.15.1

package/.claude/skills/cfn-docker-loop-orchestration/orchestrate.sh

@@ -22,23 +22,23 @@ PURPLE='\033[0;35m'
 NC='\033[0m'
 
 log() {
-    echo -e "${BLUE}[$(date '+%H:%M:%S')]${NC} $*"
+    echo -e "${BLUE}[$(date '+%H:%M:%S')]${NC} $*" >&2
 }
 
 log_success() {
-    echo -e "${GREEN}[SUCCESS]${NC} $*"
+    echo -e "${GREEN}[SUCCESS]${NC} $*" >&2
 }
 
 log_error() {
-    echo -e "${RED}[ERROR]${NC} $*"
+    echo -e "${RED}[ERROR]${NC} $*" >&2
 }
 
 log_warning() {
-    echo -e "${YELLOW}[WARNING]${NC} $*"
+    echo -e "${YELLOW}[WARNING]${NC} $*" >&2
 }
 
 log_loop() {
-    echo -e "${PURPLE}[LOOP]${NC} $*"
+    echo -e "${PURPLE}[LOOP]${NC} $*" >&2
 }
 
 # Function to display usage
@@ -61,6 +61,11 @@ Operations:
   monitor-progress      Monitor overall loop progress
   validate-deliverables Validate required deliverables
   handle-error          Handle execution errors
+  execute-waves         Execute complete wave-based execution (Mode A)
+  spawn-wave            Spawn specific wave of containers
+  monitor-wave          Monitor wave container completion
+  cleanup-wave          Remove wave containers and artifacts
+  validate-errors       Run error validation and count results
 
 Options:
   --task-description TEXT    Task description
@@ -84,6 +89,11 @@ Examples:
   $0 spawn-loop3 --task-id task-auth --agents backend-developer,frontend-engineer,security-specialist
   $0 monitor-loop3 --task-id task-auth --gate-threshold 0.80
   $0 collect-consensus --task-id task-auth --required-consensus 0.90
+  $0 execute-waves --task-id task-fix --batching-plan /tmp/waves.json
+  $0 spawn-wave --task-id task-fix --wave-number 1 --batching-plan /tmp/waves.json
+  $0 monitor-wave --task-id task-fix --wave-number 1 --expected-count 28
+  $0 cleanup-wave --task-id task-fix --wave-number 1
+  $0 validate-errors --task-id task-fix --command "tsc --noEmit"
 
 EOF
 }
@@ -115,6 +125,13 @@ PROJECT_ROOT="$(cd "$(dirname "$SCRIPT_DIR")/../.." && pwd)"
 # Path to skills
 REDIS_COORDINATION_SKILL="$PROJECT_ROOT/.claude/skills/cfn-docker-redis-coordination/coordinate.sh"
 AGENT_SPAWNING_SKILL="$PROJECT_ROOT/.claude/skills/cfn-docker-agent-spawning/spawn-agent.sh"
+WAVE_EXECUTION_SKILL="$PROJECT_ROOT/.claude/skills/cfn-docker-wave-execution"
+WAVE_SPAWN_SCRIPT="$WAVE_EXECUTION_SKILL/spawn-wave.sh"
+WAVE_HELPERS="$WAVE_EXECUTION_SKILL/lib/docker-helpers.sh"
+WAVE_CHECKPOINT_SKILL="$PROJECT_ROOT/.claude/skills/cfn-wave-checkpoint"
+CHECKPOINT_SAVE_SCRIPT="$WAVE_CHECKPOINT_SKILL/save-checkpoint.sh"
+CHECKPOINT_RESUME_SCRIPT="$WAVE_CHECKPOINT_SKILL/resume-wave.sh"
+CHECKPOINT_CLEANUP_SCRIPT="$WAVE_CHECKPOINT_SKILL/cleanup-orphans.sh"
 
 # Parse command line arguments
 OPERATION=""
@@ -134,6 +151,12 @@ FORCE_ITERATION=""
 DRY_RUN=false
 VERBOSE=false
 
+# Mode A: Wave execution parameters
+BATCHING_PLAN=""
+WAVE_NUMBER=""
+EXPECTED_COUNT=""
+VALIDATION_COMMAND=""
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         --task-description)
@@ -192,6 +215,22 @@ while [[ $# -gt 0 ]]; do
             VERBOSE=true
             shift
             ;;
+        --batching-plan)
+            BATCHING_PLAN="$2"
+            shift 2
+            ;;
+        --wave-number)
+            WAVE_NUMBER="$2"
+            shift 2
+            ;;
+        --expected-count)
+            EXPECTED_COUNT="$2"
+            shift 2
+            ;;
+        --command)
+            VALIDATION_COMMAND="$2"
+            shift 2
+            ;;
         --help)
             usage
             exit 0
@@ -243,12 +282,167 @@ for dependency in "$REDIS_COORDINATION_SKILL" "$AGENT_SPAWNING_SKILL"; do
     fi
 done
 
+# Validate Docker agent image exists
+AGENT_IMAGE="${AGENT_IMAGE:-claude-flow-novice-agent:latest}"
+if ! docker image inspect "$AGENT_IMAGE" &>/dev/null; then
+    log_error "Required Docker image not found: $AGENT_IMAGE"
+    log_error "Please build the image first or set AGENT_IMAGE environment variable"
+    exit 1
+fi
+log "Using agent image: $AGENT_IMAGE"
+
 # Change to project root
 cd "$PROJECT_ROOT"
 
 # Operation implementations
+
+# Planning phase: Decompose task into atomic units
+plan_task() {
+    local task_description="$1"
+    local task_id="$2"
+
+    if [[ -z "$task_description" ]]; then
+        log_error "Task description is required for planning"
+        return 1
+    fi
+
+    log "Planning phase: Decomposing task into atomic units"
+    log "Task: $task_description"
+
+    # Create plan file
+    local plan_file="/tmp/cfn-docker-plan-${task_id}.json"
+
+    # Check if plan file already exists (from pre-planning)
+    if [[ -f "$plan_file" ]]; then
+        log "Using existing plan file: $plan_file"
+
+        # Validate plan structure
+        if ! jq -e '.atomic_tasks' "$plan_file" > /dev/null 2>&1; then
+            log_error "Invalid existing plan format: missing atomic_tasks"
+            return 1
+        fi
+
+        log_success "Task planning complete: $(jq -r '.atomic_tasks | length' "$plan_file") atomic tasks"
+
+        # Extract agent assignments from plan
+        local agents
+        agents=$(jq -r '.atomic_tasks[].agent_type' "$plan_file" | sort -u | tr '\n' ' ')
+        echo "$agents"
+        return 0
+    fi
+
+    # Generate plan via LLM API call (for Docker mode)
+    if [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
+        log "Generating plan via Anthropic API..."
+
+        # Create planning prompt
+        local planning_prompt="You are a task planning expert. Decompose this task into atomic units for parallel execution.
+
+Task: ${task_description}
+
+Requirements:
+1. Break task into 15-30 minute atomic units
+2. Each atomic task should have: description, estimated time, dependencies, agent type, deliverables
+3. Agent types available: backend-developer, react-frontend-engineer, security-specialist, tester, reviewer, devops-engineer
+4. Assign 1 atomic task per agent (2-3 max if shared context helps)
+5. Identify which tasks can run in parallel vs sequential
+6. Use simple dependency notation: [] for no dependencies, [\"task-1\"] for dependencies
+
+Output ONLY valid JSON in this exact format:
+{
+  \"atomic_tasks\": [
+    {
+      \"id\": \"task-1\",
+      \"description\": \"Implement JWT token generation middleware\",
+      \"estimated_time\": \"20 min\",
+      \"dependencies\": [],
+      \"agent_type\": \"backend-developer\",
+      \"deliverables\": [\"src/middleware/jwt.ts\", \"tests\"]
+    }
+  ],
+  \"execution_phases\": {
+    \"phase_1_parallel\": [\"task-1\", \"task-3\"],
+    \"phase_2_sequential\": [\"task-2\"]
+  }
+}"
+
+        # Call Anthropic API
+        local api_response
+        api_response=$(curl -s -X POST https://api.anthropic.com/v1/messages \
+            -H "x-api-key: ${ANTHROPIC_API_KEY}" \
+            -H "anthropic-version: 2023-06-01" \
+            -H "content-type: application/json" \
+            -d "{
+                \"model\": \"claude-sonnet-4-20250514\",
+                \"max_tokens\": 2048,
+                \"messages\": [{
+                    \"role\": \"user\",
+                    \"content\": $(echo "$planning_prompt" | jq -Rs .)
+                }]
+            }")
+
+        # Extract plan from response
+        local plan_content
+        plan_content=$(echo "$api_response" | jq -r '.content[0].text' 2>/dev/null)
+
+        if [[ -z "$plan_content" || "$plan_content" == "null" ]]; then
+            log_error "Failed to get plan from API"
+            log_warning "API response: $(echo "$api_response" | head -100)"
+            return 1
+        fi
+
+        # Clean JSON (remove markdown code blocks if present)
+        plan_content=$(echo "$plan_content" | sed -n '/^{/,/^}/p')
+
+        # Save plan file
+        echo "$plan_content" > "$plan_file"
+
+        # Validate plan structure
+        if ! jq -e '.atomic_tasks' "$plan_file" > /dev/null 2>&1; then
+            log_error "Invalid plan format from API: missing atomic_tasks"
+            log_warning "Plan content: $(cat "$plan_file" | head -50)"
+            return 1
+        fi
+
+        log_success "Task planning complete via API: $(jq -r '.atomic_tasks | length' "$plan_file") atomic tasks"
+
+        # Extract agent assignments from plan
+        local agents
+        agents=$(jq -r '.atomic_tasks[].agent_type' "$plan_file" | sort -u | tr '\n' ' ')
+        echo "$agents"
+        return 0
+    fi
+
+    # No API key - wait for external plan file (Task mode)
+    log_warning "No ANTHROPIC_API_KEY found, waiting for external plan file..."
+    local wait_count=0
+    while [[ ! -f "$plan_file" && $wait_count -lt 30 ]]; do
+        sleep 1
+        ((wait_count++))
+    done
+
+    if [[ ! -f "$plan_file" ]]; then
+        log_warning "No plan file created, falling back to analyze_task"
+        return 1
+    fi
+
+    # Validate plan structure
+    if ! jq -e '.atomic_tasks' "$plan_file" > /dev/null 2>&1; then
+        log_error "Invalid plan format: missing atomic_tasks"
+        return 1
+    fi
+
+    log_success "Task planning complete: $(jq -r '.atomic_tasks | length' "$plan_file") atomic tasks"
+
+    # Extract agent assignments from plan
+    local agents
+    agents=$(jq -r '.atomic_tasks[].agent_type' "$plan_file" | sort -u | tr '\n' ' ')
+    echo "$agents"
+}
+
 analyze_task() {
     local task_description="$1"
+    local task_id="${2:-}"
 
     if [[ -z "$task_description" ]]; then
         log_error "Task description is required for task analysis"
@@ -257,7 +451,18 @@ analyze_task() {
 
     log "Analyzing task: $task_description"
 
-    # Simple keyword-based agent selection (can be enhanced with ML)
+    # Try planning first if task_id provided
+    if [[ -n "$task_id" ]]; then
+        local planned_agents
+        if planned_agents=$(plan_task "$task_description" "$task_id" 2>/dev/null); then
+            log "Using planned agent assignments: $planned_agents"
+            echo "$planned_agents"
+            return 0
+        fi
+    fi
+
+    # Fallback: Simple keyword-based agent selection
+    log_warning "Using fallback keyword-based agent selection"
     local selected_agents=()
 
     if [[ "$task_description" =~ (frontend|ui|user.interface|react|vue|angular) ]]; then
@@ -345,40 +550,66 @@ spawn_loop3() {
     log_loop "Spawning Loop 3 implementers (iteration $iteration)"
     log "Agents: $agents"
 
-    # Store task context for agents
-    local context_file="/tmp/task-context-${task_id}-loop3-${iteration}.json"
+    # Check for execution plan
+    local plan_file="/tmp/cfn-docker-plan-${task_id}.json"
+    local has_plan=false
+    if [[ -f "$plan_file" ]] && jq -e '.atomic_tasks' "$plan_file" > /dev/null 2>&1; then
+        has_plan=true
+        log "Using execution plan with $(jq -r '.atomic_tasks | length' "$plan_file") atomic tasks"
+    fi
 
-    # Create enhanced context with loop information
-    cat > "$context_file" << EOF
+    # Spawn agents
+    IFS=',' read -ra AGENT_ARRAY <<< "$agents"
+    local agent_ids=()
+    local task_index=0
+
+    for agent_type in "${AGENT_ARRAY[@]}"; do
+        agent_type=$(echo "$agent_type" | xargs)  # trim whitespace
+
+        # Get atomic task assignment from plan (if available)
+        local atomic_task_desc="$TASK_DESCRIPTION"
+        local atomic_task_deliverables=""
+
+        if [[ "$has_plan" == true ]]; then
+            # Find atomic tasks assigned to this agent type
+            atomic_task_desc=$(jq -r ".atomic_tasks[] | select(.agent_type == \"$agent_type\") | .description" "$plan_file" | head -1)
+            atomic_task_deliverables=$(jq -r ".atomic_tasks[] | select(.agent_type == \"$agent_type\") | .deliverables | join(\", \")" "$plan_file" | head -1)
+
+            if [[ -n "$atomic_task_desc" && "$atomic_task_desc" != "null" ]]; then
+                log "Atomic task for $agent_type: $atomic_task_desc"
+            else
+                log_warning "No atomic task found in plan for $agent_type, using full task description"
+                atomic_task_desc="$TASK_DESCRIPTION"
+            fi
+        fi
+
+        # Store task context for this specific agent
+        local context_file="/tmp/task-context-${task_id}-loop3-${iteration}-${agent_type}.json"
+
+        # Create enhanced context with atomic task assignment
+        cat > "$context_file" << EOF
 {
   "task_id": "$task_id",
   "loop_number": 3,
   "iteration": $iteration,
   "mode": "$MODE",
   "role": "implementer",
-  "task_description": "$TASK_DESCRIPTION",
+  "agent_type": "$agent_type",
+  "atomic_task": "$atomic_task_desc",
+  "expected_deliverables": "$atomic_task_deliverables",
   "gate_threshold": $GATE_THRESHOLD,
   "max_iterations": $MAX_ITERATIONS,
-  "instructions": "Implement the required solution according to the task description. Focus on creating working, high-quality code that meets the acceptance criteria. Report your confidence in the implementation (0.0-1.0).",
+  "instructions": "Complete your assigned atomic task (15-30 min scope). Focus on: $atomic_task_desc. Deliver working, tested code. Report confidence (0.0-1.0).",
   "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 }
 EOF
 
-    # Get task context from Redis if available
-    if [[ -n "$CONTEXT_FILE" ]]; then
-        # Merge with existing context
-        local merged_context=$(jq -s '.[0] * .[1]' "$CONTEXT_FILE" "$context_file")
-        echo "$merged_context" > "$context_file"
-    fi
-
-    # Spawn agents
-    IFS=',' read -ra AGENT_ARRAY <<< "$agents"
-    local agent_ids=()
-
-    for agent_type in "${AGENT_ARRAY[@]}"; do
-        agent_type=$(echo "$agent_type" | xargs)  # trim whitespace
-
-        log "Spawning agent: $agent_type"
+        # Get task context from Redis if available
+        if [[ -n "$CONTEXT_FILE" ]]; then
+            # Merge with existing context
+            local merged_context=$(jq -s '.[0] * .[1]' "$CONTEXT_FILE" "$context_file")
+            echo "$merged_context" > "$context_file"
+        fi
 
         if [[ "$DRY_RUN" == false ]]; then
             local agent_id
@@ -386,10 +617,9 @@ EOF
                 "$agent_type" \
                 "$task_id" \
                 "" \
-                --context-file "$context_file" \
+                --context "$context_file" \
                 --memory-limit "${MEMORY_LIMIT:-1g}" \
-                --network "${NETWORK:-mcp-network}" \
-                --mcp-auto-select 2>&1 | grep -o 'Agent ID: [^[:space:]]*' | cut -d' ' -f3)
+                --network "${NETWORK:-mcp-network}" 2>&1 | grep -o '^Agent ID: [^[:space:]]*' | cut -d' ' -f3)
 
             if [[ -n "$agent_id" ]]; then
                 agent_ids+=("$agent_id")
@@ -403,12 +633,19 @@ EOF
                 log_success "Agent spawned: $agent_id ($agent_type)"
             else
                 log_error "Failed to spawn agent: $agent_type"
+                return 1
             fi
         else
             log "DRY RUN: Would spawn agent: $agent_type"
         fi
     done
 
+    # Validate agents were spawned successfully
+    if [[ "$DRY_RUN" == false && ${#agent_ids[@]} -eq 0 ]]; then
+        log_error "No agents were spawned successfully"
+        return 1
+    fi
+
     if [[ "$DRY_RUN" == false && ${#agent_ids[@]} -gt 0 ]]; then
         log_loop "Loop 3 agents spawned: ${#agent_ids[@]} agents"
         # Store agent IDs for monitoring
@@ -558,10 +795,9 @@ EOF
                 "$validator_type" \
                 "$task_id" \
                 "" \
-                --context-file "$context_file" \
+                --context "$context_file" \
                 --memory-limit "${MEMORY_LIMIT:-1g}" \
-                --network "${NETWORK:-mcp-network}" \
-                --mcp-auto-select 2>&1 | grep -o 'Agent ID: [^[:space:]]*' | cut -d' ' -f3)
+                --network "${NETWORK:-mcp-network}" 2>&1 | grep -o '^Agent ID: [^[:space]]*' | cut -d' ' -f3)
 
             if [[ -n "$validator_id" ]]; then
                 validator_ids+=("$validator_id")
@@ -662,9 +898,9 @@ EOF
             "product-owner" \
             "$task_id" \
             "" \
-            --context-file "$context_file" \
+            --context "$context_file" \
             --memory-limit "${MEMORY_LIMIT:-1g}" \
-            --network "${NETWORK:-mcp-network}" 2>&1 | grep -o 'Agent ID: [^[:space:]]*' | cut -d' ' -f3)
+            --network "${NETWORK:-mcp-network}" 2>&1 | grep -o '^Agent ID: [^[:space:]]*' | cut -d' ' -f3)
 
         if [[ -n "$po_id" ]]; then
             log_success "Product Owner spawned: $po_id"
@@ -694,6 +930,475 @@ EOF
     rm -f "$context_file"
 }
 
+################################################################################
+# MEMORY BUDGET VALIDATION
+################################################################################
+
+validate_memory_budget() {
+    local batching_plan="$1"
+
+    if [[ ! -f "$batching_plan" ]]; then
+        log_error "Batching plan not found: $batching_plan"
+        return 1
+    fi
+
+    # Parse available Docker memory
+    local available_memory
+    available_memory=$(docker info --format '{{.MemTotal}}' 2>/dev/null || echo "0")
+
+    if [[ "$available_memory" -eq 0 ]]; then
+        log_warning "Cannot determine Docker memory - skipping memory validation"
+        return 0
+    fi
+
+    # Calculate required memory from plan
+    local total_memory=0
+    local wave_count
+    wave_count=$(jq '.waves | length' "$batching_plan" 2>/dev/null || echo "0")
+
+    for wave_idx in $(seq 0 $((wave_count - 1))); do
+        local containers_in_wave
+        containers_in_wave=$(jq ".waves[$wave_idx].batch_count // 0" "$batching_plan" 2>/dev/null || echo "0")
+
+        # Default memory per container (512MB)
+        local memory_per_container=$((512 * 1024 * 1024))
+
+        # Check for tier-specific memory
+        local tier
+        tier=$(jq ".waves[$wave_idx].tier // 1" "$batching_plan" 2>/dev/null || echo "1")
+
+        case "$tier" in
+            1) memory_per_container=$((512 * 1024 * 1024)) ;;
+            2) memory_per_container=$((600 * 1024 * 1024)) ;;
+            3) memory_per_container=$((800 * 1024 * 1024)) ;;
+            4) memory_per_container=$((1024 * 1024 * 1024)) ;;
+        esac
+
+        local wave_memory=$((containers_in_wave * memory_per_container))
+        total_memory=$((total_memory + wave_memory))
+
+        log "Wave $((wave_idx + 1)): $containers_in_wave containers × $((memory_per_container / 1024 / 1024))MB = $((wave_memory / 1024 / 1024))MB"
+    done
+
+    # Compare with available memory
+    local total_memory_gb=$((total_memory / 1024 / 1024 / 1024))
+    local available_memory_gb=$((available_memory / 1024 / 1024 / 1024))
+
+    log "Memory validation: Required $total_memory_gb GB / Available $available_memory_gb GB"
+
+    if [[ $total_memory -gt $available_memory ]]; then
+        log_error "Insufficient memory: Required $total_memory_gb GB exceeds available $available_memory_gb GB"
+        return 1
+    fi
+
+    log_success "Memory validation passed"
+    return 0
+}
+
+################################################################################
+# CHECKPOINT MANAGEMENT
+################################################################################
+
+check_checkpoint_recovery() {
+    local task_id="$1"
+
+    if [[ -z "$task_id" ]]; then
+        log_error "check_checkpoint_recovery requires: task_id"
+        return 1
+    fi
+
+    if [[ ! -x "$CHECKPOINT_RESUME_SCRIPT" ]]; then
+        log_warning "Checkpoint recovery script not found: $CHECKPOINT_RESUME_SCRIPT"
+        return 1
+    fi
+
+    log "Checking for existing checkpoints for task: $task_id"
+
+    # Source the resume script functions
+    source "$CHECKPOINT_RESUME_SCRIPT" 2>/dev/null || {
+        log_warning "Failed to source checkpoint resume script"
+        return 1
+    }
+
+    # Check if resumable waves exist
+    if get_resumable_waves "$task_id" > /tmp/resumable_waves.txt 2>/dev/null; then
+        local wave_count
+        wave_count=$(wc -l < /tmp/resumable_waves.txt)
+
+        if [[ $wave_count -gt 0 ]]; then
+            log_success "Found $wave_count checkpoint(s) for recovery"
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+resume_from_checkpoint() {
+    local task_id="$1"
+
+    if [[ -z "$task_id" ]]; then
+        log_error "resume_from_checkpoint requires: task_id"
+        return 1
+    fi
+
+    if [[ ! -x "$CHECKPOINT_RESUME_SCRIPT" ]]; then
+        log_error "Checkpoint recovery script not found: $CHECKPOINT_RESUME_SCRIPT"
+        return 1
+    fi
+
+    log "Attempting to resume from checkpoint for task: $task_id"
+
+    # Call resume script
+    if "$CHECKPOINT_RESUME_SCRIPT" resume "$task_id"; then
+        log_success "Successfully resumed from checkpoint"
+        return 0
+    else
+        log_error "Failed to resume from checkpoint"
+        return 1
+    fi
+}
+
+save_wave_checkpoint() {
+    local task_id="$1"
+    local wave_number="$2"
+    local container_ids="$3"
+    local batch_count="$4"
+
+    if [[ -z "$task_id" ]] || [[ -z "$wave_number" ]] || [[ -z "$container_ids" ]]; then
+        log_warning "Invalid checkpoint parameters, skipping checkpoint save"
+        return 0  # Non-fatal
+    fi
+
+    if [[ ! -x "$CHECKPOINT_SAVE_SCRIPT" ]]; then
+        log_warning "Checkpoint save script not found, skipping checkpoint"
+        return 0  # Non-fatal
+    fi
+
+    log "Saving checkpoint for wave $wave_number"
+
+    # Call save script
+    if "$CHECKPOINT_SAVE_SCRIPT" \
+        save "$task_id" "$wave_number" "$container_ids" "$(date +%s)" "$batch_count" >/dev/null 2>&1; then
+        log_success "Checkpoint saved for wave $wave_number"
+        return 0
+    else
+        log_warning "Failed to save checkpoint (execution will continue)"
+        return 0  # Non-fatal
+    fi
+}
+
+cleanup_orphaned_containers() {
+    local task_id="$1"
+    local wave_number="${2:-}"
+
+    if [[ -z "$task_id" ]]; then
+        log_error "cleanup_orphaned_containers requires: task_id"
+        return 1
+    fi
+
+    if [[ ! -x "$CHECKPOINT_CLEANUP_SCRIPT" ]]; then
+        log_warning "Checkpoint cleanup script not found, skipping orphan cleanup"
+        return 0
+    fi
+
+    log "Cleaning up orphaned containers for task: $task_id"
+
+    if [[ -z "$wave_number" ]]; then
+        # Cleanup all waves
+        if "$CHECKPOINT_CLEANUP_SCRIPT" cleanup "$task_id" >/dev/null 2>&1; then
+            log_success "Orphan cleanup completed"
+            return 0
+        fi
+    else
+        # Cleanup specific wave
+        if "$CHECKPOINT_CLEANUP_SCRIPT" cleanup "$task_id" "$wave_number" >/dev/null 2>&1; then
+            log_success "Orphan cleanup completed for wave $wave_number"
+            return 0
+        fi
+    fi
+
+    log_warning "Orphan cleanup encountered errors (non-fatal)"
+    return 0
+}
+
+# Mode A: Wave Execution Operations
+
+spawn_wave() {
+    local task_id="$1"
+    local wave_number="$2"
+    local plan_file="$3"
+
+    if [[ -z "$task_id" ]] || [[ -z "$wave_number" ]] || [[ -z "$plan_file" ]]; then
+        log_error "spawn_wave requires: task_id, wave_number, plan_file"
+        return 1
+    fi
+
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Batching plan not found: $plan_file"
+        return 1
+    fi
+
+    log "Spawning wave $wave_number for task: $task_id"
+
+    # Validate plan has expected wave
+    if ! jq -e ".waves[$((wave_number - 1))]" "$plan_file" > /dev/null 2>&1; then
+        log_error "Wave $wave_number not found in plan"
+        return 1
+    fi
+
+    # Call wave-execution skill
+    if [[ ! -x "$WAVE_SPAWN_SCRIPT" ]]; then
+        log_error "Wave spawn script not found or not executable: $WAVE_SPAWN_SCRIPT"
+        return 1
+    fi
+
+    # Spawn containers for this wave
+    local output_file="/tmp/cfn-wave-${task_id}-${wave_number}-spawned.json"
+    if "$WAVE_SPAWN_SCRIPT" \
+        --wave-plan "$plan_file" \
+        --wave-number "$wave_number" \
+        --base-image "claude-flow-novice:latest" \
+        --workspace "$PROJECT_ROOT" \
+        --network "${NETWORK:-mcp-network}" \
+        --output "$output_file"; then
+
+        log_success "Wave $wave_number spawned successfully"
+
+        # Output spawned container IDs for tracking
+        if [[ -f "$output_file" ]]; then
+            cat "$output_file"
+        fi
+        return 0
+    else
+        log_error "Failed to spawn wave $wave_number"
+        return 1
+    fi
+}
+
+monitor_wave() {
+    local task_id="$1"
+    local wave_number="$2"
+    local expected_count="$3"
+
+    if [[ -z "$task_id" ]] || [[ -z "$wave_number" ]]; then
+        log_error "monitor_wave requires: task_id, wave_number"
+        return 1
+    fi
+
+    log "Monitoring wave $wave_number for task: $task_id"
+    log "Expected container count: ${expected_count:-N/A}"
+
+    # Use wave execution skill monitoring
+    local timeout="${TIMEOUT:-600}"
+    local monitor_script="$WAVE_EXECUTION_SKILL/monitor-wave.sh"
+
+    if [[ ! -x "$monitor_script" ]]; then
+        log_error "Wave monitor script not found: $monitor_script"
+        return 1
+    fi
+
+    # Monitor containers until completion or timeout
+    if "$monitor_script" \
+        --task-id "$task_id" \
+        --wave-number "$wave_number" \
+        --expected-count "${expected_count:-0}" \
+        --timeout "$timeout"; then
+
+        log_success "Wave $wave_number completed successfully"
+        return 0
+    else
+        local exit_code=$?
+        if [[ $exit_code -eq 2 ]]; then
+            log_error "Wave $wave_number monitoring timeout"
+        else
+            log_error "Wave $wave_number failed"
+        fi
+        return $exit_code
+    fi
+}
+
+cleanup_wave() {
+    local task_id="$1"
+    local wave_number="$2"
+
+    if [[ -z "$task_id" ]] || [[ -z "$wave_number" ]]; then
+        log_error "cleanup_wave requires: task_id, wave_number"
+        return 1
+    fi
+
+    log "Cleaning up wave $wave_number for task: $task_id"
+
+    # Use wave execution skill cleanup
+    local cleanup_script="$WAVE_EXECUTION_SKILL/cleanup-wave.sh"
+
+    if [[ ! -x "$cleanup_script" ]]; then
+        log_error "Wave cleanup script not found: $cleanup_script"
+        return 1
+    fi
+
+    # Remove containers and artifacts
+    if "$cleanup_script" \
+        --task-id "$task_id" \
+        --wave-number "$wave_number"; then
+
+        log_success "Wave $wave_number cleaned up successfully"
+        return 0
+    else
+        log_warning "Wave $wave_number cleanup had errors (partial cleanup)"
+        return 1
+    fi
+}
+
+validate_errors() {
+    local task_id="$1"
+    local command="$2"
+
+    if [[ -z "$task_id" ]] || [[ -z "$command" ]]; then
+        log_error "validate_errors requires: task_id, command"
+        return 1
+    fi
+
+    log "Running error validation for task: $task_id"
+    log "Command: $command"
+
+    # Create temporary output file for results
+    local output_file="/tmp/cfn-validate-errors-${task_id}.log"
+
+    # Execute validation command and capture output
+    if eval "$command" > "$output_file" 2>&1; then
+        local error_count=0
+    else
+        # Command failed, count errors from output
+        local error_count=$(grep -i "error" "$output_file" 2>/dev/null | wc -l)
+    fi
+
+    log_success "Error validation complete"
+    log "Error count: $error_count"
+
+    # Return JSON results
+    cat << EOF
+{
+  "task_id": "$task_id",
+  "command": "$command",
+  "error_count": $error_count,
+  "output_file": "$output_file",
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF
+
+    return 0
+}
+
+execute_waves() {
+    local task_id="$1"
+    local plan_file="$2"
+
+    if [[ -z "$task_id" ]] || [[ -z "$plan_file" ]]; then
+        log_error "execute_waves requires: task_id, plan_file"
+        return 1
+    fi
+
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Batching plan not found: $plan_file"
+        return 1
+    fi
+
+    log "Starting complete wave-based execution for task: $task_id"
+    log "Plan file: $plan_file"
+
+    # Parse wave count from plan
+    local wave_count
+    wave_count=$(jq '.waves | length' "$plan_file" 2>/dev/null)
+
+    if [[ -z "$wave_count" ]] || [[ "$wave_count" -lt 1 ]]; then
+        log_error "Invalid plan: no waves found"
+        return 1
+    fi
+
+    log "Total waves to execute: $wave_count"
+
+    # Validate memory budget before starting
+    if ! validate_memory_budget "$plan_file"; then
+        log_error "Memory budget validation failed - aborting execution"
+        return 1
+    fi
+
+    # Check for checkpoint recovery
+    if check_checkpoint_recovery "$task_id"; then
+        log_warning "Found existing checkpoint for task: $task_id"
+        if resume_from_checkpoint "$task_id"; then
+            log_success "Resumed execution from checkpoint"
+            # Continue monitoring remaining waves
+        else
+            log_warning "Checkpoint resume failed, starting fresh execution"
+        fi
+    fi
+
+    # Track results
+    local results_file="/tmp/cfn-wave-results-${task_id}.json"
+    echo '{"waves": [], "summary": {"total": 0, "succeeded": 0, "failed": 0}}' > "$results_file"
+
+    # Execute each wave sequentially
+    for wave_num in $(seq 1 "$wave_count"); do
+        log_loop "=== Wave $wave_num/$wave_count ==="
+
+        # Get batch count for this wave
+        local batch_count
+        batch_count=$(jq ".waves[$((wave_num - 1))].batch_count // 0" "$plan_file" 2>/dev/null)
+
+        # Spawn wave
+        if ! spawn_wave "$task_id" "$wave_num" "$plan_file"; then
+            log_error "Failed to spawn wave $wave_num"
+            # Attempt orphan cleanup before exiting
+            cleanup_orphaned_containers "$task_id" "$wave_num"
+            return 1
+        fi
+
+        # Get container IDs from spawn output for checkpoint
+        local container_ids
+        container_ids=$(docker ps -a --filter "label=cfn.task=$task_id" --filter "label=cfn.wave=$wave_num" --format "{{.ID}}" 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+
+        # Validate container IDs before saving checkpoint
+        if [[ -z "$container_ids" ]]; then
+            log_error "No containers found for wave $wave_num - checkpoint not saved"
+            cleanup_orphaned_containers "$task_id" "$wave_num"
+            return 1
+        fi
+
+        # Save checkpoint after successful spawn
+        save_wave_checkpoint "$task_id" "$wave_num" "$container_ids" "$batch_count"
+
+        # Monitor wave completion
+        if ! monitor_wave "$task_id" "$wave_num" "$batch_count"; then
+            log_error "Wave $wave_num failed or timed out"
+            # Attempt orphan cleanup before exiting
+            cleanup_orphaned_containers "$task_id" "$wave_num"
+            return 1
+        fi
+
+        # Update results
+        jq --arg wn "$wave_num" --arg status "completed" '.waves += [{wave_number: ($wn | tonumber), status: $status}]' "$results_file" > "${results_file}.tmp" && \
+            mv "${results_file}.tmp" "$results_file"
+
+        log_success "Wave $wave_num completed"
+    done
+
+    # Final cleanup and validation
+    log "Finalizing wave execution..."
+
+    for wave_num in $(seq 1 "$wave_count"); do
+        # Don't cleanup yet - logs may be needed
+        log "Preparing to cleanup wave $wave_num (logs preserved)"
+    done
+
+    # Output final results
+    log_success "Wave execution completed for task: $task_id"
+    cat "$results_file"
+
+    return 0
+}
+
 execute() {
     local task_id="$1"
     local task_description="$2"
@@ -702,9 +1407,9 @@ execute() {
     log "Description: $task_description"
     log "Mode: $MODE"
 
-    # Analyze task and select agents if not specified
+    # Analyze task and select agents if not specified (includes planning phase)
     if [[ -z "$AGENTS" ]]; then
-        AGENTS=$(analyze_task "$task_description")
+        AGENTS=$(analyze_task "$task_description" "$task_id")
     fi
 
     # Initialize orchestration
@@ -719,7 +1424,8 @@ execute() {
         spawn_loop3 "$task_id" "$AGENTS" "$iteration"
 
         # Gate check
-        gate_result=$(gate_check "$task_id" "$GATE_THRESHOLD" "$iteration" "$MAX_ITERATIONS")
+        gate_check "$task_id" "$GATE_THRESHOLD" "$iteration" "$MAX_ITERATIONS"
+        gate_result=$?
         case $gate_result in
             0) # Gate passed
                 log_loop "Gate PASSED - proceeding to Loop 2"
@@ -733,6 +1439,10 @@ execute() {
                 ((iteration++))
                 continue
                 ;;
+            *)
+                log_error "Invalid gate result: $gate_result"
+                return 1
+                ;;
         esac
     done
 
@@ -779,6 +1489,21 @@ case "$OPERATION" in
     trigger-po-decision)
         trigger_po_decision "$TASK_ID" ""
         ;;
+    execute-waves)
+        execute_waves "$TASK_ID" "$BATCHING_PLAN"
+        ;;
+    spawn-wave)
+        spawn_wave "$TASK_ID" "$WAVE_NUMBER" "$BATCHING_PLAN"
+        ;;
+    monitor-wave)
+        monitor_wave "$TASK_ID" "$WAVE_NUMBER" "$EXPECTED_COUNT"
+        ;;
+    cleanup-wave)
+        cleanup_wave "$TASK_ID" "$WAVE_NUMBER"
+        ;;
+    validate-errors)
+        validate_errors "$TASK_ID" "$VALIDATION_COMMAND"
+        ;;
     *)
         log_error "Unknown operation: $OPERATION"
         usage