Research & Intelligence (Experimental)

• @research-agent - Context7-powered documentation lookup
• @prd-research-agent - Intelligent requirement breakdown
• @task-orchestrator - Smart task parallelization

System & Coordination

• /van command - Entry point that routes to @task-orchestrator
• @task-orchestrator - Central routing hub that picks the right specialist
• @behavioral-transformation-agent - System behavioral setup
• @hook-integration-agent - TDD enforcement automation
• @van-maintenance-agent - System maintenance and updates

Plus 20+ other specialized agents for specific development tasks.

Installation options

Quick install (recommended for trying it out)

npx claude-code-collective init

Other options if you want to be selective

# Just core agents for lightweight projects
npx claude-code-collective init --minimal

# Focus on testing framework only
npx claude-code-collective init --testing-only

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

# Interactive setup with choices
npx claude-code-collective init --interactive

What actually gets installed

your-project/
├── CLAUDE.md                    # Behavioral rules for agents
├── .claude/
│   ├── settings.json           # Hook configuration
│   ├── agents/                 # Agent definitions (30+ files)
│   │   ├── prd-research-agent.md
│   │   ├── task-orchestrator.md
│   │   ├── lib/
│   │   │   └── research-analyzer.js  # Complexity analysis engine
│   │   └── ... (lots more agents)
│   └── hooks/                  # TDD enforcement scripts
│       ├── test-driven-handoff.sh
│       └── collective-metrics.sh
└── .claude-collective/
    ├── tests/                  # Test framework templates
    ├── metrics/                # Usage tracking (for development)
    └── package.json           # Testing setup (Vitest)

How it works

1. /van command routes to @task-orchestrator (the routing hub) which analyzes requests and delegates to specialists
2. Research phase - agents use Context7 for real documentation
3. Tests written first - before any implementation
4. Implementation - minimal code to make tests pass
5. Refactoring - clean up while keeping tests green
6. Delivery - you see what tests were added and results

The TDD contract every agent follows

## DELIVERY COMPLETE
✅ Tests written first (RED phase)
✅ Implementation passes tests (GREEN phase)
✅ Code refactored for quality (REFACTOR phase)
📊 Test Results: X/X passing

Management commands

# Check what's installed and working
npx claude-code-collective status

# Validate installation integrity
npx claude-code-collective validate

# Fix broken installations
npx claude-code-collective repair

# Remove everything
npx claude-code-collective clean

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

Current state (honest assessment)

What works well

• TDD enforcement prevents a lot of bugs
• Context7 integration is much better than agents guessing
• Routing usually picks the right agent for the job
• Breaking down complex tasks is genuinely helpful

What's experimental/rough

• Some agents are still being refined
• Research phase can be slow sometimes
• Hook system requires restart (Claude Code limitation)
• Documentation is scattered across files

Known limitations

• Requires Node.js >= 16
• Need to restart Claude Code after installation
• Opinionated about TDD (if you don't like tests, skip this)
• Some agents might be too thorough/slow for simple tasks

Testing your installation

After installing:

# 1. Validate everything installed correctly
npx claude-code-collective validate

# 2. Check status
npx claude-code-collective status

# 3. Restart Claude Code (required for hooks)

# 4. Try it out
# In Claude Code: "Build a simple todo app with React"
# Expected: routes to research → breaks down task → writes tests → implements

Troubleshooting

Installation fails

• Check Node.js version: node --version (need >= 16)
• Clear npm cache: npm cache clean --force
• Try force install: npx claude-code-collective init --force

Agents don't work

• Restart Claude Code (hooks need to load)
• Check .claude/settings.json exists
• Run npx claude-code-collective validate

Tests don't run

• Make sure your project has a test runner (Jest, Vitest, etc.)
• Check if tests are actually being written to files
• Look at the TDD completion reports from agents

Research is slow

• Context7 might be having connectivity issues
• Agent might be being thorough (this varies)
• Check .claude-collective/metrics/ for timing data

Requirements

• Node.js: >= 16.0.0
• NPM: >= 8.0.0
• Claude Code: With MCP support and hook system
• Restart: Required after installation (hooks limitation)

What this is and isn't

What it is

• Experimental development aid for rapid prototyping
• Collection of TDD-focused AI agents
• Personal project that I use for my own MVPs
• Opinionated about test-first development

What it isn't

• Production-ready enterprise software
• Guaranteed to work perfectly
• Following any official standards
• A replacement for thinking or understanding code

Why TDD?

Because in my experience:

• Writing tests first forces better design thinking
• Tests catch bugs when they're cheap to fix
• Refactoring is safe with good test coverage
• Code with tests is easier to change later

The agents enforce this because I believe it leads to better outcomes. If you disagree with TDD philosophy, this tool probably isn't for you.

Research features (experimental)

To make agents smarter about modern development:

• Context7 integration - real, current library documentation
• ResearchDrivenAnalyzer - intelligent complexity assessment
• Smart task breakdown - only creates subtasks when actually needed
• Best practice application - research-informed patterns

This stuff is experimental and sometimes overthinks things, but generally helpful.

Solutions to common agent problems

AI agents can be unreliable. Here's what I built to deal with that:

Agents ignoring TDD rules: Hook system enforces test-first development before any code gets written.

Agents bypassing directives: CLAUDE.md behavioral operating system with prime directives that override default behavior.

Agents stopping mid-task: Test-driven handoff validation ensures work gets completed or explicitly handed off.

Agents making up APIs: Context7 integration forces agents to use real, current documentation.

Agents taking wrong approach: Central routing through @task-orchestrator hub prevents agents from self-selecting incorrectly.

Agents breaking coordination: Hub-and-spoke architecture eliminates peer-to-peer communication chaos.

Agents skipping quality steps: Quality gates that block completion until standards are met.

Agents losing context: Handoff contracts preserve required information across agent transitions.

Agents providing inconsistent output: Standardized TDD completion reporting from every implementation agent.

Agents working on wrong priorities: ResearchDrivenAnalyzer scores complexity to focus effort appropriately.

Most of these are enforced automatically through hooks and behavioral constraints, not just hoping agents follow instructions.

Support

This is a personal project, but:

• Issues welcome if you find bugs or have suggestions
• PRs welcome for small fixes or better agent prompts
• Don't expect rapid responses - this is a side project

Get help: Run npx claude-code-collective validate for diagnostics

License

MIT License - Use it, break it, fix it, whatever works for you.

Experimental | TDD-Focused | Personal Project | Use At Your Own Risk

Changelog

See CHANGELOG.md for detailed version history and release notes.