claude-flow-novice 2.14.28 → 2.14.30

package/claude-assets/skills/cfn-telemetry/collect-metrics.sh

@@ -0,0 +1,249 @@
+#!/bin/bash
+# CFN Telemetry Collection System
+# Real-time metrics collection for agent monitoring
+
+set -euo pipefail
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+TELEMETRY_DIR="${CFN_TELEMETRY_DIR:-$PROJECT_ROOT/.artifacts/telemetry}"
+COLLECTION_INTERVAL="${CFN_TELEMETRY_INTERVAL:-30}"  # seconds
+
+# Ensure telemetry directory exists
+mkdir -p "$TELEMETRY_DIR"
+
+# Function to collect agent metrics
+collect_agent_metrics() {
+    local agent_id="$1"
+    local agent_pid="$2"
+    local iteration="${3:-1}"
+    local agent_type="${4:-unknown}"
+
+    if ! kill -0 "$agent_pid" 2>/dev/null; then
+        echo "⚠️ Process $agent_pid no longer running" >&2
+        return 1
+    fi
+
+    # Collect memory and CPU usage
+    local memory_kb=$(ps -o rss= -p "$agent_pid" 2>/dev/null | tr -d ' ' || echo "0")
+    local cpu_percent=$(ps -o %cpu= -p "$agent_pid" 2>/dev/null | tr -d ' ' || echo "0")
+    local start_time=$(ps -o lstart= -p "$agent_pid" 2>/dev/null || echo "unknown")
+
+    # Calculate memory usage percentage
+    local memory_limit_kb=$((CFN_MEMORY_LIMIT * 1024))
+    local memory_usage_percent=$(echo "scale=1; $memory_kb * 100 / $memory_limit_kb" | bc -l 2>/dev/null || echo "0")
+
+    # Create metrics record
+    local metrics_file="$TELEMETRY_DIR/agent_${agent_id}_$(date +%s).json"
+    cat > "$metrics_file" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "collection_type": "agent_metrics",
+  "agent_id": "$agent_id",
+  "agent_type": "$agent_type",
+  "iteration": $iteration,
+  "pid": $agent_pid,
+  "process": {
+    "start_time": "$start_time",
+    "memory_kb": $memory_kb,
+    "cpu_percent": $cpu_percent,
+    "memory_limit_kb": $memory_limit_kb,
+    "memory_usage_percent": $memory_usage_percent
+  },
+  "limits": {
+    "memory_limit_mb": $CFN_MEMORY_LIMIT,
+    "timeout_seconds": $CFN_VALIDATION_TIMEOUT,
+    "cpu_limit_percent": $CFN_CPU_LIMIT
+  },
+  "environment": {
+    "cfn_mode": "${CFN_MODE:-unset}",
+    "task_id": "${TASK_ID:-unset}",
+    "validation_timeout": $CFN_VALIDATION_TIMEOUT
+  }
+}
+EOF
+
+    # Log summary
+    echo "📊 Collected metrics for $agent_id: ${memory_kb}KB memory, ${cpu_percent}% CPU" >&2
+
+    # Check for memory limit violations
+    if (( $(echo "$memory_usage_percent > 90" | bc -l) )); then
+        echo "⚠️ WARNING: $agent_id using ${memory_usage_percent}% of memory limit" >&2
+        collect_alert "$agent_id" "memory_warning" "Memory usage at ${memory_usage_percent}%"
+    fi
+
+    return 0
+}
+
+# Function to collect system metrics
+collect_system_metrics() {
+    local system_file="$TELEMETRY_DIR/system_$(date +%s).json"
+
+    # System resource usage
+    local system_memory=$(free -m | awk 'NR==2{printf "%.1f", $3*100/$2}')
+    local system_cpu=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | sed 's/%us,//')
+    local load_avg=$(uptime | awk -F'load average:' '{print $2}' | tr -d ' ')
+
+    cat > "$system_file" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "collection_type": "system_metrics",
+  "system": {
+    "memory_usage_percent": $system_memory,
+    "cpu_usage_percent": ${system_cpu:-0},
+    "load_average": "$load_avg"
+  },
+  "cfn_processes": {
+    "active_agents": $(pgrep -f "claude-flow-novice agent" | wc -l || echo 0),
+    "orchestrator_processes": $(pgrep -f "orchestrate.sh" | wc -l || echo 0)
+  }
+}
+EOF
+}
+
+# Function to collect alerts
+collect_alert() {
+    local agent_id="$1"
+    local alert_type="$2"
+    local message="$3"
+
+    local alert_file="$TELEMETRY_DIR/alert_$(date +%s).json"
+    cat > "$alert_file" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "alert_type": "$alert_type",
+  "agent_id": "$agent_id",
+  "message": "$message",
+  "severity": "warning"
+}
+EOF
+
+    echo "🚨 ALERT: $alert_type for $agent_id - $message" >&2
+}
+
+# Function to start continuous monitoring
+start_monitoring() {
+    local agent_id="$1"
+    local agent_pid="$2"
+    local iteration="${3:-1}"
+    local agent_type="${4:-unknown}"
+
+    echo "🔍 Starting monitoring for $agent_id (PID: $agent_pid)" >&2
+
+    # Initial metrics collection
+    collect_agent_metrics "$agent_id" "$agent_pid" "$iteration" "$agent_type"
+
+    # Start background monitoring
+    (
+        while kill -0 "$agent_pid" 2>/dev/null; do
+            sleep "$COLLECTION_INTERVAL"
+            collect_agent_metrics "$agent_id" "$agent_pid" "$iteration" "$agent_type"
+        done
+
+        # Final metrics when process exits
+        collect_agent_metrics "$agent_id" "$agent_pid" "$iteration" "$agent_type"
+        echo "✅ Monitoring ended for $agent_id" >&2
+    ) &
+
+    local monitor_pid=$!
+    echo "$monitor_pid"
+}
+
+# Function to stop monitoring
+stop_monitoring() {
+    local monitor_pid="$1"
+
+    if kill -0 "$monitor_pid" 2>/dev/null; then
+        kill "$monitor_pid" 2>/dev/null || true
+        wait "$monitor_pid" 2>/dev/null || true
+        echo "🛑 Stopped monitoring (PID: $monitor_pid)" >&2
+    fi
+}
+
+# Function to cleanup old telemetry files
+cleanup_telemetry() {
+    local retention_days="${1:-7}"
+    local cutoff_time=$(date -d "$retention_days days ago" +%s 2>/dev/null || echo 0)
+
+    find "$TELEMETRY_DIR" -name "*.json" -type f -mtime "+$retention_days" -delete 2>/dev/null || true
+    echo "🧹 Cleaned telemetry files older than $retention_days days" >&2
+}
+
+# Function to generate summary report
+generate_summary() {
+    local summary_file="$TELEMETRY_DIR/summary_$(date +%s).json"
+
+    local total_metrics=$(find "$TELEMETRY_DIR" -name "agent_*.json" | wc -l)
+    local total_alerts=$(find "$TELEMETRY_DIR" -name "alert_*.json" | wc -l)
+    local recent_metrics=$(find "$TELEMETRY_DIR" -name "agent_*.json" -mmin -60 | wc -l)
+
+    cat > "$summary_file" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "collection_type": "telemetry_summary",
+  "metrics": {
+    "total_agent_metrics": $total_metrics,
+    "recent_metrics_last_hour": $recent_metrics,
+    "total_alerts": $total_alerts
+  },
+  "system": {
+    "telemetry_directory": "$TELEMETRY_DIR",
+    "collection_interval_seconds": $COLLECTION_INTERVAL
+  }
+}
+EOF
+
+    echo "📈 Telemetry summary: $total_metrics total metrics, $total_alerts alerts" >&2
+}
+
+# Main execution
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    case "${1:-help}" in
+        "collect-agent")
+            collect_agent_metrics "$2" "$3" "${4:-1}" "${5:-unknown}"
+            ;;
+        "collect-system")
+            collect_system_metrics
+            ;;
+        "start-monitoring")
+            start_monitoring "$2" "$3" "${4:-1}" "${5:-unknown}"
+            ;;
+        "stop-monitoring")
+            stop_monitoring "$2"
+            ;;
+        "cleanup")
+            cleanup_telemetry "${2:-7}"
+            ;;
+        "summary")
+            generate_summary
+            ;;
+        "help"|"--help"|"-h")
+            cat <<'EOF'
+CFN Telemetry Collection System
+
+USAGE:
+    collect-metrics.sh <command> [args...]
+
+COMMANDS:
+    collect-agent <agent_id> <pid> [iteration] [type]    Collect single agent metrics
+    collect-system                                      Collect system metrics
+    start-monitoring <agent_id> <pid> [iteration] [type]  Start continuous monitoring
+    stop-monitoring <monitor_pid>                       Stop monitoring
+    cleanup [days]                                      Clean old telemetry files (default: 7 days)
+    summary                                             Generate summary report
+
+EXAMPLES:
+    collect-metrics.sh collect-agent reviewer_123 45678 1 reviewer
+    collect-metrics.sh start-monitoring tester_456 78901
+    collect-metrics.sh cleanup 3
+
+EOF
+            ;;
+        *)
+            echo "Unknown command: $1" >&2
+            echo "Use 'help' for usage information" >&2
+            exit 1
+            ;;
+    esac
+fi

package/claude-assets/skills/cfn-telemetry/start-telemetry.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+
+# Start Telemetry Collection for CFN Stabilization System
+# This script initializes and starts telemetry monitoring for agent execution
+
+set -euo pipefail
+
+# Required parameters
+TASK_ID="${1:-}"
+AGENT_ID="${2:-}"
+
+# Validate required parameters
+if [ -z "$TASK_ID" ] || [ -z "$AGENT_ID" ]; then
+    echo "Usage: $0 <task-id> <agent-id>"
+    exit 1
+fi
+
+# Get telemetry directory from environment or use default
+TELEMETRY_DIR="${CFN_TELEMETRY_DIR:-/tmp/cfn-telemetry}"
+mkdir -p "$TELEMETRY_DIR"
+
+# Get current timestamp
+TIMESTAMP=$(date -Iseconds)
+
+# Initialize telemetry session
+TELEMETRY_FILE="$TELEMETRY_DIR/${TASK_ID}_${AGENT_ID}_telemetry.json"
+
+# Create initial telemetry record
+cat > "$TELEMETRY_FILE" << TELEMETRY_EOF
+{
+    "task_id": "$TASK_ID",
+    "agent_id": "$AGENT_ID",
+    "session_start": "$TIMESTAMP",
+    "status": "active",
+    "memory_usage": 0,
+    "cpu_usage": 0,
+    "disk_usage": 0,
+    "file_count": 0,
+    "metrics": [],
+    "events": []
+}
+TELEMETRY_EOF
+
+# Start background telemetry collection
+BACKGROUND_PID=$$
+echo "$BACKGROUND_PID" > "$TELEMETRY_DIR/${TASK_ID}_${AGENT_ID}_pid.txt"
+
+# Initialize metrics collection
+echo "Starting telemetry collection for task $TASK_ID, agent $AGENT_ID"
+
+# Set up monitoring intervals (every 5 seconds)
+INTERVAL=5
+
+# Background telemetry monitoring function
+collect_telemetry() {
+    local start_time=$(date +%s)
+
+    while true; do
+        current_time=$(date +%s)
+        elapsed_time=$((current_time - start_time))
+
+        # Collect system metrics
+        memory_usage=$(free -m | grep Mem | awk '{print $3}')
+        cpu_usage=$(top -bn1 | grep "Cpu(s)" | sed "s/.*, *\([0-9.]*\)%* id.*/\1/" | awk '{print 100 - $1}')
+        disk_usage=$(df /tmp | tail -1 | awk '{print $5}' | tr -d '%')
+        file_count=$(find "$TELEMETRY_DIR" -name "*.json" -type f 2>/dev/null | wc -l)
+
+        # Create metric record
+        metric_record='{
+            "timestamp": "'$(date -Iseconds)'",
+            "elapsed_seconds": '"$elapsed_time"',
+            "memory_usage": '"$memory_usage"',
+            "cpu_usage": '"$cpu_usage"',
+            "disk_usage": '"$disk_usage"',
+            "file_count": '"$file_count"'
+        }'
+
+        # Append to telemetry file
+        jq --argjson metric "$metric_record" '.metrics += [$metric]' "$TELEMETRY_FILE" > "$TELEMETRY_FILE.tmp" 2>/dev/null || true
+        mv "$TELEMETRY_FILE.tmp" "$TELEMETRY_FILE" 2>/dev/null || true
+
+        # Sleep for interval
+        sleep $INTERVAL
+    done
+}
+
+# Start telemetry collection in background
+collect_tlemetry &
+TELEMETRY_COLLECTOR_PID=$!
+
+# Save collector PID
+echo "$TELEMETRY_COLLECTOR_PID" > "$TELEMETRY_DIR/${TASK_ID}_${AGENT_ID}_collector_pid.txt"
+
+# Log telemetry start event
+echo "Telemetry collection started for $TASK_ID:$AGENT_ID (PID: $TELEMETRY_COLLECTOR_PID)"
+
+# Keep script running while telemetry is active
+while kill -0 "$TELEMETRY_COLLECTOR_PID" 2>/dev/null; do
+    sleep 1
+done
+
+# Cleanup when telemetry stops
+TELEMETRY_STOP_TIME=$(date -Iseconds)
+jq --arg stop_time "$TELEMETRY_STOP_TIME" '.session_stop = $stop_time | .status = "stopped"' "$TELEMETRY_FILE" > "$TELEMETRY_FILE.tmp" 2>/dev/null || true
+mv "$TELEMETRY_FILE.tmp" "$TELEMETRY_FILE" 2>/dev/null || true
+
+# Remove PID files
+rm -f "$TELEMETRY_DIR/${TASK_ID}_${AGENT_ID}_pid.txt"
+rm -f "$TELEMETRY_DIR/${TASK_ID}_${AGENT_ID}_collector_pid.txt"
+
+echo "Telemetry collection stopped for $TASK_ID:$AGENT_ID"

package/claude-assets/skills/cfn-validation-runner-instrumentation/wrapped-executor.sh

@@ -0,0 +1,327 @@
+#!/bin/bash
+# CFN Validation Runner Instrumentation
+# Wraps Bun/Node/Playwright invocations with logging, timeouts, and cleanup
+
+set -euo pipefail
+
+# Script configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Configuration defaults
+DEFAULT_TIMEOUT="${CFN_VALIDATION_TIMEOUT:-300}"  # 5 minutes
+DEFAULT_MEMORY="${CFN_VALIDATION_MEMORY:-2048}"  # 2GB
+LOG_DIR="${CFN_VALIDATION_LOG_DIR:-$PROJECT_ROOT/.claude/logs/validation}"
+MONITOR_INTERVAL="${CFN_MONITOR_INTERVAL:-30}"  # 30 seconds
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Logging functions
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $(date '+%Y-%m-%d %H:%M:%S') - $1" | tee -a "$LOG_FILE"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $(date '+%Y-%m-%d %H:%M:%S') - $1" | tee -a "$LOG_FILE"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $(date '+%Y-%m-%d %H:%M:%S') - $1" | tee -a "$LOG_FILE"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $(date '+%Y-%m-%d %H:%M:%S') - $1" | tee -a "$LOG_FILE"
+}
+
+# Process monitoring
+monitor_process() {
+    local pid="$1"
+    local timeout="$2"
+    local command_name="$3"
+    local log_file="$4"
+
+    local elapsed=0
+    while kill -0 "$pid" 2>/dev/null; do
+        if [[ $elapsed -ge $timeout ]]; then
+            log_warning "Process $pid ($command_name) exceeded timeout ${timeout}s, terminating..."
+
+            # Get memory usage before termination
+            local memory_usage=$(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ' || echo "unknown")
+            log_error "Memory usage at termination: ${memory_usage}KB"
+
+            # Terminate the process gracefully
+            kill -TERM "$pid" 2>/dev/null || true
+            sleep 5
+
+            # Force kill if still running
+            if kill -0 "$pid" 2>/dev/null; then
+                log_error "Force killing process $pid ($command_name)"
+                kill -KILL "$pid" 2>/dev/null || true
+            fi
+
+            return 124  # Timeout exit code
+        fi
+
+        # Log periodic status
+        if [[ $((elapsed % MONITOR_INTERVAL)) -eq 0 && $elapsed -gt 0 ]]; then
+            local memory_usage=$(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ' || echo "unknown")
+            log_info "Process $pid ($command_name) running: ${elapsed}s elapsed, ${memory_usage}KB memory"
+        fi
+
+        sleep 1
+        ((elapsed++))
+    done
+
+    return 0
+}
+
+# Instrumented execution wrapper
+execute_instrumented() {
+    local command="$1"
+    local timeout="${2:-$DEFAULT_TIMEOUT}"
+    local memory_limit="${3:-$DEFAULT_MEMORY}"
+    shift 3
+    local args=("$@")
+
+    # Create log directory
+    mkdir -p "$LOG_DIR"
+
+    # Generate unique execution ID
+    local execution_id="exec_$(date +%Y%m%d_%H%M%S)_$$"
+    local log_file="$LOG_DIR/${execution_id}.log"
+    export LOG_FILE="$log_file"
+
+    # Extract command name for logging
+    local command_name=$(basename "$command")
+    local full_command="$command ${args[*]}"
+
+    # Start execution logging
+    log_info "=== Starting Instrumented Execution ==="
+    log_info "Execution ID: $execution_id"
+    log_info "Command: $full_command"
+    log_info "Timeout: ${timeout}s"
+    log_info "Memory Limit: ${memory_limit}MB"
+    log_info "Working Directory: $(pwd)"
+    log_info "Environment: CFN_MODE=${CFN_MODE:-unset}, NODE_OPTIONS=${NODE_OPTIONS:-unset}"
+
+    # Set up resource limits
+    local memory_limit_kb=$((memory_limit * 1024))
+
+    # Start the command with resource limits
+    local start_time=$(date +%s)
+    log_info "Starting process at $(date)"
+
+    # Launch command in background with resource limits
+    (
+        # Apply memory limit
+        ulimit -v "$memory_limit_kb" 2>/dev/null || {
+            log_warning "Could not set memory limit via ulimit"
+        }
+
+        # Apply Node.js specific memory limit
+        if [[ "$command_name" == "node" || "$command_name" == "bun" ]]; then
+            export NODE_OPTIONS="${NODE_OPTIONS:-} --max-old-space-size=$memory_limit"
+            log_info "Set NODE_OPTIONS: $NODE_OPTIONS"
+        fi
+
+        # Execute the command
+        exec "$command" "${args[@]}" 2>&1
+    ) &
+
+    local pid=$!
+    log_info "Process started with PID: $pid"
+
+    # Start monitoring in background
+    monitor_process "$pid" "$timeout" "$command_name" "$log_file" &
+    local monitor_pid=$!
+
+    # Wait for command completion
+    local exit_code=0
+    if wait "$pid" 2>/dev/null; then
+        exit_code=$?
+        log_success "Process $pid ($command_name) completed successfully"
+    else
+        exit_code=$?
+        if [[ $exit_code -eq 124 ]]; then
+            log_error "Process $pid ($command_name) timed out after ${timeout}s"
+        else
+            log_error "Process $pid ($command_name) failed with exit code: $exit_code"
+        fi
+    fi
+
+    # Stop monitoring
+    kill "$monitor_pid" 2>/dev/null || true
+    wait "$monitor_pid" 2>/dev/null || true
+
+    # Calculate execution time
+    local end_time=$(date +%s)
+    local duration=$((end_time - start_time))
+
+    # Final status logging
+    log_info "=== Execution Summary ==="
+    log_info "Command: $full_command"
+    log_info "Exit Code: $exit_code"
+    log_info "Duration: ${duration}s"
+    log_info "Memory Limit: ${memory_limit}MB"
+
+    # Log resource usage summary if available
+    if command -v ps >/dev/null 2>&1; then
+        local final_memory=$(ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ' || echo "unknown")
+        log_info "Final Memory: ${final_memory}KB"
+    fi
+
+    # Cleanup if process is still running
+    if kill -0 "$pid" 2>/dev/null; then
+        log_warning "Cleaning up still-running process $pid"
+        kill -TERM "$pid" 2>/dev/null || true
+        sleep 2
+        kill -KILL "$pid" 2>/dev/null || true
+    fi
+
+    # Archive log if successful
+    if [[ $exit_code -eq 0 ]]; then
+        local archive_log="$LOG_DIR/${execution_id}_success.log"
+        mv "$log_file" "$archive_log" 2>/dev/null || true
+        log_success "Log archived: $archive_log"
+    else
+        local archive_log="$LOG_DIR/${execution_id}_failed.log"
+        mv "$log_file" "$archive_log" 2>/dev/null || true
+        log_error "Failed log archived: $archive_log"
+    fi
+
+    return $exit_code
+}
+
+# Specific wrappers for common tools
+execute_node() {
+    local timeout="${1:-$DEFAULT_TIMEOUT}"
+    shift
+    log_info "Executing Node.js with instrumentation"
+    execute_instrumented "node" "$timeout" "$DEFAULT_MEMORY" "$@"
+}
+
+execute_bun() {
+    local timeout="${1:-$DEFAULT_TIMEOUT}"
+    shift
+    log_info "Executing Bun with instrumentation"
+    execute_instrumented "bun" "$timeout" "$DEFAULT_MEMORY" "$@"
+}
+
+execute_playwright() {
+    local timeout="${1:-$DEFAULT_TIMEOUT}"
+    shift
+    # Playwright may need more memory
+    local playwright_memory="${CFN_PLAYWRIGHT_MEMORY:-4096}"
+    log_info "Executing Playwright with instrumentation"
+    execute_instrumented "npx" "$timeout" "$playwright_memory" "playwright" "$@"
+}
+
+execute_npx() {
+    local timeout="${1:-$DEFAULT_TIMEOUT}"
+    shift
+    log_info "Executing NPX with instrumentation"
+    execute_instrumented "npx" "$timeout" "$DEFAULT_MEMORY" "$@"
+}
+
+# Cleanup old logs
+cleanup_logs() {
+    local max_days="${CFN_LOG_RETENTION_DAYS:-7}"
+    log_info "Cleaning up logs older than $max_days days"
+
+    find "$LOG_DIR" -name "*.log" -type f -mtime "+$max_days" -delete 2>/dev/null || true
+    log_info "Log cleanup completed"
+}
+
+# Show usage
+show_usage() {
+    cat <<'EOF'
+CFN Validation Runner Instrumentation
+
+USAGE:
+    source "$(dirname "${BASH_SOURCE[0]}")/wrapped-executor.sh"
+
+    # Generic Execution
+    execute_instrumented <command> [timeout] [memory_limit] [args...]
+
+    # Tool-Specific Wrappers
+    execute_node [timeout] [args...]           # Execute Node.js
+    execute_bun [timeout] [args...]            # Execute Bun
+    execute_playwright [timeout] [args...]     # Execute Playwright
+    execute_npx [timeout] [args...]            # Execute NPX
+
+    # Maintenance
+    cleanup_logs                               # Clean up old logs
+
+ENVIRONMENT VARIABLES:
+    CFN_VALIDATION_TIMEOUT      # Default timeout in seconds (default: 300)
+    CFN_VALIDATION_MEMORY       # Default memory limit in MB (default: 2048)
+    CFN_VALIDATION_LOG_DIR      # Log directory (default: ./.claude/logs/validation)
+    CFN_MONITOR_INTERVAL        # Monitoring interval in seconds (default: 30)
+    CFN_PLAYWRIGHT_MEMORY       # Playwright memory limit in MB (default: 4096)
+    CFN_LOG_RETENTION_DAYS      # Log retention in days (default: 7)
+
+EXAMPLES:
+    # Execute Node.js script with default settings
+    execute_node validate.js
+
+    # Execute Bun with custom timeout
+    execute_bun 600 build.ts
+
+    # Execute Playwright with longer timeout
+    execute_playwright 900 test.spec.js
+
+    # Generic execution with custom memory limit
+    execute_instrumented custom-tool 300 4096 --arg1 --arg2
+
+OUTPUT:
+    All executions generate detailed logs in ./.claude/logs/validation/
+    Logs include: start time, end time, memory usage, exit codes, timeouts
+
+EOF
+}
+
+# Main execution block
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+        show_usage
+        exit 0
+    fi
+
+    # Execute operation if provided
+    if [[ $# -gt 0 ]]; then
+        case "$1" in
+            "node")
+                shift
+                execute_node "$@"
+                ;;
+            "bun")
+                shift
+                execute_bun "$@"
+                ;;
+            "playwright")
+                shift
+                execute_playwright "$@"
+                ;;
+            "npx")
+                shift
+                execute_npx "$@"
+                ;;
+            "cleanup")
+                cleanup_logs
+                ;;
+            *)
+                echo "Unknown command: $1" >&2
+                echo "Use --help for usage information" >&2
+                exit 1
+                ;;
+        esac
+    else
+        echo "CFN Validation Runner Instrumentation" >&2
+        echo "Use --help for usage information" >&2
+    fi
+fi