claude-code-collective/README.md

Sub-agent collective framework for Claude Code with TDD validation, hub-spoke coordination, and automated handoffs

# Claude Code Sub-Agent Collective

[![npm version](https://badge.fury.io/js/claude-code-collective.svg)](https://badge.fury.io/js/claude-code-collective)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **NPX installer for the claude-code-sub-agent-collective system** - A research framework for reliable multi-agent coordination using hub-and-spoke architecture with Context Engineering.

## 🚀 Quick Start

Install the collective system in your project with one command:

```bash
npx claude-code-collective init
```

### ⚡ Latest Updates

**v1.3.7** - 🔧 **NPX Installer Fix**: Fixed agent library file installation. ResearchDrivenAnalyzer and other agent lib files now properly copy during NPX installation. Updated file-mapping.js to include agent lib directory mapping for complete template distribution.

**v1.3.6** - 🐛 **Critical Orchestrator Bug Fix**: Fixed premature TDD validation that was blocking implementation workflows. Hook now correctly distinguishes between deployment messages ("Deploying agent") and completion messages ("Phase completed"), preventing false validation triggers before work is actually done. Ensures proper sequencing: Orchestrator → Implementation → Completion → THEN Validation.

**v1.3.5** - 🧠 **Autonomous PRD Research Agent**: Major upgrade transforms prd-research-agent from delegation-heavy to fully autonomous. New ResearchDrivenAnalyzer class provides intelligent complexity scoring using Context7 patterns. 40% API reduction, 70% expansion efficiency, 100% research utilization. Agent now makes research-informed decisions instead of blind delegation.

**v1.3.4** - 🐛 **TDD Hook Dependency Fix**: Fixed false positive test failures when node_modules missing in .claude-collective/. Hook now automatically installs dependencies before running tests, preventing "Cannot find module" errors from blocking agent handoffs.

**v1.3.3** - ⚡ **TaskMaster Speed Optimization**: Eliminated slow Perplexity API calls from TaskMaster complexity analysis and task expansion. Agents now use fast Context7 research + pass results as context instead of triggering internal research calls. Same research quality, much faster execution.

**v1.3.2** - 🐛 **TDD Hook Fix**: Fixed build validation hook to check for package.json existence before running npm build. Prevents handoff failures in test environments without package.json.

**v1.3.1** - 🐛 **Critical Bug Fix**: Fixed false positive test failures in TDD validation system. Vitest output parsing now correctly recognizes `✓` success indicators and "Tests X passed (X)" format.

**v1.3.0** - **75-85% faster research phase!** We've optimized research agents by replacing slow TaskMaster research API calls with lightning-fast Context7 + Claude knowledge synthesis. Research quality maintained while dramatically improving speed.

## 📋 What is the Sub-Agent Collective?

The Claude Code Sub-Agent Collective is a research framework that proves three critical hypotheses:

1. **JIT Context Loading** - On-demand resource allocation improves efficiency over pre-loading
2. **Hub-and-Spoke Coordination** - Central hub coordination outperforms distributed agent communication  
3. **Test-Driven Handoffs** - Test-first handoffs improve quality and reduce integration failures

### Key Features

- **🎯 Behavioral Operating System**: CLAUDE.md defines agent coordination directives
- **🔄 Hub-and-Spoke Routing**: All requests flow through @routing-agent for optimal agent selection
- **🧪 Test-Driven Validation**: Every handoff includes contract validation for quality assurance
- **📊 Research Metrics**: Automatic collection of performance and coordination data
- **🛡️ Directive Enforcement**: Hook system ensures behavioral compliance

## 🛠️ Installation Options

### Interactive Installation
```bash
npx claude-code-collective init --interactive
```

### Quick Installations
```bash
# Full installation with all agents and testing
npx claude-code-collective init

# Minimal installation (core agents only)
npx claude-code-collective init --minimal

# Hooks and behavioral system only
npx claude-code-collective init --hooks-only

# Testing framework focused
npx claude-code-collective init --testing-only
```

## 📁 What Gets Installed

```
your-project/
├── CLAUDE.md                    # Behavioral directives
├── .claude/
│   ├── settings.json           # Hook configuration
│   ├── agents/                 # Agent definitions
│   │   ├── routing-agent.json
│   │   ├── testing-implementation-agent.json
│   │   └── ...
│   └── hooks/                  # Enforcement scripts
│       ├── directive-enforcer.sh
│       ├── collective-metrics.sh
│       └── ...
└── .claude-collective/
    ├── tests/                  # Test contracts
    ├── metrics/                # Research data
    └── package.json           # Testing framework
```

## 🔧 Management Commands

```bash
# Check installation status
npx claude-code-collective status

# Validate installation integrity  
npx claude-code-collective validate

# Repair corrupted installation
npx claude-code-collective repair

# Remove collective installation
npx claude-code-collective clean

# Get help
npx claude-code-collective --help
```

## 🎯 How It Works

### 1. Behavioral Operating System
The `CLAUDE.md` file defines three prime directives:
- **NEVER IMPLEMENT DIRECTLY** - All implementation flows through agents
- **COLLECTIVE ROUTING PROTOCOL** - Hub-and-spoke pattern maintained
- **TEST-DRIVEN VALIDATION** - Handoffs include contract validation

### 2. Agent Coordination
```mermaid
graph TD
    A[User Request] --> B[@routing-agent]
    B --> C[@implementation-agent]
    B --> D[@testing-agent] 
    B --> E[@research-agent]
    C --> F[Test Contract]
    D --> F
    E --> F
    F --> G[Quality Gates]
    G --> H[Success/Retry]
```

### 3. Hook Enforcement
- **PreToolUse**: Validates directives before execution
- **PostToolUse**: Collects metrics and validates outcomes
- **SubagentStop**: Ensures proper handoff validation

## 🧪 Testing Your Installation

After installation, test the collective:

```bash
# Validate installation
npx claude-code-collective validate

# Check status
npx claude-code-collective status

# In Claude Code, try:
# "Route this request through @routing-agent to create a login component"
```

## 📊 Research Metrics

The collective automatically collects:
- **JIT Metrics**: Context loading times and memory usage
- **Hub-Spoke Metrics**: Routing compliance and coordination overhead
- **TDD Metrics**: Handoff success rates and test pass rates

View metrics in `.claude-collective/metrics/`

## 🚨 Important Notes

### Restart Required
After installation, **restart Claude Code** to activate hooks and agents.

### Hook Compliance
The system enforces behavioral directives through hooks. Violations are logged and may block operations.

### Research Framework
This is a research system designed to prove coordination hypotheses. It may behave differently than expected if directives are bypassed.

## 🛠️ Requirements

- **Node.js**: >= 16.0.0
- **NPM**: >= 8.0.0
- **Claude Code**: Compatible with hook system

## 🐛 Troubleshooting

### Installation Issues
```bash
# Check Node.js version
node --version

# Clear npm cache
npm cache clean --force

# Force reinstall
npx claude-code-collective init --force

# Repair installation
npx claude-code-collective repair
```

### Hooks Not Working
1. Check `.claude/settings.json` syntax
2. Verify hook script permissions: `ls -la .claude/hooks/`
3. Restart Claude Code session
4. Run validation: `npx claude-code-collective validate`

### Agent Routing Issues
1. Verify agents installed: `npx claude-code-collective status`
2. Check behavioral directives in `CLAUDE.md`
3. Use explicit routing: `@routing-agent "your request"`

## 📚 Documentation

- **Installation Structure**: See files created in your project
- **Agent Definitions**: Check `.claude/agents/` directory
- **Hook Scripts**: Review `.claude/hooks/` for enforcement logic
- **Test Contracts**: Examine `.claude-collective/tests/` for validation

## 🤝 Support

### Common Issues
- **Permission Denied**: Use `sudo` on Unix systems or fix npm permissions
- **NPX Not Found**: Install with `npm install -g npx`
- **Installation Fails**: Check Node.js version and disk space

### Get Help
- Run `npx claude-code-collective validate` for diagnostics
- Check error logs in `/tmp/collective-install.log`
- Review installation status with `npx claude-code-collective status`

## 🔬 Research Goals

This collective system is designed to prove that:
1. **JIT context loading** reduces resource usage by >30%
2. **Hub-and-spoke coordination** achieves >95% routing accuracy  
3. **Test-driven handoffs** improve success rates to >98%

Metrics are automatically collected to validate these hypotheses.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🚀 Quick Reference

```bash
# Install
npx claude-code-collective init

# Status  
npx claude-code-collective status

# Validate
npx claude-code-collective validate

# Clean
npx claude-code-collective clean --force
```

---

**Research Framework** | **Hub-and-Spoke Architecture** | **Test-Driven Coordination** | **Context Engineering**