claude-flow-novice 2.14.35 → 2.14.37

package/claude-assets/commands/switch-api.md

@@ -15,7 +15,7 @@ Switch Main Chat and Task() tool API provider between Z.ai (cost-optimized) and
 **Arguments:**
 - `status` - Show current routing configuration (default)
 - `zai` - Route Main Chat + Task tool to Z.ai for cost savings
-- `max` - Route Main Chat + Task tool to Anthropic for quality (also accepts `claude` or `anthropic` as aliases)
+- `max` or `claude` - Route Main Chat + Task tool to Anthropic for quality
 
 **What This Does:**
 

package/claude-assets/skills/cfn-error-logging/SKILL.md

@@ -0,0 +1,339 @@
+# CFN Error Logging Skill
+
+## Metadata
+- **Skill ID:** cfn-error-logging
+- **Version:** 1.0.0
+- **Category:** Error Management & Debugging
+- **Dependencies:** redis-coordination, system-diagnostics
+- **Maturity:** Production
+- **Last Updated:** 2025-11-10
+
+## Purpose
+Comprehensive error logging and diagnostic capture for CFN Loop failures. Creates detailed error reports that users can send for debugging when CFN loops fail in CLI or Docker modes.
+
+## Responsibilities
+1. **Error Detection**: Monitor CFN Loop execution for failures and exceptions
+2. **Diagnostic Capture**: Collect system state, logs, and configuration data
+3. **Report Generation**: Create user-friendly error reports with actionable information
+4. **Log Management**: Store, organize, and clean up error logs
+5. **Integration**: Hook into CLI and Docker CFN Loop failure points
+
+## Interface
+
+### Main Entry Point
+```bash
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action <capture|report|cleanup|list> \
+  --task-id <unique-id> \
+  [--error-type <orchestrator|agent-spawn|timeout|consensus|resource>] \
+  [--error-message <description>] \
+  [--exit-code <number>] \
+  [--context <json>]
+```
+
+### Parameters
+- `action`: Operation to perform (capture, report, cleanup, list)
+- `task-id`: Unique CFN Loop task identifier
+- `error-type`: Type of error that occurred
+- `error-message`: Human-readable error description
+- `exit-code`: Process exit code (if available)
+- `context`: Additional context data (JSON format)
+
+### Available Actions
+
+#### **capture** - Capture Error Data
+```bash
+# Automatic capture on CFN Loop failure
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action capture \
+  --task-id "cfn-cli-1731234567" \
+  --error-type "orchestrator" \
+  --error-message "Agent spawning failed" \
+  --exit-code 1
+```
+
+#### **report** - Generate User Report
+```bash
+# Generate user-friendly error report
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action report \
+  --task-id "cfn-cli-1731234567" \
+  --format "markdown"
+```
+
+#### **cleanup** - Manage Error Logs
+```bash
+# Clean old error logs (older than 7 days)
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action cleanup \
+  --retention-days 7
+```
+
+#### **list** - List Error Logs
+```bash
+# List all error logs
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action list \
+  --format "table"
+```
+
+## Data Captured
+
+### System Diagnostics
+- **Hardware**: CPU, memory, disk space usage
+- **Software**: OS version, Node.js version, npx version
+- **Dependencies**: Redis connectivity, Docker status
+- **Network**: Connection status, latency
+
+### CFN Loop State
+- **Configuration**: Task ID, mode, agent lists, thresholds
+- **Execution**: Current iteration, agent PIDs, timeouts
+- **Redis Data**: Task context, agent states, confidence scores
+- **Checkpoints**: Last successful iteration, saved state
+
+### Error Context
+- **Error Details**: Type, message, exit code, timestamp
+- **Stack Traces**: Process logs, error messages, debug output
+- **Environment**: Working directory, environment variables
+- **Process Tree**: Parent/child process relationships
+
+## Integration Points
+
+### CLI Loop Integration
+```bash
+# Add to orchestrate.sh error handling
+if [ $EXIT_CODE -ne 0 ]; then
+  ./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+    --action capture \
+    --task-id "$TASK_ID" \
+    --error-type "orchestrator" \
+    --error-message "CFN Loop failed at iteration $ITERATION" \
+    --exit-code $EXIT_CODE
+fi
+```
+
+### Docker Loop Integration
+```bash
+# Add to cfn-docker-loop-orchestration error handling
+if [ $CONTAINER_EXIT_CODE -ne 0 ]; then
+  ./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+    --action capture \
+    --task-id "$TASK_ID" \
+    --error-type "docker" \
+    --error-message "Container failed: $CONTAINER_NAME" \
+    --exit-code $CONTAINER_EXIT_CODE
+fi
+```
+
+### Agent Spawning Integration
+```bash
+# Add to agent spawning error handling
+if ! $SPAWN_COMMAND; then
+  ./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+    --action capture \
+    --task-id "$TASK_ID" \
+    --error-type "agent-spawn" \
+    --error-message "Failed to spawn agent: $AGENT_TYPE" \
+    --exit-code $?
+fi
+```
+
+## Error Report Format
+
+### Markdown Report (User-Friendly)
+```markdown
+# CFN Loop Error Report
+
+## 🚨 Error Summary
+- **Task ID**: cfn-cli-1731234567
+- **Error Type**: orchestrator
+- **Message**: Agent spawning failed
+- **Timestamp**: 2025-11-10 04:30:15 UTC
+- **Exit Code**: 1
+
+## 📋 Quick Diagnosis
+**Most Likely Cause**: npx not found or Redis connection failed
+**Recommended Action**: Check dependencies with pre-flight validation
+
+## 🔧 Troubleshooting Steps
+1. ✅ Check Node.js installation: `node --version`
+2. ✅ Check npx availability: `npx --version`
+3. ❌ Check Redis connection: `redis-cli ping`
+4. ✅ Check available memory: `free -h`
+
+## 📊 System State
+- **Memory Usage**: 65% (2.6GB/4GB)
+- **Disk Space**: 45GB available
+- **CPU Load**: 0.8
+- **Concurrent CFN Loops**: 3
+
+## 📝 Send This Report
+**To**: Your Claude assistant
+**Include**:
+- Complete error details above
+- Any recent changes to your setup
+- Steps you were trying to perform
+```
+
+## JSON Report (Machine-Readable)
+```json
+{
+  "task_id": "cfn-cli-1731234567",
+  "error_type": "orchestrator",
+  "error_message": "Agent spawning failed",
+  "timestamp": "2025-11-10T04:30:15Z",
+  "exit_code": 1,
+  "system_diagnostics": {...},
+  "cfn_state": {...},
+  "troubleshooting_steps": [...]
+}
+```
+
+## Storage and Management
+
+### Log Location
+- **Base Directory**: `/tmp/cfn_error_logs/`
+- **Individual Logs**: `/tmp/cfn_error_logs/cfn-error-<task-id>-<timestamp>.json`
+- **Reports**: `/tmp/cfn_error_logs/reports/cfn-report-<task-id>-<timestamp>.md`
+
+### Log Rotation
+- **Retention**: 7 days by default
+- **Cleanup**: Automatic cleanup on skill invocation
+- **Compression**: Compress logs older than 1 day
+- **Size Limit**: Maximum 100MB of error logs total
+
+### Privacy Considerations
+- **No Code**: Never captures source code content
+- **No Credentials**: Strips sensitive environment variables
+- **Local Storage**: All logs stored locally, user-controlled
+- **User Consent**: Error capture only on explicit failures
+
+## Usage Examples
+
+### Capture Error on CLI Loop Failure
+```bash
+# In cfn-loop-cli command
+if ! npx claude-flow-novice agent cfn-v3-coordinator ...; then
+  ./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+    --action capture \
+    --task-id "$TASK_ID" \
+    --error-type "cli-coordinator" \
+    --error-message "CLI coordinator failed to start"
+fi
+```
+
+### Generate Debug Report
+```bash
+# After CFN Loop failure
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action report \
+  --task-id "cfn-cli-1731234567" \
+  --format markdown > /tmp/cfn_error_report.md
+
+echo "📋 Error report saved to: /tmp/cfn_error_report.md"
+echo "📤 Send this file to your Claude assistant for debugging help"
+```
+
+### List Recent Errors
+```bash
+# List all recent errors
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action list \
+  --format table
+
+# List errors from last 24 hours
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action list \
+  --since "24h" \
+  --format json
+```
+
+## Error Categories
+
+### Orchestrator Errors
+- Configuration validation failures
+- Parameter parsing errors
+- Mode threshold mismatches
+- Resource allocation failures
+
+### Agent Spawning Errors
+- npx command failures
+- Node.js environment issues
+- Agent binary not found
+- Container runtime errors
+
+### Coordination Errors
+- Redis connection failures
+- Key conflicts and race conditions
+- Timeout errors
+- Consensus calculation failures
+
+### Resource Errors
+- Memory exhaustion
+- Disk space shortage
+- Process limit exceeded
+- Network connectivity issues
+
+### System Errors
+- Permission denied
+- File system errors
+- Signal termination
+- Unexpected crashes
+
+## Troubleshooting Guide
+
+### Common Error Patterns
+1. **"npx not found"**: Install Node.js and npx globally
+2. **"Redis connection failed"**: Start Redis server or check configuration
+3. **"Memory exhaustion"**: Close other applications or increase system memory
+4. **"Permission denied"**: Check file permissions and user access
+
+### Diagnostic Commands
+```bash
+# System health check
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action diagnostics
+
+# Dependency validation
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action validate-dependencies
+
+# Resource monitoring
+./.claude/skills/cfn-error-logging/invoke-error-logging.sh \
+  --action monitor-resources
+```
+
+## Best Practices
+
+### For Users
+1. **Send Complete Reports**: Include the full error report when asking for help
+2. **Provide Context**: Describe what you were trying to accomplish
+3. **Check Dependencies**: Run pre-flight validation before complex tasks
+4. **Monitor Resources**: Watch memory and disk usage during long-running tasks
+
+### For Developers
+1. **Integration Points**: Add error logging to all CFN Loop failure points
+2. **Error Categories**: Use appropriate error types for better classification
+3. **Context Capture**: Include relevant state information for debugging
+4. **Privacy**: Never capture sensitive data or code content
+
+### For System Administrators
+1. **Log Management**: Regular cleanup of old error logs
+2. **Monitoring**: Track error frequency and patterns
+3. **Resource Planning**: Ensure adequate memory and disk space
+4. **Dependency Management**: Keep Node.js, Redis, and Docker updated
+
+## Troubleshooting
+
+### Skill Failures
+If the error logging skill itself fails:
+1. **Check Permissions**: Ensure write access to `/tmp/`
+2. **Disk Space**: Verify available space for log files
+3. **Dependencies**: Check for required system tools (jq, bc, etc.)
+4. **Fallback**: Use manual error reporting with basic system diagnostics
+
+### Common Issues
+- **Permission Denied**: Fix directory permissions
+- **Disk Full**: Clean up old error logs
+- **Missing Tools**: Install required dependencies
+- **Timezone Issues**: Use UTC timestamps consistently

package/claude-assets/skills/cfn-error-logging/cleanup-error-logs.sh

@@ -0,0 +1,334 @@
+#!/bin/bash
+
+##############################################################################
+# CFN Error Logging - Cleanup and Management Script
+# Version: 1.0.0
+#
+# Automated cleanup and management for CFN error logs
+# Manages log rotation, compression, and retention policies
+#
+# Usage: ./cleanup-error-logs.sh [--retention-days 7] [--dry-run] [--force]
+##############################################################################
+
+set -euo pipefail
+
+# Configuration
+LOG_BASE_DIR="/tmp/cfn_error_logs"
+DEFAULT_RETENTION_DAYS=7
+MAX_TOTAL_SIZE_MB=100
+COMPRESS_THRESHOLD_DAYS=1
+
+# Parse arguments
+RETENTION_DAYS="$DEFAULT_RETENTION_DAYS"
+DRY_RUN=false
+FORCE=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --retention-days)
+      RETENTION_DAYS="$2"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --force)
+      FORCE=true
+      shift
+      ;;
+    --help|-h)
+      cat << EOF
+CFN Error Logging - Cleanup Script
+
+Usage: $0 [OPTIONS]
+
+Options:
+  --retention-days N    Delete logs older than N days (default: 7)
+  --dry-run            Show what would be deleted without actually deleting
+  --force              Skip confirmation prompts
+  --help, -h           Show this help message
+
+Examples:
+  $0                           # Standard cleanup (7-day retention)
+  $0 --retention-days 3        # Delete logs older than 3 days
+  $0 --dry-run                 # Preview what would be deleted
+  $0 --force --retention-days 1 # Force delete logs older than 1 day
+EOF
+      exit 0
+      ;;
+    *)
+      echo "❌ Unknown option: $1"
+      echo "Use --help for usage information"
+      exit 1
+      ;;
+  esac
+done
+
+# Logging function
+log() {
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"
+}
+
+# Ensure base directory exists
+mkdir -p "$LOG_BASE_DIR"
+
+# Get current disk usage of error logs
+get_disk_usage() {
+  if command -v du >/dev/null 2>&1; then
+    du -sm "$LOG_BASE_DIR" 2>/dev/null | cut -f1 || echo "0"
+  else
+    echo "0"
+  fi
+}
+
+# Get total size in MB with detailed breakdown
+get_size_breakdown() {
+  local total_size=0
+  local error_logs=0
+  local reports=0
+  local compressed=0
+  local other=0
+
+  if [ -d "$LOG_BASE_DIR" ]; then
+    # Error logs
+    if [ -d "$LOG_BASE_DIR/logs" ]; then
+      error_logs=$(du -sm "$LOG_BASE_DIR/logs" 2>/dev/null | cut -f1 || echo "0")
+    fi
+
+    # Reports
+    if [ -d "$LOG_BASE_DIR/reports" ]; then
+      reports=$(du -sm "$LOG_BASE_DIR/reports" 2>/dev/null | cut -f1 || echo "0")
+    fi
+
+    # Compressed logs
+    if [ -d "$LOG_BASE_DIR/compressed" ]; then
+      compressed=$(du -sm "$LOG_BASE_DIR/compressed" 2>/dev/null | cut -f1 || echo "0")
+    fi
+
+    # Other files
+    other=$(du -sm "$LOG_BASE_DIR" 2>/dev/null | cut -f1 || echo "0")
+    total_size=$((error_logs + reports + compressed + other))
+  fi
+
+  echo "$total_size,$error_logs,$reports,$compressed,$other"
+}
+
+# List files to be deleted
+list_files_to_delete() {
+  local cutoff_date
+  cutoff_date=$(date -d "$RETENTION_DAYS days ago" +%s 2>/dev/null || date -v-"$RETENTION_DAYS"d +%s)
+
+  find "$LOG_BASE_DIR" -type f -name "*.json" -o -name "*.md" -o -name "*.txt" | while read -r file; do
+    local file_date
+    file_date=$(stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || echo "0")
+
+    if [ "$file_date" -lt "$cutoff_date" ]; then
+      echo "$file"
+    fi
+  done
+}
+
+# Compress old logs
+compress_old_logs() {
+  local cutoff_date
+  cutoff_date=$(date -d "$COMPRESS_THRESHOLD_DAYS days ago" +%s 2>/dev/null || date -v-"$COMPRESS_THRESHOLD_DAYS"d +%s)
+
+  mkdir -p "$LOG_BASE_DIR/compressed"
+
+  log "🗜️ Compressing logs older than $COMPRESS_THRESHOLD_DAYS days..."
+
+  local compressed_count=0
+  find "$LOG_BASE_DIR" -type f -name "*.json" -not -path "*/compressed/*" | while read -r file; do
+    local file_date
+    file_date=$(stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || echo "0")
+
+    if [ "$file_date" -lt "$cutoff_date" ]; then
+      local basename
+      basename=$(basename "$file" .json)
+      local compressed_file="$LOG_BASE_DIR/compressed/${basename}.json.gz"
+
+      if [ ! -f "$compressed_file" ]; then
+        if gzip -c "$file" > "$compressed_file" 2>/dev/null; then
+          if [ "$DRY_RUN" != true ]; then
+            rm -f "$file"
+          fi
+          compressed_count=$((compressed_count + 1))
+          log "  Compressed: $(basename "$file") → $(basename "$compressed_file")"
+        fi
+      fi
+    fi
+  done
+
+  if [ "$compressed_count" -gt 0 ]; then
+    log "✅ Compressed $compressed_count log files"
+  else
+    log "ℹ️ No files needed compression"
+  fi
+}
+
+# Delete empty directories
+cleanup_empty_dirs() {
+  if [ "$DRY_RUN" != true ]; then
+    find "$LOG_BASE_DIR" -type d -empty -delete 2>/dev/null || true
+  fi
+}
+
+# Show cleanup summary
+show_summary() {
+  local before_size="$1"
+  local after_size="$2"
+  local files_deleted="$3"
+
+  local size_saved=$((before_size - after_size))
+
+  echo ""
+  echo "📊 Cleanup Summary:"
+  echo "  Files deleted: $files_deleted"
+  echo "  Space saved: ${size_saved}MB"
+  echo "  Current usage: ${after_size}MB"
+
+  if [ "$after_size" -gt "$MAX_TOTAL_SIZE_MB" ]; then
+    echo "  ⚠️  Warning: Error logs still exceed recommended size (${MAX_TOTAL_SIZE_MB}MB)"
+    echo "  Consider running with --retention-days $(($RETENTION_DAYS - 1)) to reduce further"
+  fi
+}
+
+# Main cleanup function
+run_cleanup() {
+  log "🧹 Starting CFN error log cleanup (retention: $RETENTION_DAYS days)"
+
+  # Get initial size
+  local size_breakdown
+  size_breakdown=$(get_size_breakdown)
+  local before_size
+  before_size=$(echo "$size_breakdown" | cut -d, -f1)
+
+  log "📊 Current disk usage: ${before_size}MB"
+
+  if [ "$before_size" -eq 0 ]; then
+    log "ℹ️ No error logs found to clean up"
+    return 0
+  fi
+
+  # Show size breakdown
+  local error_logs reports compressed other
+  IFS=, read -r error_logs reports compressed other <<< "$size_breakdown"
+
+  log "📁 Size breakdown:"
+  if [ "$error_logs" -gt 0 ]; then
+    log "  Error logs: ${error_logs}MB"
+  fi
+  if [ "$reports" -gt 0 ]; then
+    log "  Reports: ${reports}MB"
+  fi
+  if [ "$compressed" -gt 0 ]; then
+    log "  Compressed: ${compressed}MB"
+  fi
+  if [ "$other" -gt 0 ]; then
+    log "  Other: ${other}MB"
+  fi
+
+  # Compress old logs first
+  compress_old_logs
+
+  # List files to delete
+  local files_to_delete
+  files_to_delete=$(list_files_to_delete)
+
+  if [ -z "$files_to_delete" ]; then
+    log "ℹ️ No files older than $RETENTION_DAYS days found"
+
+    # Show final size after compression
+    local final_size
+    final_size=$(get_disk_usage)
+
+    if [ "$before_size" -ne "$final_size" ]; then
+      show_summary "$before_size" "$final_size" "0"
+    fi
+
+    cleanup_empty_dirs
+    return 0
+  fi
+
+  local file_count
+  file_count=$(echo "$files_to_delete" | wc -l)
+
+  log "📋 Found $file_count files older than $RETENTION_DAYS days:"
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "$files_to_delete" | head -10 | while read -r file; do
+      log "  Would delete: $(basename "$file") ($(du -sh "$file" 2>/dev/null | cut -f1 || echo "unknown"))"
+    done
+
+    if [ "$file_count" -gt 10 ]; then
+      log "  ... and $((file_count - 10)) more files"
+    fi
+
+    log "🔍 DRY RUN - No files were actually deleted"
+  else
+    # Show sample of files to be deleted
+    echo "$files_to_delete" | head -5 | while read -r file; do
+      log "  Deleting: $(basename "$file") ($(du -sh "$file" 2>/dev/null | cut -f1 || echo "unknown"))"
+    done
+
+    if [ "$file_count" -gt 5 ]; then
+      log "  ... and $((file_count - 5)) more files"
+    fi
+
+    # Confirmation prompt (unless forced)
+    if [ "$FORCE" != true ]; then
+      echo ""
+      read -p "Delete these $file_count files? [y/N] " -n 1 -r
+      echo ""
+
+      if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        log "❌ Cancelled by user"
+        return 0
+      fi
+    fi
+
+    # Delete files
+    local deleted_count=0
+    echo "$files_to_delete" | while read -r file; do
+      if rm -f "$file" 2>/dev/null; then
+        deleted_count=$((deleted_count + 1))
+      fi
+    done
+
+    log "✅ Deleted $deleted_count files"
+  fi
+
+  # Clean up empty directories
+  cleanup_empty_dirs
+
+  # Get final size
+  local after_size
+  after_size=$(get_disk_usage)
+
+  show_summary "$before_size" "$after_size" "$file_count"
+
+  log "✅ Cleanup completed"
+}
+
+# Check if running as root (warn about permission issues)
+if [ "$EUID" -eq 0 ]; then
+  log "⚠️ Running as root - this may affect log ownership"
+fi
+
+# Check disk space before cleanup
+local available_space
+available_space=$(df "$LOG_BASE_DIR" 2>/dev/null | awk 'NR==2{print int($4/1024)}' || echo "0")
+
+if [ "$available_space" -lt 50 ]; then
+  log "⚠️ Low disk space (${available_space}MB available) - forcing cleanup"
+  FORCE=true
+fi
+
+# Run cleanup
+run_cleanup
+
+# Log cleanup completion to system log if possible
+if command -v logger >/dev/null 2>&1; then
+  logger -t "cfn-error-logging" "Cleanup completed: retention=${RETENTION_DAYS}d, deleted=${file_count:-0} files"
+fi