Sub-agent collective framework for Claude Code with TDD validation, TaskMaster Task ID integration, hub-spoke coordination, and deterministic handoffs
npm install claude-code-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.
``bash`
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.
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:
1. Write tests first, always (RED → GREEN → REFACTOR)
2. Use Context7 to pull real documentation
3. Route work to specialists based on what needs doing
4. Break down complex requests intelligently
command - Entry point that routes to @task-orchestratorPlus 20+ other specialized agents for specific development tasks.
bash
npx claude-code-collective init
`$3
bash
Just core agents for lightweight projects
npx claude-code-collective init --minimalFocus on testing framework only
npx claude-code-collective init --testing-onlyJust the behavioral system and hooks
npx claude-code-collective init --hooks-onlyInteractive 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.
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$3
`
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
bash
Check what's installed and working
npx claude-code-collective statusValidate installation integrity
npx claude-code-collective validateFix broken installations
npx claude-code-collective repairRemove everything
npx claude-code-collective cleanGet help
npx claude-code-collective --help
`Current state (honest assessment)
$3
- 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$3
- Some agents are still being refined
- Research phase can be slow sometimes
- Hook system requires restart (Claude Code limitation)
- Documentation is scattered across files$3
- 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 tasksTesting your installation
After installing:
bash
1. Validate everything installed correctly
npx claude-code-collective validate2. Check status
npx claude-code-collective status3. 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
$3
- Check Node.js version: (need >= 16)
- Clear npm cache: npm cache clean --force
- Try force install: $3
- Restart Claude Code (hooks need to load)
- Check exists
- Run npx claude-code-collective validate$3
- 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$3
- Context7 might be having connectivity issues
- Agent might be being thorough (this varies)
- Check for timing dataRequirements
- 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
$3
- 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$3
- Production-ready enterprise software
- Guaranteed to work perfectly
- Following any official standards
- A replacement for thinking or understanding codeWhy 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 diagnosticsMIT License - Use it, break it, fix it, whatever works for you.
---
Experimental | TDD-Focused | Personal Project | Use At Your Own Risk
See CHANGELOG.md for detailed version history and release notes.