telos-framework 0.1.4 → 0.3.0

package/.claude/hooks/collective-metrics.sh

@@ -0,0 +1,291 @@
+#!/bin/bash
+# collective-metrics.sh
+# Phase 3 - Hook Integration System
+# Collects performance metrics and coordination statistics for research validation
+
+# Set up metrics storage
+PROJECT_DIR=${CLAUDE_PROJECT_DIR:-"/mnt/h/Active/taskmaster-agent-claude-code"}
+METRICS_DIR="$PROJECT_DIR/.claude-collective/metrics"
+METRICS_FILE="$METRICS_DIR/metrics-$(date +%Y%m%d).json"
+LOG_FILE="$METRICS_DIR/collective-metrics.log"
+
+mkdir -p "$METRICS_DIR"
+
+timestamp() { date '+%Y-%m-%d %H:%M:%S'; }
+epoch_ms() { date +%s%3N; }
+
+log() {
+    echo "[$(timestamp)] $1" >> "$LOG_FILE"
+}
+
+# Initialize environment variables
+EVENT=${EVENT:-""}
+TOOL_NAME=${TOOL_NAME:-""}
+SUBAGENT_NAME=${SUBAGENT_NAME:-""}
+USER_PROMPT=${USER_PROMPT:-""}
+EXECUTION_TIME_MS=${EXECUTION_TIME_MS:-0}
+CLAUDE_PROJECT_DIR=${CLAUDE_PROJECT_DIR:-"/mnt/h/Active/taskmaster-agent-claude-code"}
+
+log "METRICS COLLECTION TRIGGERED - Event: $EVENT, Tool: $TOOL_NAME, Agent: $SUBAGENT_NAME"
+
+# Initialize metrics file if it doesn't exist
+initialize_metrics_file() {
+    if [[ ! -f "$METRICS_FILE" ]]; then
+        cat > "$METRICS_FILE" << 'EOF'
+{
+  "date": "",
+  "research_metrics": {
+    "jit_hypothesis": {
+      "context_load_times": [],
+      "memory_usage": [],
+      "agent_spawn_times": []
+    },
+    "hub_spoke_hypothesis": {
+      "routing_accuracy": [],
+      "coordination_overhead": [],
+      "peer_communication_violations": 0
+    },
+    "tdd_hypothesis": {
+      "handoff_success_rate": [],
+      "integration_defects": [],
+      "test_coverage": []
+    }
+  },
+  "performance_metrics": {
+    "tool_executions": [],
+    "agent_handoffs": [],
+    "directive_violations": [],
+    "quality_gates": []
+  },
+  "system_health": {
+    "uptime": 0,
+    "error_rate": 0,
+    "response_times": []
+  }
+}
+EOF
+        # Set the date
+        jq --arg date "$(date -I)" '.date = $date' "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        log "Initialized metrics file: $METRICS_FILE"
+    fi
+}
+
+# Collect JIT (Just-in-Time) Context Loading metrics
+collect_jit_metrics() {
+    local start_time="$1"
+    local context_size="$2"
+    
+    if [[ "$EVENT" == "PreToolUse" ]]; then
+        # Record context load time
+        local load_time=$(($(epoch_ms) - start_time))
+        
+        jq --argjson load_time "$load_time" \
+           --argjson context_size "${context_size:-0}" \
+           '.research_metrics.jit_hypothesis.context_load_times += [{
+             "timestamp": now,
+             "load_time_ms": $load_time,
+             "context_size": $context_size,
+             "tool": "'$TOOL_NAME'"
+           }]' "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        
+        log "JIT Metrics: Context load time: ${load_time}ms, Size: $context_size"
+    fi
+}
+
+# Collect Hub-Spoke Coordination metrics
+collect_hub_spoke_metrics() {
+    local routing_decision="$1"
+    local coordination_start="$2"
+    
+    if [[ "$EVENT" == "SubagentStop" ]]; then
+        # Calculate coordination overhead
+        local coordination_time=$(($(epoch_ms) - coordination_start))
+        
+        # Determine routing accuracy (simplified heuristic)
+        local accuracy=1
+        if echo "$USER_PROMPT" | grep -qi "error\|fail\|retry"; then
+            accuracy=0
+        fi
+        
+        jq --argjson accuracy "$accuracy" \
+           --argjson coord_time "$coordination_time" \
+           '.research_metrics.hub_spoke_hypothesis.routing_accuracy += [$accuracy] |
+            .research_metrics.hub_spoke_hypothesis.coordination_overhead += [{
+              "timestamp": now,
+              "coordination_time_ms": $coord_time,
+              "agent": "'$SUBAGENT_NAME'"
+            }]' "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        
+        log "Hub-Spoke Metrics: Accuracy: $accuracy, Coordination time: ${coordination_time}ms"
+    fi
+    
+    # Check for peer-to-peer communication violations
+    if echo "$USER_PROMPT" | grep -qi -E "@[a-z-]*agent.*@[a-z-]*agent"; then
+        jq '.research_metrics.hub_spoke_hypothesis.peer_communication_violations += 1' \
+           "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        log "Hub-Spoke Violation: Peer-to-peer communication detected"
+    fi
+}
+
+# Collect Test-Driven Development metrics
+collect_tdd_metrics() {
+    local handoff_quality="$1"
+    local test_coverage="$2"
+    
+    if [[ "$EVENT" == "SubagentStop" ]]; then
+        # Assess handoff success (simplified scoring)
+        local handoff_success=1
+        if echo "$USER_PROMPT" | grep -qi -E "error\|fail\|incomplete\|retry"; then
+            handoff_success=0
+        fi
+        
+        # Check for test mentions
+        local has_tests=0
+        if echo "$USER_PROMPT" | grep -qi -E "test\|spec\|coverage\|validate"; then
+            has_tests=1
+        fi
+        
+        jq --argjson success "$handoff_success" \
+           --argjson has_tests "$has_tests" \
+           --argjson coverage "${test_coverage:-0}" \
+           '.research_metrics.tdd_hypothesis.handoff_success_rate += [$success] |
+            .research_metrics.tdd_hypothesis.test_coverage += [{
+              "timestamp": now,
+              "coverage": $coverage,
+              "has_tests": $has_tests,
+              "agent": "'$SUBAGENT_NAME'"
+            }]' "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        
+        log "TDD Metrics: Handoff success: $handoff_success, Has tests: $has_tests, Coverage: $test_coverage"
+    fi
+}
+
+# Collect performance metrics
+collect_performance_metrics() {
+    local execution_start=$(epoch_ms)
+    
+    # Record tool execution
+    if [[ -n "$TOOL_NAME" ]]; then
+        jq --arg tool "$TOOL_NAME" \
+           --argjson exec_time "${EXECUTION_TIME_MS:-0}" \
+           '.performance_metrics.tool_executions += [{
+             "timestamp": now,
+             "tool": $tool,
+             "execution_time_ms": $exec_time,
+             "event": "'$EVENT'"
+           }]' "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        
+        log "Performance: Tool $TOOL_NAME executed in ${EXECUTION_TIME_MS}ms"
+    fi
+    
+    # Record agent handoffs
+    if [[ "$EVENT" == "SubagentStop" && -n "$SUBAGENT_NAME" ]]; then
+        jq --arg agent "$SUBAGENT_NAME" \
+           '.performance_metrics.agent_handoffs += [{
+             "timestamp": now,
+             "agent": $agent,
+             "event": "'$EVENT'"
+           }]' "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        
+        log "Performance: Agent handoff recorded for $SUBAGENT_NAME"
+    fi
+}
+
+# Collect system health metrics
+collect_system_health() {
+    # Update response times
+    if [[ "$EXECUTION_TIME_MS" -gt 0 ]]; then
+        jq --argjson response_time "$EXECUTION_TIME_MS" \
+           '.system_health.response_times += [$response_time]' \
+           "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+    fi
+    
+    # Calculate error rate (simplified)
+    local is_error=0
+    if echo "$USER_PROMPT" | grep -qi -E "error\|fail\|exception"; then
+        is_error=1
+    fi
+    
+    if [[ "$is_error" == "1" ]]; then
+        jq '.system_health.error_rate += 1' \
+           "$METRICS_FILE" > "$METRICS_FILE.tmp" && mv "$METRICS_FILE.tmp" "$METRICS_FILE"
+        log "System Health: Error detected and recorded"
+    fi
+}
+
+# Generate metrics summary
+generate_summary() {
+    if [[ ! -f "$METRICS_FILE" ]]; then
+        return 0
+    fi
+    
+    local summary_file="$METRICS_DIR/summary-$(date +%Y%m%d).txt"
+    
+    cat > "$summary_file" << EOF
+# Collective Metrics Summary - $(date)
+
+## Research Hypothesis Validation
+
+### JIT Hypothesis
+- Context load times collected: $(jq '.research_metrics.jit_hypothesis.context_load_times | length' "$METRICS_FILE")
+- Average load time: $(jq '[.research_metrics.jit_hypothesis.context_load_times[].load_time_ms] | add / length' "$METRICS_FILE" 2>/dev/null || echo "N/A")ms
+
+### Hub-Spoke Hypothesis  
+- Routing accuracy: $(jq '[.research_metrics.hub_spoke_hypothesis.routing_accuracy] | add / length * 100' "$METRICS_FILE" 2>/dev/null || echo "N/A")%
+- Peer communication violations: $(jq '.research_metrics.hub_spoke_hypothesis.peer_communication_violations' "$METRICS_FILE")
+
+### TDD Hypothesis
+- Handoff success rate: $(jq '[.research_metrics.tdd_hypothesis.handoff_success_rate] | add / length * 100' "$METRICS_FILE" 2>/dev/null || echo "N/A")%
+- Test coverage events: $(jq '.research_metrics.tdd_hypothesis.test_coverage | length' "$METRICS_FILE")
+
+## Performance Metrics
+- Tool executions: $(jq '.performance_metrics.tool_executions | length' "$METRICS_FILE")
+- Agent handoffs: $(jq '.performance_metrics.agent_handoffs | length' "$METRICS_FILE")
+- Average response time: $(jq '[.system_health.response_times] | add / length' "$METRICS_FILE" 2>/dev/null || echo "N/A")ms
+
+EOF
+    
+    log "Generated metrics summary: $summary_file"
+}
+
+# Main collection logic
+main() {
+    local start_time=$(epoch_ms)
+    
+    log "Starting metrics collection for event: $EVENT"
+    
+    # Initialize metrics file
+    initialize_metrics_file
+    
+    # Collect metrics based on event type
+    case "$EVENT" in
+        "PreToolUse")
+            collect_jit_metrics "$start_time" "$(echo "$USER_PROMPT" | wc -c)"
+            collect_performance_metrics
+            ;;
+        "PostToolUse")
+            collect_performance_metrics
+            collect_system_health
+            ;;
+        "SubagentStop")
+            collect_hub_spoke_metrics "routing" "$start_time"
+            collect_tdd_metrics "quality" "0"
+            collect_performance_metrics
+            ;;
+        *)
+            collect_performance_metrics
+            ;;
+    esac
+    
+    # Generate summary periodically (every 10th execution)
+    local execution_count=$(jq '.performance_metrics.tool_executions | length' "$METRICS_FILE" 2>/dev/null || echo "0")
+    if [[ $((execution_count % 10)) -eq 0 && $execution_count -gt 0 ]]; then
+        generate_summary
+    fi
+    
+    log "Metrics collection completed for event: $EVENT"
+    return 0
+}
+
+# Execute main function
+main "$@"

package/.claude/hooks/directive-enforcer.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# directive-enforcer.sh
+# Claude Code Sub-Agent Collective - Directive Enforcement Hook
+# Validates behavioral directives before tool execution
+
+# Set up logging
+LOG_FILE="/tmp/directive-enforcer.log"
+timestamp() { date '+%Y-%m-%d %H:%M:%S'; }
+
+log() {
+    echo "[$(timestamp)] $1" >> "$LOG_FILE"
+}
+
+# Initialize environment variables if not set
+USER_PROMPT=${USER_PROMPT:-""}
+TOOL_NAME=${TOOL_NAME:-""}
+CLAUDE_PROJECT_DIR=${CLAUDE_PROJECT_DIR:-"/mnt/h/Active/taskmaster-agent-claude-code"}
+
+log "DIRECTIVE ENFORCEMENT TRIGGERED - Tool: $TOOL_NAME"
+
+# DIRECTIVE 1: NEVER IMPLEMENT DIRECTLY
+# Block direct implementation when hub-and-spoke pattern should be used
+check_direct_implementation() {
+    local prompt="$1"
+    local tool="$2"
+    
+    # Check for implementation-related activities
+    if [[ "$tool" == "Write" || "$tool" == "Edit" || "$tool" == "MultiEdit" ]]; then
+        # Look for direct implementation phrases that violate hub-and-spoke
+        if echo "$prompt" | grep -qi -E "(implement|create.*code|write.*function|add.*feature|build.*component)"; then
+            # Check if this is coming from a specialized agent (allowed)
+            if ! echo "$prompt" | grep -qi "@.*-agent"; then
+                log "DIRECTIVE 1 VIOLATION: Direct implementation detected without agent routing"
+                echo "❌ DIRECTIVE VIOLATION: Direct implementation attempted"
+                echo "🔄 REQUIRED ACTION: Route through @routing-agent for proper agent selection"
+                echo "📋 VIOLATION: NEVER IMPLEMENT DIRECTLY - Use hub-and-spoke pattern"
+                return 1
+            fi
+        fi
+    fi
+    return 0
+}
+
+# DIRECTIVE 2: COLLECTIVE ROUTING PROTOCOL  
+# Ensure requests flow through proper routing channels
+check_routing_protocol() {
+    local prompt="$1"
+    
+    # Check for peer-to-peer agent communication violations
+    if echo "$prompt" | grep -qi -E "(@[a-z-]*agent.*@[a-z-]*agent|direct.*communication|bypass.*routing)"; then
+        log "DIRECTIVE 2 VIOLATION: Peer-to-peer agent communication detected"
+        echo "❌ ROUTING VIOLATION: Peer-to-peer agent communication not allowed"
+        echo "🔄 REQUIRED ACTION: Route all requests through @routing-agent hub"
+        return 1
+    fi
+    
+    return 0
+}
+
+# DIRECTIVE 3: TEST-DRIVEN VALIDATION
+# Ensure handoffs include proper test validation
+check_test_driven_validation() {
+    local prompt="$1"
+    local tool="$2"
+    
+    # Check for handoff scenarios without test validation
+    if echo "$prompt" | grep -qi -E "(handoff|hand.*off|transfer.*to|route.*to.*agent)"; then
+        if ! echo "$prompt" | grep -qi -E "(test|validate|verify|contract|quality.*gate)"; then
+            log "DIRECTIVE 3 WARNING: Handoff without explicit test validation mentioned"
+            echo "⚠️  TEST-DRIVEN WARNING: Handoff detected without test validation"
+            echo "📋 RECOMMENDATION: Include test contract validation in handoff"
+            # Don't block, just warn
+        fi
+    fi
+    
+    return 0
+}
+
+# Security validation - prevent malicious command injection
+validate_security() {
+    local prompt="$1"
+    
+    # Check for basic command injection patterns
+    if echo "$prompt" | grep -qi -E "(rm -rf|curl |wget |;s*rm|;s*curl|;s*wget)"; then
+        log "SECURITY VIOLATION: Potential command injection detected"
+        echo "🚨 SECURITY VIOLATION: Potentially malicious input detected"
+        return 1
+    fi
+    
+    return 0
+}
+
+# Main enforcement logic
+main() {
+    log "Starting directive enforcement for tool: $TOOL_NAME"
+    
+    # Run all validation checks
+    if ! validate_security "$USER_PROMPT"; then
+        exit 1
+    fi
+    
+    if ! check_direct_implementation "$USER_PROMPT" "$TOOL_NAME"; then
+        exit 1
+    fi
+    
+    if ! check_routing_protocol "$USER_PROMPT"; then
+        exit 1
+    fi
+    
+    check_test_driven_validation "$USER_PROMPT" "$TOOL_NAME"
+    
+    log "All directive checks passed for tool: $TOOL_NAME"
+    return 0
+}
+
+# Execute main function
+main "$@"

package/.claude/hooks/load-behavioral-system.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Load Collective Behavioral System
+# SessionStart hook to inject behavioral files into Claude's context
+
+echo "🚀 CLAUDE CODE COLLECTIVE INITIALIZATION SEQUENCE"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🤖 Activating Multi-Agent Behavioral Operating System..."
+echo "⚡ Loading Hub-Spoke Coordination Protocols..."
+echo "🧠 Initializing Context Engineering Framework..."
+echo ""
+
+echo "=== COLLECTIVE BEHAVIORAL RULES (.claude-collective/CLAUDE.md) ==="
+cat .claude-collective/CLAUDE.md
+echo ""
+
+echo "=== GLOBAL DECISION ENGINE (.claude-collective/DECISION.md) ==="
+cat .claude-collective/DECISION.md
+echo ""
+
+echo "=== SPECIALIZED AGENTS (.claude-collective/agents.md) ==="
+cat .claude-collective/agents.md
+echo ""
+
+echo "=== HOOK INTEGRATION (.claude-collective/hooks.md) ==="
+cat .claude-collective/hooks.md
+echo ""
+
+echo "=== QUALITY ASSURANCE (.claude-collective/quality.md) ==="
+cat .claude-collective/quality.md
+echo ""
+
+echo "=== RESEARCH FRAMEWORK (.claude-collective/research.md) ==="
+cat .claude-collective/research.md
+echo ""
+
+echo "=== TASKMASTER INTEGRATION (.taskmaster/CLAUDE.md) ==="
+cat .taskmaster/CLAUDE.md
+echo ""
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ BEHAVIORAL OPERATING SYSTEM ONLINE"
+echo "🎯 Prime Directives: LOADED"
+echo "🔗 Agent Network: 40+ Specialists ACTIVE"
+echo "📊 TDD Framework: ENGAGED"
+echo "🔄 Auto-Delegation: READY"
+echo "📡 Hub-Spoke Coordination: OPERATIONAL"
+echo ""
+echo "🌟 Claude Code Collective v1.4.3 - Ready for Enhanced Development"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/.claude/hooks/routing-executor.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+# No-op: routing is hub-only; this hook is disabled by config
+exit 0