claude-flow-novice 2.18.5 → 2.18.6

package/.claude/skills/cfn-edit-safety/lib/hooks/post-edit-handler.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+
+# Post-Edit Hook Handler - Sprint 2.2
+# Reusable wrapper for post-edit-pipeline.js with automatic feedback capture
+#
+# Usage:
+#   ./post-edit-handler.sh <file_path> [--memory-key <key>] [--agent-id <id>] [--coordinator-id <id>]
+#
+# Examples:
+#   ./post-edit-handler.sh src/example.js --memory-key "swarm/coder-1/step-2"
+#   ./post-edit-handler.sh test.js --agent-id "coder-1" --coordinator-id "coordinator-cfn"
+
+set -euo pipefail
+
+# Parse arguments
+FILE_PATH=""
+MEMORY_KEY=""
+AGENT_ID=""
+COORDINATOR_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --memory-key)
+            MEMORY_KEY="$2"
+            shift 2
+            ;;
+        --agent-id)
+            AGENT_ID="$2"
+            shift 2
+            ;;
+        --coordinator-id)
+            COORDINATOR_ID="$2"
+            shift 2
+            ;;
+        *)
+            if [ -z "$FILE_PATH" ]; then
+                FILE_PATH="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+# Validate required arguments
+if [ -z "$FILE_PATH" ]; then
+    echo "Error: File path required"
+    echo "Usage: $0 <file_path> [--memory-key <key>] [--agent-id <id>] [--coordinator-id <id>]"
+    exit 1
+fi
+
+# Auto-detect agent context from memory key if not provided
+if [ -z "$AGENT_ID" ] && [ -n "$MEMORY_KEY" ]; then
+    # Extract agent ID from memory key pattern: swarm/{agentId}/...
+    AGENT_ID=$(echo "$MEMORY_KEY" | grep -oP 'swarm/\K[^/]+' || echo "")
+fi
+
+# Set default memory key if not provided
+if [ -z "$MEMORY_KEY" ]; then
+    MEMORY_KEY="swarm/${AGENT_ID:-unknown}/hook-pipeline"
+fi
+
+# Build command arguments
+CMD_ARGS="$FILE_PATH --memory-key $MEMORY_KEY"
+if [ -n "$AGENT_ID" ]; then
+    CMD_ARGS="$CMD_ARGS --agent-id $AGENT_ID"
+fi
+if [ -n "$COORDINATOR_ID" ]; then
+    CMD_ARGS="$CMD_ARGS --coordinator-id $COORDINATOR_ID"
+fi
+
+echo "Executing post-edit pipeline: $FILE_PATH"
+echo "Memory key: $MEMORY_KEY"
+[ -n "$AGENT_ID" ] && echo "Agent ID: $AGENT_ID"
+[ -n "$COORDINATOR_ID" ] && echo "Coordinator ID: $COORDINATOR_ID"
+
+# Execute post-edit pipeline
+set +e  # Temporarily disable exit on error to capture exit code
+node config/hooks/post-edit-pipeline.js $CMD_ARGS
+EXIT_CODE=$?
+set -e  # Re-enable exit on error
+
+# Extract feedback from log
+LOG_FILE=".artifacts/logs/post-edit-pipeline.log"
+if [ ! -f "$LOG_FILE" ]; then
+    echo "Warning: Log file not found: $LOG_FILE"
+    exit $EXIT_CODE
+fi
+
+LAST_LOG_ENTRY=$(tail -n 1 "$LOG_FILE")
+STATUS=$(echo "$LAST_LOG_ENTRY" | jq -r '.status // "NO_STATUS"' 2>/dev/null || echo "NO_STATUS")
+
+echo "Validation status: $STATUS"
+
+# Handle feedback types
+case "$STATUS" in
+    "ROOT_WARNING")
+        echo "⚠️  ROOT_WARNING detected - automatic resolution available"
+        FEEDBACK_DIR=".artifacts/feedback"
+        mkdir -p "$FEEDBACK_DIR"
+        echo "$LAST_LOG_ENTRY" > "$FEEDBACK_DIR/pending-root-warning.json"
+        echo "Feedback saved to: $FEEDBACK_DIR/pending-root-warning.json"
+        echo "Run: ./claude/skills/hook-pipeline/feedback-resolver.sh --type ROOT_WARNING --auto-resolve"
+        exit 2  # Special exit code for ROOT_WARNING
+        ;;
+    "TDD_VIOLATION")
+        echo "⚠️  TDD_VIOLATION detected - test file missing or incomplete"
+        FEEDBACK_DIR=".artifacts/feedback"
+        mkdir -p "$FEEDBACK_DIR"
+        echo "$LAST_LOG_ENTRY" > "$FEEDBACK_DIR/pending-tdd-violation.json"
+        echo "Feedback saved to: $FEEDBACK_DIR/pending-tdd-violation.json"
+        echo "Run: ./claude/skills/hook-pipeline/feedback-resolver.sh --type TDD_VIOLATION"
+        exit 3  # Special exit code for TDD_VIOLATION
+        ;;
+    "LOW_COVERAGE")
+        echo "⚠️  LOW_COVERAGE detected - test coverage below threshold"
+        CURRENT=$(echo "$LAST_LOG_ENTRY" | jq -r '.current // 0')
+        REQUIRED=$(echo "$LAST_LOG_ENTRY" | jq -r '.required // 80')
+        echo "Current coverage: $CURRENT% (required: $REQUIRED%)"
+        FEEDBACK_DIR=".artifacts/feedback"
+        mkdir -p "$FEEDBACK_DIR"
+        echo "$LAST_LOG_ENTRY" > "$FEEDBACK_DIR/pending-low-coverage.json"
+        exit 4  # Special exit code for LOW_COVERAGE
+        ;;
+    "RUST_QUALITY")
+        echo "⚠️  RUST_QUALITY issues detected - run cargo clippy and rustfmt"
+        FEEDBACK_DIR=".artifacts/feedback"
+        mkdir -p "$FEEDBACK_DIR"
+        echo "$LAST_LOG_ENTRY" > "$FEEDBACK_DIR/pending-rust-quality.json"
+        echo "Run: ./claude/skills/hook-pipeline/feedback-resolver.sh --type RUST_QUALITY --auto-resolve"
+        exit 5  # Special exit code for RUST_QUALITY
+        ;;
+    "LINT_ISSUES")
+        echo "⚠️  LINT_ISSUES detected - run linter auto-fix"
+        FEEDBACK_DIR=".artifacts/feedback"
+        mkdir -p "$FEEDBACK_DIR"
+        echo "$LAST_LOG_ENTRY" > "$FEEDBACK_DIR/pending-lint-issues.json"
+        echo "Run: ./claude/skills/hook-pipeline/feedback-resolver.sh --type LINT_ISSUES --auto-resolve"
+        exit 6  # Special exit code for LINT_ISSUES
+        ;;
+    "NO_STATUS"|"SUCCESS"|"IMPROVEMENTS_SUGGESTED")
+        echo "✅ Validation passed"
+        [[ "$STATUS" == "IMPROVEMENTS_SUGGESTED" ]] && echo "ℹ️  Some improvements were suggested but no issues found"
+        ;;
+    *)
+        echo "⚠️  Unknown status: $STATUS"
+        ;;
+esac
+
+# Publish completion to Redis (if agent context available)
+if [ -n "$AGENT_ID" ]; then
+    REDIS_CHANNEL="swarm:skills:sprint-2.2:${AGENT_ID}:hooks"
+    redis-cli lpush "$REDIS_CHANNEL" "{\"file\": \"$FILE_PATH\", \"status\": \"$STATUS\", \"timestamp\": $(date +%s)}" >/dev/null 2>&1 || true
+fi
+
+exit $EXIT_CODE

package/.claude/skills/cfn-edit-safety/lib/hooks/security-scan.json

@@ -0,0 +1,60 @@
+{
+  "version": "1.4.0",
+  "modes": {
+    "basic": {
+      "checks": [
+        "SQL_INJECTION",
+        "XSS_VULNERABILITY",
+        "HARDCODED_SECRETS"
+      ],
+      "confidence_threshold": 70
+    },
+    "advanced": {
+      "checks": [
+        "SQL_INJECTION",
+        "XSS_VULNERABILITY",
+        "HARDCODED_SECRETS",
+        "INSECURE_DEPENDENCIES",
+        "POTENTIAL_RCE"
+      ],
+      "confidence_threshold": 85
+    },
+    "comprehensive": {
+      "checks": [
+        "SQL_INJECTION",
+        "XSS_VULNERABILITY",
+        "HARDCODED_SECRETS",
+        "INSECURE_DEPENDENCIES",
+        "POTENTIAL_RCE",
+        "DEPRECATED_CRYPTO",
+        "BUFFER_OVERFLOW"
+      ],
+      "confidence_threshold": 95
+    }
+  },
+  "patterns": {
+    "SQL_INJECTION": [
+      "(SELECT|INSERT|UPDATE|DELETE).*['\"].*['\" ]UNION|['\"]\\s*(--|#)",
+      "exec\\(.*sqlalchemy.*"
+    ],
+    "XSS_VULNERABILITY": [
+      "innerHTML\\.\\s*=",
+      "document\\.write\\(",
+      "eval\\("
+    ],
+    "HARDCODED_SECRETS": [
+      "password\\s*=\\s*['\"].*['\"]",
+      "secret_key\\s*=\\s*['\"].*['\"]",
+      "api_key\\s*=\\s*['\"].*['\"]{8,}",
+      "token\\s*=\\s*['\"].*['\"]{16,}"
+    ],
+    "INSECURE_DEPENDENCIES": [
+      "\"(version|dependencies)\":\\s*\"(<|>|<=|>=)?([0-9]+\\.){1,2}[0-9]+\""
+    ]
+  },
+  "exclusions": [
+    "/**/*.min.js",
+    "/**/*.test.js",
+    "/**/*.spec.js"
+  ]
+}

package/.claude/skills/cfn-edit-safety/lib/hooks/security-scanner.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# Claude Flow: Security Scanning Hook
+# Version: 1.4.0
+
+set -euo pipefail
+
+# Security Scanning Configuration
+SCAN_TYPES=(
+    "SQL_INJECTION"
+    "XSS_VULNERABILITY"
+    "HARDCODED_SECRETS"
+    "INSECURE_DEPENDENCIES"
+)
+
+# Logging Configuration
+LOG_DIR=".artifacts/security-logs"
+TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
+LOG_FILE="${LOG_DIR}/security-scan-${TIMESTAMP}.log"
+
+# Ensure log directory exists
+mkdir -p "${LOG_DIR}"
+
+# Create log file
+touch "${LOG_FILE}"
+
+# Security Scanning Function
+run_security_scan() {
+    local file_path="$1"
+    local file_extension="${file_path##*.}"
+    local scan_confidence=0
+    local vulnerabilities=()
+
+    echo "Scanning file: ${file_path}" >&2
+
+    # SQL Injection Detection
+    if grep -qE "(SELECT|INSERT|UPDATE|DELETE).*['\"].*['\"]" "${file_path}"; then
+        vulnerabilities+=("SQL_INJECTION")
+        ((scan_confidence+=25))
+    fi
+
+    # XSS Vulnerability Detection
+    if grep -qE "innerHTML|document\.write|eval\(" "${file_path}"; then
+        vulnerabilities+=("XSS_VULNERABILITY")
+        ((scan_confidence+=25))
+    fi
+
+    # Hardcoded Secrets Detection
+    if grep -qE "(password|secret|token|api_key).*=.*['\"]" "${file_path}"; then
+        vulnerabilities+=("HARDCODED_SECRETS")
+        ((scan_confidence+=25))
+    fi
+
+    # Dependency Vulnerability Detection (Basic)
+    if [[ "${file_extension}" == "json" ]] && grep -qE '"(version|dependencies)"' "${file_path}"; then
+        # Check for vulnerable package versions using basic regex (can be expanded)
+        if grep -qE '"(version|dependencies)".*[0-9]+\.[0-9]+\.[0-9]+' "${file_path}"; then
+            vulnerabilities+=("INSECURE_DEPENDENCIES")
+            ((scan_confidence+=25))
+        fi
+    fi
+
+    # Output JSON Results
+    local json_result
+    json_result=$(jq -n \
+        --arg confidence "${scan_confidence}" \
+        --arg passed "$([ ${#vulnerabilities[@]} -eq 0 ] && echo true || echo false)" \
+        --arg vulns "$(printf '%s\n' "${vulnerabilities[@]}" | jq -R . | jq -s .)" \
+        '{
+            passed: ($passed | test("true")),
+            confidence: ($confidence | tonumber),
+            vulnerabilities: $vulns
+        }')
+
+    # Write to log
+    if [ ${#vulnerabilities[@]} -gt 0 ]; then
+        echo "Security Vulnerabilities Detected in ${file_path}:" >&2
+        for vuln in "${vulnerabilities[@]}"; do
+            echo " - ${vuln}" >&2
+        done
+        echo "Confidence Score: ${scan_confidence}/100" >&2
+    else
+        echo "No security vulnerabilities detected in ${file_path}" >&2
+    fi
+
+    # Output JSON
+    echo "${json_result}"
+}
+
+# Main Security Scanning Logic
+main() {
+    local file_path="${1:?Provide file path to scan}"
+
+    # Skip scanning for certain file types or paths
+    if [[ "${file_path}" =~ \.(min\.|test\.|spec\.) ]]; then
+        jq -n '{
+            passed: true,
+            confidence: 100,
+            vulnerabilities: []
+        }'
+        exit 0
+    fi
+
+    run_security_scan "${file_path}"
+    exit_code=$?
+
+    # Exit with appropriate code for coordination
+    case ${exit_code} in
+        0)
+            exit 0  # No vulnerabilities
+            ;;
+        1)
+            exit 2  # Vulnerabilities detected (non-blocking)
+            ;;
+        *)
+            exit 1  # Unexpected error
+            ;;
+    esac
+}
+
+# Entry point
+main "$@"

package/.claude/skills/cfn-edit-safety/lib/hooks/test-root-warning-resolution.sh

@@ -0,0 +1,148 @@
+#!/bin/bash
+set -e
+
+RESULTS_FILE=".artifacts/analytics/root-warning-test.json"
+LOG_FILE=".artifacts/logs/post-edit-pipeline.log"
+mkdir -p .artifacts/analytics .artifacts/logs
+
+echo "═══════════════════════════════════════════════════════════"
+echo "🧪 Testing ROOT_WARNING Detection (50 test files)"
+echo "Hook Pipeline: Detect files in root, warn with suggested location"
+echo "═══════════════════════════════════════════════════════════"
+echo ""
+
+# Track results
+TOTAL_FILES=0
+WARNINGS_DETECTED=0
+FAILED_DETECTION=0
+declare -a FAILED_TESTS
+
+test_root_warning() {
+  local filename=$1
+  local expected_location=$2
+
+  TOTAL_FILES=$((TOTAL_FILES + 1))
+
+  # Create file in root directory (trigger ROOT_WARNING)
+  echo "Test content $TOTAL_FILES - $(date)" > "$filename"
+
+  echo -n "[Test $TOTAL_FILES] Creating $filename in root... "
+
+  # Run post-edit hook to detect ROOT_WARNING
+  local warning_detected=false
+  local suggested=""
+
+  # Check if hook script exists
+  if [ -f "config/hooks/post-edit-pipeline.js" ]; then
+    # Run actual hook (captures output)
+    HOOK_OUTPUT=$(node config/hooks/post-edit-pipeline.js "$filename" --memory-key "test/root-warning/$TOTAL_FILES" 2>&1)
+
+    # Check if ROOT_WARNING was printed
+    if echo "$HOOK_OUTPUT" | grep -q "ROOT DIRECTORY WARNING"; then
+      warning_detected=true
+      # Extract suggested location from output
+      suggested=$(echo "$HOOK_OUTPUT" | grep -A 1 "SUGGESTED LOCATIONS" | tail -1 | sed 's/.*\. \(.*\) (.*/\1/' | xargs)
+    fi
+
+    # Also check log file if it exists
+    if [ -f "$LOG_FILE" ]; then
+      LAST_LOG=$(tail -1 "$LOG_FILE" 2>/dev/null || echo '{}')
+      status=$(echo "$LAST_LOG" | jq -r '.status // "UNKNOWN"' 2>/dev/null || echo "UNKNOWN")
+      if [ "$status" = "ROOT_WARNING" ]; then
+        warning_detected=true
+      fi
+    fi
+  fi
+
+  # Validate warning detection
+  if [ "$warning_detected" = true ]; then
+    echo "✅ WARNING detected (suggested: $suggested or similar)"
+    WARNINGS_DETECTED=$((WARNINGS_DETECTED + 1))
+  else
+    echo "❌ No WARNING detected"
+    FAILED_DETECTION=$((FAILED_DETECTION + 1))
+    FAILED_TESTS+=("$filename (expected warning)")
+  fi
+
+  # Cleanup
+  rm -f "$filename"
+}
+
+echo "──────────────────────────────────────"
+echo "Testing source files (10 tests)"
+echo "──────────────────────────────────────"
+for i in {1..10}; do
+  test_root_warning "test-source-$i.js" "src/test-source-$i.js"
+done
+
+echo ""
+echo "──────────────────────────────────────"
+echo "Testing documentation files (10 tests)"
+echo "──────────────────────────────────────"
+for i in {1..10}; do
+  test_root_warning "test-doc-$i.md" "docs/test-doc-$i.md"
+done
+
+echo ""
+echo "──────────────────────────────────────"
+echo "Testing configuration files (10 tests)"
+echo "──────────────────────────────────────"
+for i in {1..10}; do
+  test_root_warning "test-config-$i.json" "config/test-config-$i.json"
+done
+
+echo ""
+echo "──────────────────────────────────────"
+echo "Testing test files (10 tests)"
+echo "──────────────────────────────────────"
+for i in {1..10}; do
+  test_root_warning "test-spec-$i.test.js" "tests/test-spec-$i.test.js"
+done
+
+echo ""
+echo "──────────────────────────────────────"
+echo "Testing script files (10 tests)"
+echo "──────────────────────────────────────"
+for i in {1..10}; do
+  test_root_warning "test-script-$i.sh" "scripts/test-script-$i.sh"
+done
+
+# Calculate detection rate
+DETECTION_RATE=$(echo "scale=2; ($WARNINGS_DETECTED / $TOTAL_FILES) * 100" | bc)
+
+# Generate report
+cat > $RESULTS_FILE << REPORT
+{
+  "total_files_tested": $TOTAL_FILES,
+  "warnings_detected": $WARNINGS_DETECTED,
+  "failed_detection": $FAILED_DETECTION,
+  "detection_rate": $DETECTION_RATE,
+  "passed": $(echo "$DETECTION_RATE == 100.00" | bc -l | grep -q 1 && echo "true" || echo "false"),
+  "threshold": 100,
+  "test_type": "warning_detection",
+  "test_date": "$(date -I)"
+}
+REPORT
+
+echo ""
+echo "═══════════════════════════════════════════════════════════"
+echo "TEST RESULTS"
+echo "═══════════════════════════════════════════════════════════"
+cat $RESULTS_FILE
+echo ""
+
+if [ $FAILED_DETECTION -gt 0 ]; then
+  echo "⚠️  Failed tests:"
+  for test in "${FAILED_TESTS[@]}"; do
+    echo "   - $test"
+  done
+  echo ""
+fi
+
+if echo "$DETECTION_RATE == 100.00" | bc -l | grep -q 1; then
+  echo "✅ SUCCESS: 100% ROOT_WARNING detection rate ($WARNINGS_DETECTED/$TOTAL_FILES)"
+  exit 0
+else
+  echo "❌ FAILED: ${DETECTION_RATE}% detection rate ($WARNINGS_DETECTED/$TOTAL_FILES detected)"
+  exit 1
+fi

package/.claude/skills/cfn-epic-parser/SKILL.md

@@ -0,0 +1,220 @@
+# CFN Epic Parser
+
+## Overview
+
+The cfn-epic-parser skill converts natural language epic documents written in markdown format into structured JSON configurations suitable for execution in either MDAP or CFN Loop modes.
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Parse with auto-detected mode
+./.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md
+
+# Force MDAP mode
+./.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --mode mdap
+
+# Force CFN Loop mode with output file
+./.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --mode cfn-loop --output epic-config.json
+
+# Validate epic structure without generating output
+./.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --validate
+
+# Enable verbose logging
+./.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --verbose
+```
+
+### Command Line Options
+
+- `<input.md>`: Path to the epic markdown file to parse (required)
+- `-o, --output <file>`: Output JSON file path (default: stdout)
+- `-m, --mode <mode>`: Execution mode: `mdap`, `cfn-loop`, or `auto` (default: auto)
+- `-v, --validate`: Validate epic structure without generating output
+- `-V, --verbose`: Enable verbose logging
+- `-h, --help`: Show help message
+
+### Mode Descriptions
+
+- **auto**: Automatically detect mode based on epic content
+  - Detects CFN Loop mode if multiple phases are defined
+  - Defaults to MDAP mode for single-phase epics
+- **mdap**: Generate MDAP-compatible configuration for atomic task execution
+  - Creates task-based structure with maxTaskSize of 50 lines
+  - Atomic execution with pre-loaded context injection
+- **cfn-loop**: Generate CFN Loop configuration for phased execution
+  - Creates phase-based structure with dependencies
+  - Configures consensus and gate thresholds for validation
+
+## Epic Document Format
+
+The parser expects markdown files with the following structure:
+
+### Required Sections
+
+```markdown
+# Epic Title
+
+**Epic ID**: `unique-epic-identifier`
+**Status**: [Not Started | In Progress | Completed]
+**Estimated Duration**: [X weeks]
+**Owner**: [Team or individual]
+**Priority**: [Low | Medium | High]
+
+## Epic Description
+
+Detailed description of the epic goals and scope.
+
+## Strategic Goals
+
+1. Goal one description
+2. Goal two description
+3. ...
+
+## Phases (for CFN Loop)
+
+### Phase 1: Phase Name
+**Status**: Not Started
+**Duration**: X weeks
+**Dependencies**: [None | Phase X, Phase Y]
+
+Description of phase goals.
+
+### Phase 2: Phase Name
+...
+```
+
+### Optional Fields
+
+- **Agents**: Number of agents involved (e.g., `Agents: 50`)
+- **File**: Reference to phase file (e.g., `File: planning/phase-1.md`)
+- **Deliverables**: List of expected deliverables
+- **Acceptance Criteria**: Checklist of completion criteria
+
+## Output Format
+
+### MDAP Mode Output
+
+```json
+{
+  "executionMode": "mdap",
+  "metadata": {
+    "epicId": "unique-identifier",
+    "name": "Epic Title",
+    "description": "Epic description",
+    "status": "not_started",
+    "priority": "high",
+    "estimatedDuration": "10 weeks",
+    "owner": "Team Name"
+  },
+  "goals": ["Goal 1", "Goal 2", "Goal 3"],
+  "tasks": [],
+  "configuration": {
+    "maxTaskSize": 50,
+    "atomicExecution": true,
+    "contextInjection": "pre-loaded"
+  }
+}
+```
+
+### CFN Loop Mode Output
+
+```json
+{
+  "executionMode": "cfn-loop",
+  "metadata": { ... },
+  "phases": [
+    {
+      "phaseId": "phase-1",
+      "name": "Phase Name",
+      "description": "Phase description",
+      "status": "not_started",
+      "estimatedDuration": "5 weeks",
+      "dependencies": []
+    },
+    ...
+  ],
+  "goals": ["Goal 1", "Goal 2", "Goal 3"],
+  "configuration": {
+    "loopMode": "standard",
+    "consensusThreshold": 0.90,
+    "gateThreshold": 0.95
+  }
+}
+```
+
+## Testing
+
+Run the test suite to verify parser functionality:
+
+```bash
+./.claude/skills/cfn-epic-parser/test-parser.sh
+```
+
+The test suite validates:
+- Help output and error handling
+- Metadata extraction (ID, status, priority, etc.)
+- Phase parsing and dependency tracking
+- Goal extraction from Strategic Goals section
+- Mode auto-detection based on content
+- Validation of epic structure
+- File output generation
+
+## Dependencies
+
+- `jq`: Required for JSON processing
+  - Ubuntu/Debian: `sudo apt-get install jq`
+  - macOS: `brew install jq`
+
+## Examples
+
+### Parse Marketing Epic
+
+```bash
+./.claude/skills/cfn-epic-parser/parse.sh \
+  planning/global/marketing/EPIC_OVERVIEW.md \
+  --mode cfn-loop \
+  --output marketing-epic-config.json
+```
+
+### Validate Epic Structure
+
+```bash
+./.claude/skills/cfn-epic-parser/parse.sh \
+  planning/my-new-epic.md \
+  --validate --verbose
+```
+
+### Generate MDAP Configuration
+
+```bash
+./.claude/skills/cfn-epic-parser/parse.sh \
+  planning/simple-feature-epic.md \
+  --mode mdap \
+  --output simple-feature-config.json
+```
+
+## Error Handling
+
+The parser provides clear error messages for:
+- Missing input files
+- Invalid execution modes
+- Malformed epic structure
+- Missing required fields
+- JSON validation failures
+
+## Integration with CFN Workflows
+
+The generated JSON configurations can be used by:
+- CFN Loop orchestrator for phased execution
+- MDAP decomposer for atomic task generation
+- Epic management tools for tracking progress
+- Validation agents for structure compliance
+
+## Best Practices
+
+1. **Consistent Epic IDs**: Use lowercase with hyphens (e.g., `user-authentication-v2`)
+2. **Clear Phase Dependencies**: Explicitly list dependencies in each phase
+3. **Specific Goals**: Use numbered lists for strategic goals
+4. **Descriptive Phases**: Include duration and clear deliverables
+5. **Status Tracking**: Keep status updated for accurate reporting