claude-flow-novice 2.9.1 → 2.10.1

package/.claude/skills/cfn-redis-coordination/execute-product-owner-decision.sh

@@ -0,0 +1,258 @@
+#!/bin/bash
+##############################################################################
+# Product Owner Decision Execution Script
+#
+# Handles the complete Product Owner decision protocol:
+# 1. Query Loop 2 consensus from Redis
+# 2. Apply GOAP decision framework
+# 3. Push decision to Redis
+# 4. Signal completion
+# 5. Report confidence
+#
+# Usage:
+#   ./execute-product-owner-decision.sh --task-id <task> --agent-id <agent>
+##############################################################################
+
+set -euo pipefail
+
+# Parse arguments
+TASK_ID=""
+AGENT_ID=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --task-id)
+      TASK_ID="$2"
+      shift 2
+      ;;
+    --agent-id)
+      AGENT_ID="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: $0 --task-id <task> --agent-id <agent>"
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$TASK_ID" ] || [ -z "$AGENT_ID" ]; then
+  echo "Error: --task-id and --agent-id are required"
+  exit 1
+fi
+
+echo "[Product Owner] Starting decision execution for task: $TASK_ID"
+echo ""
+
+# Step 1: Query Loop 2 consensus and context
+echo "[Step 1] Querying Loop 2 consensus and context from Redis..."
+CONSENSUS=$(redis-cli lindex "swarm:${TASK_ID}:metrics:loop2_consensus" 0 | jq -r '.consensus')
+ITERATION=$(redis-cli lindex "swarm:${TASK_ID}:metrics:loop2_consensus" 0 | jq -r '.iteration')
+
+# Get feedback from validators
+FEEDBACK_JSON=$(redis-cli lrange "swarm:${TASK_ID}:loop2:feedback" 0 -1 | jq -s '.')
+
+# Get acceptance criteria and scope
+ACCEPTANCE_CRITERIA=$(redis-cli get "swarm:${TASK_ID}:success-criteria" | jq -r '.acceptanceCriteria // []')
+EPIC_CONTEXT=$(redis-cli get "swarm:${TASK_ID}:epic-context")
+IN_SCOPE=$(echo "$EPIC_CONTEXT" | jq -r '.inScope // []')
+OUT_OF_SCOPE=$(echo "$EPIC_CONTEXT" | jq -r '.outOfScope // []')
+EPIC_GOAL=$(echo "$EPIC_CONTEXT" | jq -r '.epicGoal // ""')
+
+echo "  Loop 2 Consensus: $CONSENSUS"
+echo "  Iteration: $ITERATION"
+echo "  Validator Feedback Items: $(echo "$FEEDBACK_JSON" | jq 'length')"
+echo ""
+
+# Step 2: Apply scope categorization
+echo "[Step 2] Categorizing validator feedback by scope..."
+
+# Initialize arrays
+IN_SCOPE_ITEMS="[]"
+OUT_OF_SCOPE_ITEMS="[]"
+IN_SCOPE_CONSENSUS=0
+OUT_OF_SCOPE_CONSENSUS=0
+
+# Process feedback if available
+if [ "$FEEDBACK_JSON" != "null" ] && [ "$FEEDBACK_JSON" != "[]" ]; then
+  # Categorize each feedback item
+  for feedback_item in $(echo "$FEEDBACK_JSON" | jq -r '.[] | @base64'); do
+    _jq() {
+      echo "$feedback_item" | base64 --decode | jq -r "$1"
+    }
+
+    FEEDBACK_TEXT=$(_jq '.')
+    IS_IN_SCOPE="false"
+
+    # Check if feedback relates to acceptance criteria or inScope items
+    for criterion in $(echo "$ACCEPTANCE_CRITERIA" | jq -r '.[] | @base64'); do
+      CRITERION_TEXT=$(echo "$criterion" | base64 --decode)
+      if echo "$FEEDBACK_TEXT" | grep -iq "$(echo "$CRITERION_TEXT" | head -c 20)"; then
+        IS_IN_SCOPE="true"
+        break
+      fi
+    done
+
+    # Add to appropriate category
+    if [ "$IS_IN_SCOPE" = "true" ]; then
+      IN_SCOPE_ITEMS=$(echo "$IN_SCOPE_ITEMS" | jq --arg item "$FEEDBACK_TEXT" '. + [$item]')
+    else
+      OUT_OF_SCOPE_ITEMS=$(echo "$OUT_OF_SCOPE_ITEMS" | jq --arg item "$FEEDBACK_TEXT" '. + [$item]')
+    fi
+  done
+
+  # Calculate in-scope consensus (consensus weighted by in-scope ratio)
+  TOTAL_ITEMS=$(echo "$FEEDBACK_JSON" | jq 'length')
+  IN_SCOPE_COUNT=$(echo "$IN_SCOPE_ITEMS" | jq 'length')
+
+  if [ "$TOTAL_ITEMS" -gt 0 ]; then
+    # If there's feedback, weight consensus by in-scope ratio
+    IN_SCOPE_CONSENSUS=$(echo "scale=2; $CONSENSUS * $IN_SCOPE_COUNT / $TOTAL_ITEMS" | bc -l)
+  else
+    # No feedback means validators had no concerns - use full consensus
+    IN_SCOPE_CONSENSUS=$CONSENSUS
+  fi
+else
+  # No feedback at all - use full consensus as in-scope
+  IN_SCOPE_CONSENSUS=$CONSENSUS
+fi
+
+echo "  In-Scope Items: $(echo "$IN_SCOPE_ITEMS" | jq 'length')"
+echo "  Out-of-Scope Items: $(echo "$OUT_OF_SCOPE_ITEMS" | jq 'length')"
+echo "  In-Scope Consensus: $IN_SCOPE_CONSENSUS"
+echo ""
+
+# Step 3: Apply GOAP decision framework with scope enforcement
+echo "[Step 3] Applying GOAP decision framework with scope enforcement..."
+
+# Default threshold (standard mode)
+CONSENSUS_THRESHOLD=0.90
+MAX_ITERATIONS=10
+
+# Determine decision based on scope-aware consensus
+DECISION_TYPE=""
+DECISION_REASONING=""
+DECISION_CONFIDENCE=0
+BACKLOG_ITEMS="[]"
+
+if (( $(echo "$CONSENSUS >= $CONSENSUS_THRESHOLD" | bc -l) )); then
+  # High consensus - check if there are out-of-scope items
+  OUT_OF_SCOPE_COUNT=$(echo "$OUT_OF_SCOPE_ITEMS" | jq 'length')
+
+  if [ "$OUT_OF_SCOPE_COUNT" -gt 0 ]; then
+    DECISION_TYPE="DEFER_AND_PROCEED"
+    DECISION_REASONING="In-scope work complete (consensus $CONSENSUS >= $CONSENSUS_THRESHOLD). Deferring $OUT_OF_SCOPE_COUNT out-of-scope items to backlog."
+    DECISION_CONFIDENCE=0.92
+    BACKLOG_ITEMS="$OUT_OF_SCOPE_ITEMS"
+    echo "  Decision: DEFER_AND_PROCEED (moving out-of-scope items to backlog)"
+  else
+    DECISION_TYPE="PROCEED"
+    DECISION_REASONING="All work complete, consensus threshold met ($CONSENSUS >= $CONSENSUS_THRESHOLD)"
+    DECISION_CONFIDENCE=0.95
+    echo "  Decision: PROCEED (consensus exceeds threshold, no out-of-scope items)"
+  fi
+elif [ "$ITERATION" -lt "$MAX_ITERATIONS" ]; then
+  # Below consensus - check if in-scope consensus would meet threshold
+  if (( $(echo "$IN_SCOPE_CONSENSUS >= $CONSENSUS_THRESHOLD" | bc -l) )); then
+    # In-scope work is good, out-of-scope items preventing consensus
+    DECISION_TYPE="DEFER_AND_PROCEED"
+    DECISION_REASONING="In-scope consensus met ($IN_SCOPE_CONSENSUS >= $CONSENSUS_THRESHOLD). Out-of-scope items preventing overall consensus - deferring to backlog."
+    DECISION_CONFIDENCE=0.88
+    BACKLOG_ITEMS="$OUT_OF_SCOPE_ITEMS"
+    echo "  Decision: DEFER_AND_PROCEED (in-scope work complete, deferring out-of-scope blockers)"
+  else
+    # In-scope work needs improvement
+    DECISION_TYPE="ITERATE"
+    DECISION_REASONING="In-scope consensus below threshold ($IN_SCOPE_CONSENSUS < $CONSENSUS_THRESHOLD), targeted improvements needed"
+    DECISION_CONFIDENCE=0.90
+    BACKLOG_ITEMS="$OUT_OF_SCOPE_ITEMS"
+    echo "  Decision: ITERATE (in-scope work needs improvement, iteration $ITERATION/$MAX_ITERATIONS)"
+  fi
+else
+  DECISION_TYPE="ABORT"
+  DECISION_REASONING="Max iterations reached ($ITERATION >= $MAX_ITERATIONS) without meeting in-scope consensus threshold"
+  DECISION_CONFIDENCE=0.85
+  echo "  Decision: ABORT (max iterations reached)"
+fi
+
+echo ""
+
+# Build structured decision JSON with scope analysis
+DECISION=$(jq -n \
+  --arg decision "$DECISION_TYPE" \
+  --arg reasoning "$DECISION_REASONING" \
+  --arg confidence "$DECISION_CONFIDENCE" \
+  --argjson in_scope_items "$IN_SCOPE_ITEMS" \
+  --argjson out_of_scope_items "$OUT_OF_SCOPE_ITEMS" \
+  --arg in_scope_consensus "$IN_SCOPE_CONSENSUS" \
+  --argjson backlog_items "$BACKLOG_ITEMS" \
+  '{
+    decision: $decision,
+    reasoning: $reasoning,
+    confidence: ($confidence | tonumber),
+    scope_analysis: {
+      in_scope_consensus: ($in_scope_consensus | tonumber),
+      in_scope_items: $in_scope_items,
+      out_of_scope_items: $out_of_scope_items
+    },
+    backlog_items: $backlog_items
+  }')
+
+echo "[Step 4] Managing backlog items..."
+if [ "$(echo "$BACKLOG_ITEMS" | jq 'length')" -gt 0 ]; then
+  # Store backlog items in Redis
+  BACKLOG_KEY="swarm:${TASK_ID}:backlog"
+  echo "$BACKLOG_ITEMS" | redis-cli -x LPUSH "$BACKLOG_KEY" >/dev/null
+  echo "  ✓ Stored $(echo "$BACKLOG_ITEMS" | jq 'length') backlog items in Redis: $BACKLOG_KEY"
+
+  # Persist backlog to file for human review
+  BACKLOG_FILE=".claude/cfn-data/backlog/${TASK_ID}.json"
+  mkdir -p "$(dirname "$BACKLOG_FILE")"
+
+  BACKLOG_RECORD=$(jq -n \
+    --arg task_id "$TASK_ID" \
+    --arg timestamp "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+    --arg epic_goal "$EPIC_GOAL" \
+    --argjson items "$BACKLOG_ITEMS" \
+    '{
+      task_id: $task_id,
+      timestamp: $timestamp,
+      epic_goal: $epic_goal,
+      deferred_items: $items,
+      status: "pending_review"
+    }')
+
+  echo "$BACKLOG_RECORD" > "$BACKLOG_FILE"
+  echo "  ✓ Backlog persisted to: $BACKLOG_FILE"
+else
+  echo "  No backlog items to store"
+fi
+echo ""
+
+echo "[Step 5] Pushing decision to Redis..."
+DECISION_KEY="swarm:${TASK_ID}:${AGENT_ID}:decision"
+echo "$DECISION" | redis-cli -x LPUSH "$DECISION_KEY" >/dev/null
+echo "  ✓ Decision pushed to: $DECISION_KEY"
+echo "  Content: $DECISION"
+echo ""
+
+# Step 6: Signal completion
+echo "[Step 6] Signaling completion..."
+DONE_KEY="swarm:${TASK_ID}:${AGENT_ID}:done"
+redis-cli LPUSH "$DONE_KEY" "complete" >/dev/null
+echo "  ✓ Completion signaled"
+echo ""
+
+# Step 7: Report confidence
+echo "[Step 7] Reporting confidence..."
+./.claude/skills/cfn-redis-coordination/invoke-waiting-mode.sh report \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --confidence "$DECISION_CONFIDENCE"
+
+echo ""
+echo "🎉 Product Owner decision execution complete!"
+echo "   Decision: $DECISION_TYPE"
+echo "   Consensus: $CONSENSUS"
+echo "   Iteration: $ITERATION"

package/.claude/skills/cfn-redis-coordination/get-agent-timeout.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# get-agent-timeout.sh - Get agent timeout from swarm metadata with intelligent fallback
+# Part of Redis Coordination Skill
+# Usage: ./get-agent-timeout.sh --task-id <id> --agent-id <id>
+#
+# Returns agent-specific timeout from swarm metadata with fallback order:
+# 1. agentTimeouts[agent-id] (exact match from swarm metadata)
+# 2. roleTimeouts[agent-role] (role-based from swarm metadata)
+# 3. agentTimeouts.default (fallback from swarm metadata)
+# 4. Role-based hardcoded defaults (researcher=7200, backend-dev=3600, etc.)
+# 5. 3600 (hardcoded default: 1 hour)
+#
+# Version: 1.1.0
+# Last Updated: 2025-10-19
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REDIS_HOST="${REDIS_HOST:-localhost}"
+REDIS_PORT="${REDIS_PORT:-6379}"
+DEFAULT_TIMEOUT=3600  # 60 minutes default
+
+# Parse arguments
+TASK_ID=""
+AGENT_ID=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --task-id)
+      TASK_ID="$2"
+      shift 2
+      ;;
+    --agent-id)
+      AGENT_ID="$2"
+      shift 2
+      ;;
+    *)
+      echo "❌ Unknown argument: $1" >&2
+      echo "Usage: $0 --task-id <id> --agent-id <id>" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required arguments
+if [[ -z "$TASK_ID" || -z "$AGENT_ID" ]]; then
+  echo "❌ Missing required arguments" >&2
+  echo "Usage: $0 --task-id <id> --agent-id <id>" >&2
+  exit 1
+fi
+
+# Function to extract role from agent-id
+extract_role_from_agent_id() {
+  local agent_id="$1"
+
+  # Extract role prefix (everything before last hyphen and number)
+  # Examples:
+  #   "researcher-1" -> "researcher"
+  #   "backend-dev-6" -> "backend-dev"
+  #   "reviewer" -> "reviewer"
+  if [[ "$agent_id" =~ ^(.+)-[0-9]+$ ]]; then
+    echo "${BASH_REMATCH[1]}"
+  else
+    echo "$agent_id"
+  fi
+}
+
+# Function to get role-based hardcoded timeout defaults (fallback layer 4)
+get_hardcoded_role_timeout() {
+  local role="$1"
+
+  case "$role" in
+    researcher)
+      echo "7200"  # 2 hours - research takes longer
+      ;;
+    backend-dev|coder|frontend-dev)
+      echo "3600"  # 1 hour - development work
+      ;;
+    reviewer|tester|security)
+      echo "1800"  # 30 minutes - validation/review
+      ;;
+    coordinator|orchestrator|product-owner)
+      echo "900"   # 15 minutes - coordination tasks
+      ;;
+    devops|architect)
+      echo "5400"  # 90 minutes - infrastructure/architecture
+      ;;
+    *)
+      echo "3600"  # 1 hour - default fallback
+      ;;
+  esac
+}
+
+# Function to extract timeout from JSON using jq or fallback parsing
+extract_timeout_from_json() {
+  local json="$1"
+  local key="$2"
+
+  if [[ -z "$json" || "$json" == "(nil)" ]]; then
+    echo ""
+    return
+  fi
+
+  # Use jq if available
+  if command -v jq &>/dev/null; then
+    local result
+    result=$(echo "$json" | jq -r --arg k "$key" '.[$k] // empty' 2>/dev/null || echo "")
+    echo "$result"
+  else
+    # Fallback: simple pattern matching for "key": value
+    echo "$json" | grep -oP "\"$key\"\s*:\s*\K\d+" 2>/dev/null || echo ""
+  fi
+}
+
+# Get swarm ID from task mapping
+SWARM_ID=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" \
+  GET "task:${TASK_ID}:swarm" 2>/dev/null || echo "")
+
+if [[ -z "$SWARM_ID" || "$SWARM_ID" == "(nil)" ]]; then
+  # Fallback: assume task-id is swarm-id for backwards compatibility
+  SWARM_ID="$TASK_ID"
+fi
+
+# Read swarm metadata from Redis
+METADATA=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" \
+  HGETALL "swarm:${SWARM_ID}:metadata" 2>/dev/null || echo "")
+
+# Extract role from agent ID
+ROLE=$(extract_role_from_agent_id "$AGENT_ID")
+
+# Parse metadata and extract timeout configurations
+TIMEOUT=""
+
+if [[ -n "$METADATA" && "$METADATA" != "(nil)" ]]; then
+  # Parse metadata into associative array
+  declare -A META
+  while IFS= read -r key && IFS= read -r value; do
+    META["$key"]="$value"
+  done <<< "$METADATA"
+
+  AGENT_TIMEOUTS_JSON="${META[agentTimeouts]:-}"
+  ROLE_TIMEOUTS_JSON="${META[roleTimeouts]:-}"
+
+  # Fallback order 1: agentTimeouts[agent-id] (exact match)
+  if [[ -n "$AGENT_TIMEOUTS_JSON" ]]; then
+    TIMEOUT=$(extract_timeout_from_json "$AGENT_TIMEOUTS_JSON" "$AGENT_ID")
+  fi
+
+  # Fallback order 2: roleTimeouts[agent-role] (role-based)
+  if [[ -z "$TIMEOUT" && -n "$ROLE_TIMEOUTS_JSON" ]]; then
+    TIMEOUT=$(extract_timeout_from_json "$ROLE_TIMEOUTS_JSON" "$ROLE")
+  fi
+
+  # Fallback order 3: agentTimeouts.default
+  if [[ -z "$TIMEOUT" && -n "$AGENT_TIMEOUTS_JSON" ]]; then
+    TIMEOUT=$(extract_timeout_from_json "$AGENT_TIMEOUTS_JSON" "default")
+  fi
+fi
+
+# Fallback order 4: Role-based hardcoded defaults
+if [[ -z "$TIMEOUT" ]]; then
+  TIMEOUT=$(get_hardcoded_role_timeout "$ROLE")
+fi
+
+# Fallback order 5: Hardcoded default (3600s)
+if [[ -z "$TIMEOUT" ]]; then
+  TIMEOUT="$DEFAULT_TIMEOUT"
+fi
+
+# Validate timeout is numeric
+if ! [[ "$TIMEOUT" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Invalid timeout value: $TIMEOUT, using default: ${DEFAULT_TIMEOUT}s" >&2
+  TIMEOUT="$DEFAULT_TIMEOUT"
+fi
+
+# Return timeout value
+echo "$TIMEOUT"

package/.claude/skills/cfn-redis-coordination/heartbeat-functions.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+
+##############################################################################
+# Heartbeat Monitoring Functions Library
+# Extracted from orchestrate-cfn-loop.sh for standalone testing
+##############################################################################
+
+##############################################################################
+# Heartbeat Monitoring Functions
+##############################################################################
+declare -A MISSED_HEARTBEATS  # Track missed heartbeats per agent
+
+function check_agent_heartbeat() {
+  local agent="$1"
+  local task_id="$2"
+
+  HB_KEY="swarm:${task_id}:${agent}:heartbeat"
+  HB_DATA=$(redis-cli GET "$HB_KEY" 2>/dev/null || echo "")
+
+  if [ -z "$HB_DATA" ] || [ "$HB_DATA" = "(nil)" ]; then
+    return 1  # Dead
+  else
+    return 0  # Alive
+  fi
+}
+
+function calculate_quorum() {
+  local quorum_spec="$1"
+  local total_agents="$2"
+
+  # If no quorum specified, require all agents
+  if [ -z "$quorum_spec" ]; then
+    echo "$total_agents"
+    return 0
+  fi
+
+  # Check if percentage format (e.g., "85%")
+  if [[ "$quorum_spec" =~ %$ ]]; then
+    # Extract percentage value (remove % suffix)
+    local pct="${quorum_spec%\%}"
+    # Calculate: ceil(total_agents * pct / 100)
+    echo "scale=0; ($total_agents * $pct + 50) / 100" | bc
+  # Check if decimal (0.0-1.0), treat as fraction
+  elif [[ "$quorum_spec" =~ ^0?\.[0-9]+$ ]]; then
+    # Calculate: ceil(total_agents * fraction)
+    echo "scale=0; ($quorum_spec * $total_agents + 0.5) / 1" | bc
+  else
+    # Absolute number - validate it doesn't exceed total
+    if [ "$quorum_spec" -gt "$total_agents" ]; then
+      echo "Error: Quorum ($quorum_spec) exceeds total agents ($total_agents)" >&2
+      return 1
+    fi
+    echo "$quorum_spec"
+  fi
+}
+
+function check_heartbeats_loop() {
+  local task_id="$1"
+  local loop_name="$2"
+  shift 2
+  local agents=("$@")
+
+  for AGENT in "${agents[@]}"; do
+    # Skip agents already marked as failed
+    if [[ " ${LOOP3_FAILED_AGENTS[@]} ${LOOP2_FAILED_AGENTS[@]} " =~ " ${AGENT} " ]]; then
+      continue
+    fi
+
+    if ! check_agent_heartbeat "$AGENT" "$task_id"; then
+      MISSED_HEARTBEATS["$AGENT"]=$((${MISSED_HEARTBEATS["$AGENT"]:-0} + 1))
+
+      if [ ${MISSED_HEARTBEATS["$AGENT"]} -ge 2 ]; then
+        local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+        echo "  [$timestamp] [$loop_name] ⚠️ $AGENT appears hung (no heartbeat for 60s)" >&2
+
+        # Determine which loop this agent belongs to and check quorum
+        if [[ " ${LOOP3_AGENTS} " =~ " ${AGENT} " ]]; then
+          REMAINING=$((${#LOOP3_COMPLETED_AGENTS[@]}))
+          REQUIRED=$(calculate_quorum "$MIN_QUORUM_LOOP3" "$LOOP3_TOTAL")
+        elif [[ " ${LOOP2_AGENTS} " =~ " ${LOOP2_AGENTS} " ]]; then
+          REMAINING=$((${#LOOP2_COMPLETED_AGENTS[@]}))
+          REQUIRED=$(calculate_quorum "$MIN_QUORUM_LOOP2" "$LOOP2_TOTAL")
+        else
+          continue
+        fi
+
+        if [ $REMAINING -ge $REQUIRED ]; then
+          echo "  [$timestamp] [$loop_name] ℹ️ Continuing with quorum (${REMAINING}/${REQUIRED} agents)" >&2
+        else
+          echo "  [$timestamp] [$loop_name] ⚠️ Cannot meet quorum without $AGENT (${REMAINING}/${REQUIRED})" >&2
+        fi
+      fi
+    else
+      MISSED_HEARTBEATS["$AGENT"]=0  # Reset counter
+    fi
+  done
+}
+
+function start_heartbeat_monitor() {
+  local task_id="$1"
+  local loop_name="$2"
+  shift 2
+  local agents=("$@")
+
+  # Create marker file for this monitor
+  local monitor_marker="/tmp/heartbeat-monitor-${task_id}-${loop_name}.active"
+  touch "$monitor_marker"
+
+  (
+    while [ -f "$monitor_marker" ]; do
+      # Check for shutdown
+      if [ "${SHUTDOWN_REQUESTED:-0}" -eq 1 ]; then
+        break
+      fi
+
+      check_heartbeats_loop "$task_id" "$loop_name" "${agents[@]}"
+      sleep 30
+    done
+  ) &
+
+  echo "$!"  # Return PID
+}
+
+function stop_heartbeat_monitor() {
+  local task_id="$1"
+  local loop_name="$2"
+  local monitor_pid="$3"
+
+  # Remove marker file to stop the monitor loop
+  rm -f "/tmp/heartbeat-monitor-${task_id}-${loop_name}.active"
+
+  # Kill monitor process if still running
+  if [ -n "$monitor_pid" ] && kill -0 "$monitor_pid" 2>/dev/null; then
+    kill "$monitor_pid" 2>/dev/null || true
+    wait "$monitor_pid" 2>/dev/null || true
+  fi
+}

package/.claude/skills/cfn-redis-coordination/heartbeat-protocol.md

@@ -0,0 +1,106 @@
+# Heartbeat Protocol Specification
+
+## Overview
+The heartbeat protocol provides a mechanism for detecting hung or unresponsive agents in distributed agent swarms using Redis as a coordination mechanism.
+
+## Key Design Components
+
+### 1. Heartbeat Key Pattern
+```
+swarm:{task_id}:{agent_id}:heartbeat
+```
+
+### 2. Heartbeat Message Structure
+```json
+{
+    "timestamp": 1760898665,
+    "status": "working|idle|error",
+    "iteration": 2,
+    "progress": 0.75,
+    "agent_details": {
+        "agent_id": "architect-5",
+        "task_id": "redis-phase5-1760898665",
+        "environment": {
+            "cpu_usage": 0.65,
+            "memory_usage": 0.42,
+            "system_load": 0.3
+        }
+    }
+}
+```
+
+### 3. Heartbeat Configuration
+- **Update Frequency**: Every 30 seconds
+- **Default TTL**: 60 seconds
+- **Miss Threshold**: 2 consecutive missed heartbeats
+- **Quorum Threshold**: 70% of agents must be responsive
+
+### 4. Heartbeat Workflow
+1. Agent periodically sends heartbeat via Redis SET
+2. Orchestrator monitors heartbeats in background process
+3. On missed heartbeats, trigger progressive recovery mechanisms
+
+### 5. Recovery Stages
+- **Stage 1 (Miss 1)**: Log warning, continue monitoring
+- **Stage 2 (Miss 2)**:
+  - Check if remaining agents meet quorum
+  - Log to Dead Letter Queue (DLQ)
+  - Attempt soft restart of agent
+- **Stage 3 (Miss 3)**:
+  - Hard restart agent
+  - Potentially replace with standby agent
+
+### 6. Implementation Pseudo-code
+```bash
+# Send Heartbeat
+redis-cli set "swarm:${TASK_ID}:${AGENT_ID}:heartbeat" \
+    "$(generate_heartbeat_payload)" \
+    EX 60  # 60-second expiry
+
+# Check Heartbeats
+check_agent_heartbeats() {
+    for agent in ${AGENTS[@]}; do
+        heartbeat=$(redis-cli get "swarm:${TASK_ID}:${agent}:heartbeat")
+        if [[ -z "$heartbeat" ]]; then
+            handle_missed_heartbeat "$agent"
+        fi
+    done
+}
+
+handle_missed_heartbeat() {
+    local agent="$1"
+    local miss_count=$(get_miss_count "$agent")
+
+    case "$miss_count" in
+        1) log_warning "$agent missed first heartbeat" ;;
+        2)
+            log_dlq "$agent"
+            attempt_soft_restart "$agent"
+            check_quorum
+            ;;
+        3)
+            hard_restart_agent "$agent"
+            ;;
+    esac
+}
+```
+
+### 7. Monitoring and Logging
+- Comprehensive logging to `/var/log/claude-flow/heartbeat.log`
+- Prometheus metrics for heartbeat health
+- Grafana dashboard tracking agent responsiveness
+
+### 8. Security Considerations
+- Cryptographically sign heartbeat messages
+- Rate limit heartbeat submissions
+- Validate heartbeat payload schema
+
+## Integration Points
+- Redis Coordination Skill
+- CFN Loop Validation
+- Agent Spawning Mechanism
+
+## Test Coverage
+- Unit tests for heartbeat generation
+- Integration tests for recovery mechanisms
+- Chaos testing (intentional agent hanging)