Claude Code Sub Agent Collective

Claude Code Sub-Agent Collective

<a href="https://trendshift.io/repositories/15208" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15208" alt="vanzan01%2Fclaude-code-sub-agent-collective | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

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:

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

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

• /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.