Claude Code Sub-Agent Collective
Experimental NPX installer for TDD-focused AI agents
This installs a collection of AI agents designed for Test-Driven Development and rapid prototyping. It's experimental, opinionated, and I built it to speed up my own MVP development work.
What this installs
npx claude-code-collective init
You get 30+ specialized agents that enforce TDD methodology and try to be smarter about using real documentation instead of guessing.
Why this exists
I got tired of:
- AI giving me code without tests
- Having to manually look up library documentation
- Inconsistent development approaches across projects
- Breaking down complex features manually
So I built agents that:
- Write tests first, always (RED → GREEN → REFACTOR)
- Use Context7 to pull real documentation
- Route work to specialists based on what needs doing
- Break down complex requests intelligently
What you get after installation
Core Implementation Agents (TDD-enforced)
- @component-implementation-agent - UI components with tests and modern patterns
- @feature-implementation-agent - Business logic with comprehensive testing
- @infrastructure-implementation-agent - Build systems with testing setup
- @testing-implementation-agent - Test suites that actually test things
- @polish-implementation-agent - Performance optimization with preserved tests
Quality & Validation
- @quality-agent - Code review and standards checking
- @devops-agent - Deployment and CI/CD setup
- @functional-testing-agent - Browser testing with Playwright
- @enhanced-quality-gate - Comprehensive validation gates
- @completion-gate - Task validation and completion checks
Research & Intelligence (Experimental)
- @research-agent - Context7-powered documentation lookup
- @prd-research-agent - Intelligent requirement breakdown
- @task-orchestrator - Smart task parallelization
System & Coordination
/vancommand - 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
/vancommand routes to @task-orchestrator (the routing hub) which analyzes requests and delegates to specialists- Research phase - agents use Context7 for real documentation
- Tests written first - before any implementation
- Implementation - minimal code to make tests pass
- Refactoring - clean up while keeping tests green
- 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.jsonexists - 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 Lice