claude-flow-novice 2.10.4 → 2.10.6

package/claude-assets/skills/cfn-redis-coordination/invoke-waiting-mode.sh.backup-p7

@@ -0,0 +1,423 @@
+#!/bin/bash
+#
+# Redis Waiting Mode CLI Wrapper for Agents
+#
+# Usage:
+#   ./invoke-waiting-mode.sh enter --task-id <task> --agent-id <agent> --context <context>
+#   ./invoke-waiting-mode.sh wake --task-id <task> --agent-id <agent> --reason <reason> [--iteration <n>] [--priority <0-100>] [--fork-id <fork_id>]
+#   ./invoke-waiting-mode.sh report --task-id <task> --agent-id <agent> --confidence <score> [--iteration <n>]
+#   ./invoke-waiting-mode.sh collect --task-id <task> --agent-ids <id1,id2,id3>
+#   ./invoke-waiting-mode.sh shutdown --task-id <task> [--reason <reason>]
+#
+# New parameter: --fork-id
+#   Optional unique identifier for conversation continuation
+#   Allows tracking and resuming specific conversation forks
+#   Stored in Redis with 5-minute TTL during agent wake
+#
+# Priority Levels (0-100, higher = more urgent, default = 50):
+#   90-100: Critical (security patches, system failures)
+#   70-89:  High (urgent features, blocking bugs)
+#   40-60:  Medium (normal tasks, default)
+#   20-39:  Low (optimizations, refactoring)
+#   0-19:   Minimal (documentation, cleanup)
+#
+# Examples:
+#   # Agent enters waiting mode
+#   ./invoke-waiting-mode.sh enter --task-id auth-system --agent-id coder-1 --context "iteration-1"
+#
+#   # Coordinator wakes agent with fork ID
+#   ./invoke-waiting-mode.sh wake --task-id auth-system --agent-id coder-1 --reason cfn_loop_iteration --iteration 2 --fork-id "fork-1-a3b2c1d4"
+#
+#   # Other existing use cases remain unchanged
+
+set -euo pipefail
+
+# Debug mode (set DEBUG=true for verbose output)
+DEBUG="${DEBUG:-false}"
+
+# Parse command
+COMMAND="${1:-}"
+shift || true
+
+# Parse arguments
+TASK_ID=""
+AGENT_ID=""
+AGENT_IDS=""
+CONTEXT=""
+REASON=""
+ITERATION=""
+CONFIDENCE=""
+FEEDBACK=""
+TASK_DESC=""
+FORK_ID=""
+PRIORITY=50  # Default medium priority (0-100, higher = more urgent)
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --task-id)
+            TASK_ID="$2"
+            shift 2
+            ;;
+        --agent-id)
+            AGENT_ID="$2"
+            shift 2
+            ;;
+        --agent-ids)
+            AGENT_IDS="$2"
+            shift 2
+            ;;
+        --context)
+            CONTEXT="$2"
+            shift 2
+            ;;
+        --reason)
+            REASON="$2"
+            shift 2
+            ;;
+        --iteration)
+            ITERATION="$2"
+            shift 2
+            ;;
+        --confidence)
+            CONFIDENCE="$2"
+            shift 2
+            ;;
+        --feedback)
+            FEEDBACK="$2"
+            shift 2
+            ;;
+        --task)
+            TASK_DESC="$2"
+            shift 2
+            ;;
+        --priority)
+            PRIORITY="$2"
+            shift 2
+            ;;
+        --fork-id)
+            FORK_ID="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown argument: $1"
+            exit 1
+            ;;
+    esac
+done
+
+# Validate required arguments
+case "$COMMAND" in
+    enter)
+        if [ -z "$TASK_ID" ] || [ -z "$AGENT_ID" ] || [ -z "$CONTEXT" ]; then
+            echo "Error: enter requires --task-id, --agent-id, and --context"
+            exit 1
+        fi
+
+        # Enter waiting mode
+        READY_KEY="swarm:${TASK_ID}:${AGENT_ID}:ready"
+        WAKE_QUEUE="swarm:${TASK_ID}:${AGENT_ID}:wake-queue"
+        SHUTDOWN_KEY="swarm:${TASK_ID}:shutdown"
+
+        # Publish ready status
+        READY_MSG=$(jq -n \
+            --arg status "waiting" \
+            --arg context "$CONTEXT" \
+            --arg ts "$(date +%s)" \
+            '{status: $status, context: $context, timestamp: ($ts | tonumber)}')
+
+        echo "$READY_MSG" | redis-cli -x LPUSH "$READY_KEY" >/dev/null
+
+        echo "[$AGENT_ID] Entered waiting mode (context: $CONTEXT)"
+        echo "[$AGENT_ID] Blocking on priority queue $WAKE_QUEUE and $SHUTDOWN_KEY (infinite timeout)..."
+        echo "[$AGENT_ID] Zero token cost while waiting"
+
+        # Poll loop: check shutdown first, then block on wake queue with timeout
+        # This allows us to support both priority queues and shutdown signals
+        while true; do
+            # Check for shutdown signal first (highest priority)
+            SHUTDOWN_CHECK=$(redis-cli LPOP "$SHUTDOWN_KEY")
+
+            if [ -n "$SHUTDOWN_CHECK" ] && [ "$SHUTDOWN_CHECK" != "(nil)" ]; then
+                # Shutdown signal received
+                SHUTDOWN_REASON=$(echo "$SHUTDOWN_CHECK" | jq -r '.reason // "unknown"')
+                echo "[$AGENT_ID] 🛑 Shutdown signal received"
+                echo "[$AGENT_ID] Reason: $SHUTDOWN_REASON"
+                echo "$SHUTDOWN_CHECK" | jq '.'
+
+                # Exit with SIGINT code to indicate graceful shutdown
+                exit 130
+            fi
+
+            # Block on wake queue with 1-second timeout (allows periodic shutdown checks)
+            # BZPOPMIN returns: key, member, score (3 lines)
+            WAKE_RESULT=$(redis-cli BZPOPMIN "$WAKE_QUEUE" 1 2>/dev/null)
+
+            if [ -n "$WAKE_RESULT" ] && [ "$WAKE_RESULT" != "(nil)" ]; then
+                # Parse result (BZPOPMIN returns 3 lines: key, member, score)
+                WAKE_MSG=$(echo "$WAKE_RESULT" | sed -n '2p')
+
+                # Validate JSON before processing
+                if echo "$WAKE_MSG" | jq empty 2>/dev/null; then
+                    echo "[$AGENT_ID] ✅ Woken up!"
+                    echo "$WAKE_MSG" | jq '.'
+
+                    # Return wake message to caller
+                    echo "$WAKE_MSG"
+                    break
+                else
+                    echo "[$AGENT_ID] ⚠️  Invalid JSON in wake message, ignoring"
+                    continue
+                fi
+            fi
+
+            # If no wake signal received, loop back to check shutdown again
+        done
+        ;;
+
+    wake)
+        if [ -z "$TASK_ID" ] || [ -z "$AGENT_ID" ] || [ -z "$REASON" ]; then
+            echo "Error: wake requires --task-id, --agent-id, and --reason"
+            exit 1
+        fi
+
+        WAKE_QUEUE="swarm:${TASK_ID}:${AGENT_ID}:wake-queue"
+
+        # Build wake message (compact JSON for Redis storage)
+        WAKE_MSG=$(jq -nc \
+            --arg reason "$REASON" \
+            --arg iteration "${ITERATION:-0}" \
+            --arg task "${TASK_DESC:-}" \
+            --arg feedback "${FEEDBACK:-}" \
+            --arg priority "$PRIORITY" \
+            --arg fork_id "${FORK_ID:-}" \
+            --arg ts "$(date +%s)" \
+            '{
+                reason: $reason,
+                iteration: ($iteration | tonumber),
+                task: $task,
+                feedback: ($feedback | split(",") | map(select(length > 0))),
+                priority: ($priority | tonumber),
+                fork_id: $fork_id,
+                timestamp: ($ts | tonumber)
+            }')
+
+        # Store feedback in Redis for agent to read (if provided and iteration > 0)
+        # Debug: Echo values before conditional (only if feedback provided)
+        if [ -n "$FEEDBACK" ]; then
+            [ "$DEBUG" = "true" ] && echo "[DEBUG] Checking feedback storage: FEEDBACK='$FEEDBACK', ITERATION='${ITERATION:-0}'"
+        fi
+
+        # Only store feedback if: feedback is non-empty AND iteration > 0
+        # Check iteration value explicitly (not just default)
+        if [ -n "$FEEDBACK" ] && [ -n "$ITERATION" ] && [ "$ITERATION" -gt 0 ]; then
+            FEEDBACK_KEY="swarm:${TASK_ID}:${AGENT_ID}:feedback:iteration-${ITERATION}"
+            FEEDBACK_ARRAY=$(echo "$FEEDBACK" | jq -Rc 'split(",") | map(select(length > 0))')
+
+            # Only store if feedback array is not empty after filtering
+            ARRAY_LENGTH=$(echo "$FEEDBACK_ARRAY" | jq 'length')
+            if [ "$ARRAY_LENGTH" -gt 0 ]; then
+                # Store as JSON array with 24-hour TTL
+                REDIS_RESULT=$(printf '%s' "$FEEDBACK_ARRAY" | redis-cli -x SET "$FEEDBACK_KEY")
+                redis-cli EXPIRE "$FEEDBACK_KEY" 86400 >/dev/null
+
+                # Always log feedback storage (not just in DEBUG mode)
+                if [ "$REDIS_RESULT" = "OK" ]; then
+                    echo "  [Feedback] Stored $ARRAY_LENGTH items in Redis (TTL: 24h)"
+                fi
+
+                if [ "$DEBUG" = "true" ]; then
+                    echo "[DEBUG] Stored feedback in $FEEDBACK_KEY (TTL: 24h)"
+                    echo "[DEBUG] Feedback: $FEEDBACK_ARRAY"
+                    echo "[DEBUG] Redis SET result: $REDIS_RESULT"
+                fi
+            fi
+        fi
+
+        # Calculate priority score (lower score = higher priority, popped first)
+        # Score = (100 - priority) * 1000000 + timestamp
+        # This ensures higher priority messages are processed first, with FIFO for same priority
+        TIMESTAMP=$(date +%s)
+        PRIORITY_SCORE=$(echo "(100 - $PRIORITY) * 1000000 + $TIMESTAMP" | bc)
+
+        # Debug output
+        if [ "$DEBUG" = "true" ]; then
+            echo "[DEBUG] WAKE_QUEUE: $WAKE_QUEUE"
+            echo "[DEBUG] PRIORITY: $PRIORITY"
+            echo "[DEBUG] Priority score: $PRIORITY_SCORE"
+            echo "[DEBUG] Message: $WAKE_MSG"
+        fi
+
+        # Add to sorted set (ZADD with calculated score)
+        redis-cli ZADD "$WAKE_QUEUE" "$PRIORITY_SCORE" "$WAKE_MSG" >/dev/null
+
+        # Store fork ID in Redis if provided
+        if [ -n "$FORK_ID" ]; then
+            FORK_KEY="swarm:${TASK_ID}:${AGENT_ID}:fork-id"
+            # Store fork ID with 5-minute expiration
+            redis-cli SETEX "$FORK_KEY" 300 "$FORK_ID" >/dev/null
+            echo "[Coordinator] Fork ID stored: $FORK_ID (5-minute TTL)"
+        fi
+
+        echo "[Coordinator] ✅ Wake signal sent to $AGENT_ID"
+        echo "  Reason: $REASON"
+        echo "  Priority: $PRIORITY (score: $PRIORITY_SCORE)"
+        [ -n "$ITERATION" ] && echo "  Iteration: $ITERATION"
+        ;;
+
+    report)
+        if [ -z "$TASK_ID" ] || [ -z "$AGENT_ID" ] || [ -z "$CONFIDENCE" ]; then
+            echo "Error: report requires --task-id, --agent-id, and --confidence"
+            exit 1
+        fi
+
+        RESULT_KEY="swarm:${TASK_ID}:${AGENT_ID}:result"
+
+        # Build result message with optional feedback
+        RESULT_MSG=$(jq -n \
+            --arg confidence "$CONFIDENCE" \
+            --arg iteration "${ITERATION:-0}" \
+            --arg feedback "${FEEDBACK:-}" \
+            --arg ts "$(date +%s)" \
+            '{
+                confidence: ($confidence | tonumber),
+                iteration: ($iteration | tonumber),
+                feedback: ($feedback | split(",") | map(select(length > 0))),
+                timestamp: ($ts | tonumber)
+            }')
+
+        echo "$RESULT_MSG" | redis-cli -x LPUSH "$RESULT_KEY" >/dev/null
+
+        echo "[$AGENT_ID] ✅ Result reported"
+        echo "  Confidence: $CONFIDENCE"
+        [ -n "$ITERATION" ] && echo "  Iteration: $ITERATION"
+        if [ -n "$FEEDBACK" ]; then
+            echo "  Feedback items: $(echo "$FEEDBACK" | tr ',' '\n' | wc -l)"
+        fi
+        ;;
+
+    collect)
+        if [ -z "$TASK_ID" ] || [ -z "$AGENT_IDS" ]; then
+            echo "Error: collect requires --task-id and --agent-ids"
+            exit 1
+        fi
+
+        echo "[Coordinator] Collecting results from agents..."
+        echo ""
+
+        # Split agent IDs
+        IFS=',' read -ra AGENTS <<< "$AGENT_IDS"
+
+        RESULTS=()
+        CONFIDENCES=()
+        ALL_FEEDBACK=()
+
+        for AGENT in "${AGENTS[@]}"; do
+            RESULT_KEY="swarm:${TASK_ID}:${AGENT}:result"
+
+            # Get latest result (non-blocking)
+            RESULT=$(redis-cli LPOP "$RESULT_KEY")
+
+            if [ -n "$RESULT" ] && [ "$RESULT" != "(nil)" ]; then
+                CONF=$(echo "$RESULT" | jq -r '.confidence')
+                echo "  [$AGENT] Confidence: $CONF"
+                RESULTS+=("$RESULT")
+                CONFIDENCES+=("$CONF")
+
+                # Check if result includes feedback array
+                FEEDBACK=$(echo "$RESULT" | jq -r '.feedback // empty | .[]?' 2>/dev/null)
+                if [ -n "$FEEDBACK" ]; then
+                    echo "  [$AGENT] Feedback provided:"
+                    echo "$RESULT" | jq -r '.feedback[]' | sed 's/^/    - /'
+
+                    # Collect all feedback items
+                    while IFS= read -r ITEM; do
+                        ALL_FEEDBACK+=("$ITEM")
+                    done < <(echo "$RESULT" | jq -r '.feedback[]')
+                fi
+            else
+                echo "  [$AGENT] ⚠️  No result found"
+            fi
+        done
+
+        # Calculate consensus
+        if [ ${#CONFIDENCES[@]} -gt 0 ]; then
+            SUM=0
+            for CONF in "${CONFIDENCES[@]}"; do
+                SUM=$(echo "$SUM + $CONF" | bc)
+            done
+            COUNT=${#CONFIDENCES[@]}
+            CONSENSUS=$(echo "scale=2; $SUM / $COUNT" | bc)
+
+            echo ""
+            echo "[Coordinator] Consensus: $CONSENSUS"
+
+            # Print aggregated feedback if available
+            if [ ${#ALL_FEEDBACK[@]} -gt 0 ]; then
+                echo "[Coordinator] Aggregated Feedback (${#ALL_FEEDBACK[@]} items):"
+                printf '%s\n' "${ALL_FEEDBACK[@]}" | sort -u | sed 's/^/  - /'
+            fi
+
+            echo "$CONSENSUS"
+        else
+            echo ""
+            echo "[Coordinator] No results to calculate consensus"
+            echo "0.0"
+        fi
+        ;;
+
+    shutdown)
+        if [ -z "$TASK_ID" ]; then
+            echo "Error: shutdown requires --task-id"
+            exit 1
+        fi
+
+        SHUTDOWN_KEY="swarm:${TASK_ID}:shutdown"
+
+        # Build shutdown message
+        SHUTDOWN_MSG=$(jq -n \
+            --arg reason "${REASON:-task_complete}" \
+            --arg ts "$(date +%s)" \
+            '{
+                reason: $reason,
+                timestamp: ($ts | tonumber)
+            }')
+
+        # Broadcast shutdown signal (use LPUSH to add to list)
+        # All waiting agents will check this key and exit gracefully
+        echo "$SHUTDOWN_MSG" | redis-cli -x LPUSH "$SHUTDOWN_KEY" >/dev/null
+
+        echo "[Coordinator] 🛑 Shutdown signal broadcasted"
+        echo "  Task ID: $TASK_ID"
+        echo "  Reason: ${REASON:-task_complete}"
+        echo ""
+        echo "Note: Signal added to $SHUTDOWN_KEY"
+        echo "All waiting agents will receive shutdown on next poll cycle (max 1 second)"
+        ;;
+
+    *)
+        echo "Usage: $0 <command> [options]"
+        echo ""
+        echo "Commands:"
+        echo "  enter    - Agent enters waiting mode"
+        echo "  wake     - Coordinator wakes an agent (supports --priority 0-100, --fork-id)"
+        echo "  report   - Agent reports result"
+        echo "  collect  - Coordinator collects results"
+        echo "  shutdown - Coordinator broadcasts shutdown signal to all waiting agents"
+        echo ""
+        echo "Priority Levels (0-100, higher = more urgent, default = 50):"
+        echo "  90-100: Critical (security patches, system failures)"
+        echo "  70-89:  High (urgent features, blocking bugs)"
+        echo "  40-60:  Medium (normal tasks, default)"
+        echo "  20-39:  Low (optimizations, refactoring)"
+        echo "  0-19:   Minimal (documentation, cleanup)"
+        echo ""
+        echo "Examples:"
+        echo "  $0 enter --task-id auth --agent-id coder-1 --context iteration-1"
+        echo "  $0 wake --task-id auth --agent-id coder-1 --reason cfn_loop_iteration --iteration 2 --fork-id fork-1"
+        echo "  $0 wake --task-id auth --agent-id coder-1 --reason security_patch --priority 95"
+        echo "  $0 report --task-id auth --agent-id coder-1 --confidence 0.85 --iteration 1"
+        echo "  $0 collect --task-id auth --agent-ids coder-1,reviewer-1,tester-1"
+        echo "  $0 shutdown --task-id auth --reason task_complete"
+        exit 1
+        ;;
+esac

package/claude-assets/skills/cfn-redis-coordination/list-active-swarms.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+
+##############################################################################
+# List Active Swarms - Redis Coordination
+#
+# Queries Redis for all active swarm metadata to help track multiple
+# concurrent CFN Loop sessions.
+#
+# Usage:
+#   ./list-active-swarms.sh [--task-id <id>] [--mode <mode>] [--json]
+##############################################################################
+
+set -euo pipefail
+
+# Configuration
+TASK_ID_FILTER=""
+MODE_FILTER=""
+JSON_OUTPUT=false
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --task-id)
+      TASK_ID_FILTER="$2"
+      shift 2
+      ;;
+    --mode)
+      MODE_FILTER="$2"
+      shift 2
+      ;;
+    --json)
+      JSON_OUTPUT=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: $0 [--task-id <id>] [--mode <mode>] [--json]"
+      exit 1
+      ;;
+  esac
+done
+
+# Get all swarm metadata keys
+SWARM_KEYS=$(redis-cli --scan --pattern "swarm:*:metadata" 2>/dev/null || echo "")
+
+if [ -z "$SWARM_KEYS" ]; then
+  if [ "$JSON_OUTPUT" = true ]; then
+    echo '{"swarms": [], "count": 0}'
+  else
+    echo "No active swarms found"
+  fi
+  exit 0
+fi
+
+# Initialize JSON array
+if [ "$JSON_OUTPUT" = true ]; then
+  echo '{"swarms": ['
+  FIRST=true
+fi
+
+# Process each swarm
+while IFS= read -r KEY; do
+  if [ -z "$KEY" ]; then
+    continue
+  fi
+
+  # Extract swarm ID from key (swarm:swarm-<task-id>:metadata)
+  SWARM_ID=$(echo "$KEY" | sed 's/swarm:\(.*\):metadata/\1/')
+
+  # Get metadata
+  TASK_ID=$(redis-cli hget "$KEY" task_id 2>/dev/null || echo "")
+  MODE=$(redis-cli hget "$KEY" mode 2>/dev/null || echo "")
+  MAX_AGENTS=$(redis-cli hget "$KEY" max_agents 2>/dev/null || echo "")
+  LOOP3_AGENTS=$(redis-cli hget "$KEY" loop3_agents 2>/dev/null || echo "")
+  LOOP2_AGENTS=$(redis-cli hget "$KEY" loop2_agents 2>/dev/null || echo "")
+  PRODUCT_OWNER=$(redis-cli hget "$KEY" product_owner 2>/dev/null || echo "")
+  CREATED_AT=$(redis-cli hget "$KEY" created_at 2>/dev/null || echo "")
+  STATUS=$(redis-cli hget "$KEY" status 2>/dev/null || echo "in_progress")
+  FINAL_CONSENSUS=$(redis-cli hget "$KEY" final_consensus 2>/dev/null || echo "")
+  TOTAL_ITERATIONS=$(redis-cli hget "$KEY" total_iterations 2>/dev/null || echo "")
+  COMPLETED_AT=$(redis-cli hget "$KEY" completed_at 2>/dev/null || echo "")
+
+  # Apply filters
+  if [ -n "$TASK_ID_FILTER" ] && [ "$TASK_ID" != "$TASK_ID_FILTER" ]; then
+    continue
+  fi
+
+  if [ -n "$MODE_FILTER" ] && [ "$MODE" != "$MODE_FILTER" ]; then
+    continue
+  fi
+
+  # Output
+  if [ "$JSON_OUTPUT" = true ]; then
+    if [ "$FIRST" = false ]; then
+      echo ","
+    fi
+    FIRST=false
+
+    cat <<EOF
+  {
+    "swarm_id": "$SWARM_ID",
+    "task_id": "$TASK_ID",
+    "mode": "$MODE",
+    "status": "$STATUS",
+    "max_agents": $MAX_AGENTS,
+    "loop3_agents": "$LOOP3_AGENTS",
+    "loop2_agents": "$LOOP2_AGENTS",
+    "product_owner": "$PRODUCT_OWNER",
+    "created_at": "$CREATED_AT",
+    "final_consensus": "$FINAL_CONSENSUS",
+    "total_iterations": "$TOTAL_ITERATIONS",
+    "completed_at": "$COMPLETED_AT"
+  }
+EOF
+  else
+    echo "========================================="
+    echo "Swarm ID: $SWARM_ID"
+    echo "Task ID: $TASK_ID"
+    echo "Mode: $MODE"
+    echo "Status: $STATUS"
+    echo "Agents: $MAX_AGENTS total"
+    echo "  Loop 3: $LOOP3_AGENTS"
+    echo "  Loop 2: $LOOP2_AGENTS"
+    echo "  Product Owner: $PRODUCT_OWNER"
+    echo "Created: $CREATED_AT"
+
+    if [ -n "$COMPLETED_AT" ]; then
+      echo "Completed: $COMPLETED_AT"
+      echo "Final Consensus: $FINAL_CONSENSUS"
+      echo "Total Iterations: $TOTAL_ITERATIONS"
+    fi
+
+    echo ""
+  fi
+
+done <<< "$SWARM_KEYS"
+
+# Close JSON array
+if [ "$JSON_OUTPUT" = true ]; then
+  echo ""
+  echo "],"
+
+  # Count swarms
+  COUNT=$(echo "$SWARM_KEYS" | wc -l)
+  echo "\"count\": $COUNT"
+  echo "}"
+fi

package/claude-assets/skills/cfn-redis-coordination/log-event.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+##############################################################################
+# CFN Loop Event Logging to SQLite
+#
+# Usage:
+#   ./log-event.sh --task-id <id> --event-type <type> [options]
+#
+# Parameters:
+#   --task-id       Task/swarm identifier (required)
+#   --event-type    Event type: spawn, complete, gate_check, decision, error, etc. (required)
+#   --details       JSON payload with event-specific data (optional, default: {})
+#   --level         Log level: DEBUG, INFO, WARN, ERROR (optional, default: INFO)
+#   --loop          Loop identifier: loop3, loop2, product_owner, coordinator (optional)
+#   --agent-id      Agent identifier (optional)
+#   --iteration     Iteration number (optional)
+#
+# Example:
+#   ./log-event.sh \
+#     --task-id "cfn-task-123" \
+#     --event-type "agent_spawn" \
+#     --loop "loop3" \
+#     --agent-id "coder-1" \
+#     --iteration 1 \
+#     --details '{"agent_type": "coder", "timeout": 900}' \
+#     --level "INFO"
+##############################################################################
+
+set -euo pipefail
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Default to project root data/ directory (consistent with web portal)
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.claude/skills/cfn-cfn-.." && pwd)"
+DB_PATH="${DB_PATH:-${PROJECT_ROOT}/data/cfn-loop.db}"
+
+# Parameters
+TASK_ID=""
+EVENT_TYPE=""
+DETAILS="{}"
+LEVEL="INFO"
+LOOP=""
+AGENT_ID=""
+ITERATION=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --task-id) TASK_ID="$2"; shift 2 ;;
+    --event-type) EVENT_TYPE="$2"; shift 2 ;;
+    --details) DETAILS="$2"; shift 2 ;;
+    --level) LEVEL="$2"; shift 2 ;;
+    --loop) LOOP="$2"; shift 2 ;;
+    --agent-id) AGENT_ID="$2"; shift 2 ;;
+    --iteration) ITERATION="$2"; shift 2 ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Validate required parameters
+if [ -z "$TASK_ID" ] || [ -z "$EVENT_TYPE" ]; then
+  echo "Error: --task-id and --event-type are required" >&2
+  echo "Usage: $0 --task-id <id> --event-type <type> [--details <json>] [--level <level>] [--loop <loop>] [--agent-id <id>] [--iteration <n>]" >&2
+  exit 1
+fi
+
+# Validate JSON
+if ! echo "$DETAILS" | jq empty 2>/dev/null; then
+  echo "Error: --details must be valid JSON" >&2
+  exit 1
+fi
+
+# Create data directory if it doesn't exist
+mkdir -p "$(dirname "$DB_PATH")"
+
+# Initialize database schema if needed
+sqlite3 "$DB_PATH" <<'EOF'
+CREATE TABLE IF NOT EXISTS cfn_loop_logs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_id TEXT NOT NULL,
+  timestamp TEXT DEFAULT (datetime('now')),
+  event_type TEXT NOT NULL,
+  loop TEXT,
+  agent_id TEXT,
+  iteration INTEGER,
+  details TEXT,
+  level TEXT DEFAULT 'INFO'
+);
+
+CREATE INDEX IF NOT EXISTS idx_task_id ON cfn_loop_logs(task_id);
+CREATE INDEX IF NOT EXISTS idx_event_type ON cfn_loop_logs(event_type);
+CREATE INDEX IF NOT EXISTS idx_timestamp ON cfn_loop_logs(timestamp);
+CREATE INDEX IF NOT EXISTS idx_level ON cfn_loop_logs(level);
+EOF
+
+# Escape single quotes in JSON for SQLite
+DETAILS_ESCAPED="${DETAILS//\'/\'\'}"
+
+# Insert log entry
+sqlite3 "$DB_PATH" <<EOF
+INSERT INTO cfn_loop_logs (task_id, event_type, loop, agent_id, iteration, details, level)
+VALUES ('$TASK_ID', '$EVENT_TYPE', '$LOOP', '$AGENT_ID', '$ITERATION', '$DETAILS_ESCAPED', '$LEVEL');
+EOF
+
+# Also echo to stderr for orchestrator visibility (with timestamp)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+echo "[$TIMESTAMP] [$LEVEL] [$EVENT_TYPE] $DETAILS" >&2
+
+# Return success
+exit 0