telos-framework 0.2.0 → 0.3.0

package/.claude/docs/README.md

@@ -0,0 +1,214 @@
+# Claude Code Sub-Agent Collective
+
+## 📖 System Overview
+
+Welcome to your Claude Code Sub-Agent Collective installation! This system implements a research framework for reliable multi-agent coordination using hub-and-spoke architecture.
+
+### What Just Happened?
+
+The collective has been installed in your project with the following components:
+
+#### 🧠 Behavioral Operating System (`CLAUDE.md`)
+This file contains the core behavioral directives that govern how the collective operates:
+- **Directive 1**: Never implement directly - all work flows through agents
+- **Directive 2**: Hub-and-spoke routing - all requests go through @routing-agent
+- **Directive 3**: Test-driven validation - handoffs include contract validation
+
+#### 🤖 Agent Definitions (`.claude/agents/`)
+Each agent has specific capabilities and responsibilities:
+- **@routing-agent**: Central hub for semantic request analysis and routing
+- **@testing-implementation-agent**: Handles test frameworks and validation
+- **@behavioral-transformation-agent**: Manages behavioral system changes
+- **@hook-integration-agent**: Implements and manages hook systems
+
+#### 🪝 Hook Scripts (`.claude/hooks/`)
+Enforcement mechanisms that ensure directive compliance:
+- **directive-enforcer.sh**: Validates behavioral directives before tool execution
+- **collective-metrics.sh**: Collects performance and research metrics
+- **test-driven-handoff.sh**: Validates handoff contracts during transitions
+- **routing-executor.sh**: Executes routing decisions and agent handoffs
+
+#### 🧪 Testing Framework (`.claude-collective/`)
+Complete testing system for validating collective behavior:
+- **Jest configuration**: Set up for contract validation testing
+- **Test contracts**: Templates for handoff validation
+- **Metrics collection**: Research data gathering
+
+## 🚀 Getting Started
+
+### 1. Restart Claude Code
+**IMPORTANT**: Restart Claude Code to activate the hook system and agents.
+
+### 2. Test the Installation
+Try these commands to verify everything works:
+
+```bash
+# Check status
+npx claude-code-collective status
+
+# Validate installation
+npx claude-code-collective validate
+```
+
+### 3. Try Agent Routing
+In Claude Code, try a request like:
+> "Route this through @routing-agent to create a login component with validation"
+
+## 🎯 How to Use the Collective
+
+### Making Requests
+Instead of asking Claude directly, route requests through agents:
+
+**❌ Old Way (Direct):**
+> "Create a login form component"
+
+**✅ New Way (Agent Routed):**
+> "Route to @routing-agent: Create a login form component with React hooks"
+
+### Understanding Agent Routing
+The @routing-agent will analyze your request and select the best agent:
+- **Implementation tasks** → @implementation-agent
+- **Testing tasks** → @testing-implementation-agent  
+- **Research tasks** → @research-agent
+- **Hook/behavioral tasks** → @hook-integration-agent
+
+### Monitoring Activity
+- **Metrics**: Check `.claude-collective/metrics/` for performance data
+- **Logs**: Review `/tmp/collective-*.log` for detailed activity
+- **Status**: Run `npx claude-code-collective status` for health check
+
+## 📊 Research Framework
+
+This collective is designed to prove three key hypotheses:
+
+### H1: JIT Context Loading
+**Theory**: Loading context on-demand is more efficient than pre-loading
+**Measurement**: Context size, token reduction, load times
+**Goal**: >30% reduction in token usage
+
+### H2: Hub-and-Spoke Coordination  
+**Theory**: Central routing outperforms peer-to-peer communication
+**Measurement**: Routing accuracy, coordination overhead, violations
+**Goal**: >95% routing compliance
+
+### H3: Test-Driven Handoffs
+**Theory**: Contract-based handoffs improve quality
+**Measurement**: Handoff success rates, test pass rates, retry counts
+**Goal**: >98% handoff success rate
+
+## 🛡️ Behavioral Directives
+
+The collective enforces three prime directives through hooks:
+
+### Directive 1: Never Implement Directly
+- All implementation must flow through specialized agents
+- Direct coding by the hub controller is blocked
+- Violations trigger re-routing to @routing-agent
+
+### Directive 2: Collective Routing Protocol
+- All requests enter through @routing-agent
+- No direct agent-to-agent communication allowed
+- Hub-and-spoke pattern strictly maintained
+
+### Directive 3: Test-Driven Validation
+- Handoffs require test contracts with pre/post conditions
+- Failed validation triggers automatic re-routing
+- Quality gates ensure delivery standards
+
+## 🔧 Configuration
+
+### Hook Configuration (`.claude/settings.json`)
+Controls when and how hooks execute:
+- **PreToolUse**: Validates directives before tool execution
+- **PostToolUse**: Collects metrics and validates results
+- **SubagentStop**: Ensures proper handoff validation
+
+### Agent Configuration (`.claude/agents/*.json`)
+Each agent definition includes:
+- **Capabilities**: What the agent can do
+- **Tools**: Which Claude Code tools they can access
+- **Specialization**: Their primary focus area
+- **Fallbacks**: Alternative agents if unavailable
+
+### Testing Configuration (`.claude-collective/`)
+Jest-based testing framework:
+- **Contract templates**: Pre-built validation patterns
+- **Test suites**: Handoff, directive, and contract tests
+- **Coverage reporting**: Quality metrics and reporting
+
+## 🚨 Important Notes
+
+### System Behavior Changes
+With the collective active, Claude Code will behave differently:
+- **Routing Required**: Direct implementation requests may be blocked
+- **Hook Validation**: Actions are validated before execution
+- **Metrics Collection**: Performance data is automatically gathered
+- **Quality Gates**: Failed handoffs trigger retries or escalation
+
+### Troubleshooting
+If something isn't working:
+1. **Restart Claude Code** - Hooks need to be reloaded
+2. **Check Status** - Run `npx claude-code-collective status`
+3. **Validate Installation** - Run `npx claude-code-collective validate`
+4. **Review Logs** - Check `/tmp/collective-*.log` files
+5. **Repair Installation** - Run `npx claude-code-collective repair`
+
+### Getting Help
+- **Status Command**: `npx claude-code-collective status`
+- **Validation**: `npx claude-code-collective validate`  
+- **Repair**: `npx claude-code-collective repair`
+- **Documentation**: Review the files in `.claude/docs/`
+
+## 🔬 Research Participation
+
+By using this collective, you're participating in research on:
+- **Multi-agent coordination patterns**
+- **Context engineering efficiency** 
+- **Test-driven development practices**
+- **Behavioral enforcement systems**
+
+Metrics are collected automatically (no personal data) to validate the research hypotheses.
+
+## 🎯 Quick Reference
+
+### Essential Commands
+```bash
+# Check collective health
+npx claude-code-collective status
+
+# Validate everything is working  
+npx claude-code-collective validate
+
+# Fix problems
+npx claude-code-collective repair
+
+# Remove collective
+npx claude-code-collective clean
+```
+
+### Agent Routing Examples
+```
+"@routing-agent please create a user authentication system"
+"Route to appropriate agent: implement API endpoint for user login"
+"@routing-agent analyze the current codebase structure"
+```
+
+### File Structure
+```
+.claude/
+├── settings.json        # Hook configuration
+├── agents/             # Agent definitions  
+├── hooks/              # Enforcement scripts
+└── docs/               # This documentation
+
+.claude-collective/
+├── tests/              # Contract validation
+├── metrics/            # Research data
+└── package.json        # Testing framework
+```
+
+---
+
+**Welcome to the future of AI-assisted development!** 🚀
+
+The collective is now active and ready to coordinate your development work through intelligent agent routing and quality assurance.

package/.claude/docs/TROUBLESHOOTING.md

@@ -0,0 +1,126 @@
+# Claude Code Sub-Agent Collective - Troubleshooting Guide
+
+## Common Installation Issues
+
+### Template Files Not Found
+**Problem**: Warning messages about missing template files during installation.
+**Solution**: 
+1. Ensure you're using the latest version: `npx claude-code-collective@latest`
+2. Clear npm cache: `npm cache clean --force`
+3. Try installing with `--force` flag: `npx claude-code-collective --force`
+
+### Permission Errors
+**Problem**: EACCES errors when installing hooks or files.
+**Solution**:
+1. Run with appropriate permissions
+2. Check directory ownership: `ls -la .claude/`
+3. Fix permissions: `chmod +x .claude/hooks/*.sh`
+
+### Hook Execution Failures
+**Problem**: Hooks fail to execute or show permission denied.
+**Solution**:
+1. Make hooks executable: `chmod +x .claude/hooks/*.sh`
+2. Check shell compatibility (bash required)
+3. Verify hook syntax: `bash -n .claude/hooks/directive-enforcer.sh`
+
+## Agent System Issues
+
+### Agent Not Found
+**Problem**: Agent files exist but system doesn't recognize them.
+**Solution**:
+1. Check file extension (should be `.md`)
+2. Verify agent metadata format
+3. Restart Claude Code to refresh agent registry
+
+### Routing Failures
+**Problem**: Requests don't route to expected agents.
+**Solution**:
+1. Check CLAUDE.md routing patterns
+2. Verify agent capabilities in metadata
+3. Enable debug logging: add `--verbose` to commands
+
+### Test Failures
+**Problem**: TDD handoff tests fail unexpectedly.
+**Solution**:
+1. Run tests individually: `npm test -- --testNamePattern="specific test"`
+2. Check contract definitions in test files
+3. Verify agent implementations match contracts
+
+## Configuration Issues
+
+### Settings Not Applied
+**Problem**: Changes to `.claude/settings.json` don't take effect.
+**Solution**:
+1. Restart Claude Code completely
+2. Check JSON syntax: `node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json'))"`
+3. Verify hook configuration syntax
+
+### Metrics Collection Disabled
+**Problem**: Research metrics aren't being collected.
+**Solution**:
+1. Enable in research.config.json: `"enabled": true`
+2. Check storage permissions in metrics directory
+3. Verify MetricsCollector initialization
+
+## Performance Issues
+
+### Slow Agent Spawning
+**Problem**: Agent creation takes longer than expected.
+**Solution**:
+1. Check JIT loading configuration
+2. Reduce template complexity
+3. Monitor resource usage during spawning
+
+### High Memory Usage
+**Problem**: System uses excessive memory during operations.
+**Solution**:
+1. Adjust cleanup thresholds in AgentRegistry
+2. Enable periodic garbage collection
+3. Limit concurrent agent operations
+
+## Debug Mode
+
+Enable verbose logging for detailed troubleshooting:
+
+```bash
+# Set debug environment
+export DEBUG=claude-collective:*
+
+# Run with verbose output
+npx claude-code-collective --verbose --debug
+```
+
+## Getting Help
+
+1. **Documentation**: Check `.claude/docs/README.md` for system overview
+2. **Test Results**: Run `npm test` in `.claude-collective/` for system health
+3. **Log Files**: Check `.claude-collective/logs/` for detailed error logs
+4. **GitHub Issues**: Report bugs at the project repository
+
+## System Validation
+
+Run the built-in validation to check system health:
+
+```bash
+cd .claude-collective
+npm test
+npm run validate
+```
+
+Expected output: All tests passing, no validation errors.
+
+## Reset Instructions
+
+To completely reset the collective system:
+
+```bash
+# Remove all collective files
+rm -rf .claude/agents/*
+rm -rf .claude/hooks/*
+rm -rf .claude-collective/
+
+# Reinstall
+npx claude-code-collective --force
+```
+
+**Warning**: This will remove all customizations and configurations.

package/.claude/hooks/block-destructive-commands.sh

@@ -0,0 +1,243 @@
+#!/bin/sh
+# block-destructive-commands.sh
+# PreToolUse Hook - Block destructive commands before execution
+# Exit code 2 = BLOCK execution, Exit code 0 = ALLOW execution
+
+# Set up logging
+LOG_FILE="/tmp/blocked-commands.log"
+timestamp() { date '+%Y-%m-%d %H:%M:%S'; }
+
+log() {
+    echo "[$(timestamp)] $1" >> "$LOG_FILE"
+}
+
+# Read JSON input from stdin
+INPUT_JSON=$(cat)
+
+# Parse JSON using robust extraction (similar to test-driven-handoff.sh pattern)
+TOOL_NAME=""
+COMMAND=""
+
+# Try direct jq extraction first
+if command -v jq >/dev/null 2>&1; then
+    TOOL_NAME=$(echo "$INPUT_JSON" | jq -r '.tool_name' 2>/dev/null)
+    COMMAND=$(echo "$INPUT_JSON" | jq -r '.tool_input.command // ""' 2>/dev/null)
+fi
+
+# Fallback to grep/sed if jq fails or returns null
+if [ -z "$TOOL_NAME" ] || [ "$TOOL_NAME" = "null" ]; then
+    TOOL_NAME=$(echo "$INPUT_JSON" | grep -o '"tool_name":"[^"]*"' | cut -d'"' -f4)
+fi
+
+if [ -z "$COMMAND" ] || [ "$COMMAND" = "null" ]; then
+    COMMAND=$(echo "$INPUT_JSON" | grep -o '"command":"[^"]*"' | sed 's/.*"command":"\([^"]*\)".*/\1/')
+fi
+
+# Only check Bash tool commands
+if [ "$TOOL_NAME" != "Bash" ]; then
+    log "Skipping non-Bash tool: $TOOL_NAME"
+    exit 0
+fi
+
+log "Checking command for destructive patterns: $COMMAND"
+
+# Function to block command with reason
+block_command() {
+    local reason="$1"
+    local command="$2"
+    
+    echo "🚫 BLOCKED: $reason" >&2
+    echo "Command: $command" >&2
+    echo "Use manual approval or sandbox environment for dangerous operations" >&2
+    
+    log "BLOCKED: $reason - Command: $command"
+    exit 2  # Claude Code convention for blocking
+}
+
+# Check for filesystem destruction patterns
+check_filesystem_destruction() {
+    local cmd="$1"
+    
+    # Recursive force deletion
+    if echo "$cmd" | grep -qiE "rm\s+.*-.*r.*f|rm\s+.*-.*f.*r"; then
+        block_command "recursive force deletion (rm -rf)" "$cmd"
+    fi
+    
+    # Recursive deletion without confirmation
+    if echo "$cmd" | grep -qiE "rm\s+.*-r\s+"; then
+        block_command "recursive deletion without confirmation" "$cmd"
+    fi
+    
+    # Format commands
+    if echo "$cmd" | grep -qiE "mkfs\.|format\s+"; then
+        block_command "filesystem formatting command" "$cmd"
+    fi
+    
+    # Direct device writing
+    if echo "$cmd" | grep -qiE "dd\s+.*of=/dev/"; then
+        block_command "direct device writing with dd" "$cmd"
+    fi
+    
+    # System directory modifications
+    if echo "$cmd" | grep -qE ">\s*/etc/|>\s*/boot/|>\s*/sys/|>\s*/proc/"; then
+        block_command "writing to critical system directories" "$cmd"
+    fi
+}
+
+# Check for git destructive operations
+check_git_destruction() {
+    local cmd="$1"
+    
+    # Hard reset (loses uncommitted changes)
+    if echo "$cmd" | grep -qiE "git\s+reset\s+--hard"; then
+        block_command "git hard reset loses uncommitted changes" "$cmd"
+    fi
+    
+    # Force clean working directory
+    if echo "$cmd" | grep -qiE "git\s+clean\s+.*-.*f.*d|git\s+clean\s+.*-.*d.*f"; then
+        block_command "git force clean removes untracked files" "$cmd"
+    fi
+    
+    # Force push (can overwrite remote history)
+    if echo "$cmd" | grep -qiE "git\s+push\s+.*--force"; then
+        block_command "git force push can overwrite remote history" "$cmd"
+    fi
+    
+    # Rebase with force
+    if echo "$cmd" | grep -qiE "git\s+rebase\s+.*--force"; then
+        block_command "git force rebase can lose commits" "$cmd"
+    fi
+}
+
+# Check for package manager destructive operations
+check_package_manager_destruction() {
+    local cmd="$1"
+    
+    # npm create commands (can overwrite directories)
+    if echo "$cmd" | grep -qiE "npm\s+create\s+"; then
+        block_command "npm create can overwrite existing directories" "$cmd"
+    fi
+    
+    # npx create commands
+    if echo "$cmd" | grep -qiE "npx\s+create-"; then
+        block_command "npx create commands can overwrite files" "$cmd"
+    fi
+    
+    # yarn create commands
+    if echo "$cmd" | grep -qiE "yarn\s+create\s+"; then
+        block_command "yarn create can overwrite directories" "$cmd"
+    fi
+    
+    # pnpm create commands
+    if echo "$cmd" | grep -qiE "pnpm\s+create\s+"; then
+        block_command "pnpm create can overwrite directories" "$cmd"
+    fi
+    
+    # Force package installations (can break dependencies)
+    if echo "$cmd" | grep -qiE "npm\s+install\s+.*--force"; then
+        block_command "npm install --force can break dependencies" "$cmd"
+    fi
+    
+    # pip force reinstall
+    if echo "$cmd" | grep -qiE "pip\s+install\s+.*--force-reinstall"; then
+        block_command "pip force reinstall can break dependencies" "$cmd"
+    fi
+}
+
+# Check for database destruction
+check_database_destruction() {
+    local cmd="$1"
+    
+    # Drop database/table commands
+    if echo "$cmd" | grep -qiE "drop\s+(database|table|schema)"; then
+        block_command "database/table/schema drop command" "$cmd"
+    fi
+    
+    # Truncate table commands
+    if echo "$cmd" | grep -qiE "truncate\s+table"; then
+        block_command "table truncation command" "$cmd"
+    fi
+    
+    # Dangerous DELETE statements
+    if echo "$cmd" | grep -qiE "delete\s+from.*where\s+1\s*=\s*1"; then
+        block_command "delete all rows statement" "$cmd"
+    fi
+}
+
+# Check for docker/container destruction
+check_container_destruction() {
+    local cmd="$1"
+    
+    # Docker system prune
+    if echo "$cmd" | grep -qiE "docker\s+system\s+prune\s+.*-f"; then
+        block_command "docker force system prune removes all unused data" "$cmd"
+    fi
+    
+    # Docker remove all containers
+    if echo "$cmd" | grep -qiE "docker\s+rm\s+.*\$\(docker\s+ps"; then
+        block_command "docker remove all containers command" "$cmd"
+    fi
+    
+    # Kubernetes force delete
+    if echo "$cmd" | grep -qiE "kubectl\s+delete\s+.*--force"; then
+        block_command "kubectl force delete can cause data loss" "$cmd"
+    fi
+}
+
+# Check for network/download risks (Anthropic recommends blocking curl/wget)
+check_network_risks() {
+    local cmd="$1"
+    
+    # curl downloads to sensitive locations
+    if echo "$cmd" | grep -qiE "curl\s+.*>\s*/etc/|curl\s+.*>\s*/usr/|curl\s+.*>\s*/bin/"; then
+        block_command "curl download to system directories" "$cmd"
+    fi
+    
+    # wget downloads to sensitive locations  
+    if echo "$cmd" | grep -qiE "wget\s+.*-O\s*/etc/|wget\s+.*-O\s*/usr/|wget\s+.*-O\s*/bin/"; then
+        block_command "wget download to system directories" "$cmd"
+    fi
+    
+    # Piping untrusted content directly (Anthropic warns against this)
+    if echo "$cmd" | grep -qiE "curl\s+.*\|\s*(sh|bash|zsh)|wget\s+.*\|\s*(sh|bash|zsh)"; then
+        block_command "piping downloaded content to shell is dangerous" "$cmd"
+    fi
+}
+
+# Check for process/system destruction
+check_system_destruction() {
+    local cmd="$1"
+    
+    # Kill all processes
+    if echo "$cmd" | grep -qiE "killall\s+.*-9"; then
+        block_command "killall with SIGKILL can cause data loss" "$cmd"
+    fi
+    
+    # System shutdown/reboot
+    if echo "$cmd" | grep -qiE "shutdown\s+|reboot\s+|halt\s+"; then
+        block_command "system shutdown/reboot command" "$cmd"
+    fi
+    
+    # chmod 777 on system directories
+    if echo "$cmd" | grep -qE "chmod\s+777\s+/"; then
+        block_command "chmod 777 on system directories is dangerous" "$cmd"
+    fi
+    
+    # Suspicious bash with encoded content
+    if echo "$cmd" | grep -qiE "bash\s+-c\s+.*base64|sh\s+-c\s+.*base64"; then
+        block_command "suspicious encoded bash execution" "$cmd"
+    fi
+}
+
+# Run all destructive command checks
+check_filesystem_destruction "$COMMAND"
+check_git_destruction "$COMMAND"
+check_package_manager_destruction "$COMMAND" 
+check_database_destruction "$COMMAND"
+check_container_destruction "$COMMAND"
+check_network_risks "$COMMAND"
+check_system_destruction "$COMMAND"
+
+# If we get here, command is safe to execute
+log "ALLOWED: $COMMAND"
+exit 0