https://github.com/vanzan01/claude-code-sub-agent-collective
🧠Context Engineering Research - Not just another agent collection, but using research and context engineering to function as a collective. Hub-and-spoke coordination through Claude Code.
https://github.com/vanzan01/claude-code-sub-agent-collective
agents ai-development autonomous-programming claude claude-code context-engineering multi-agent playwright sub-agents task-master taskmaster yolo
Last synced: 5 months ago
JSON representation
🧠Context Engineering Research - Not just another agent collection, but using research and context engineering to function as a collective. Hub-and-spoke coordination through Claude Code.
- Host: GitHub
- URL: https://github.com/vanzan01/claude-code-sub-agent-collective
- Owner: vanzan01
- License: mit
- Created: 2025-06-06T13:34:09.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-08-17T04:06:54.000Z (5 months ago)
- Last Synced: 2025-08-18T02:02:03.900Z (5 months ago)
- Topics: agents, ai-development, autonomous-programming, claude, claude-code, context-engineering, multi-agent, playwright, sub-agents, task-master, taskmaster, yolo
- Language: JavaScript
- Homepage:
- Size: 3.07 MB
- Stars: 119
- Watchers: 6
- Forks: 14
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Claude Code Sub-Agent Collective
[](https://badge.fury.io/js/claude-code-collective)
[](https://opensource.org/licenses/MIT)
**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
```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.
## 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)
```bash
npx claude-code-collective init
```
### Other options if you want to be selective
```bash
# 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
```bash
# 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:
```bash
# 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](CHANGELOG.md) for detailed version history and release notes.