claude-code-sub-agent-collective: a TDD-enforced agent collective for Claude Code

The problem: agents that ship code without tests or real documentation

The README opens with a list of frustrations the author had while building MVPs: AI giving code without tests, manually looking up library documentation, inconsistent development approaches across projects, and breaking down complex features by hand. The stated fix is a set of agents that write tests first, pull documentation through Context7 instead of guessing, route work to specialists, and decompose complex requests. That framing matters because it tells you the target user is a solo developer or small team doing greenfield MVP work inside Claude Code, not a team maintaining a large legacy codebase. The package description calls itself a "Sub-agent collective framework for Claude Code with TDD validation, TaskMaster Task ID integration, hub-spoke coordination, and deterministic handoffs", which is a narrower promise than "an agent collection". If your workflow already has a test runner and a documentation habit, the value here is enforcement rather than capability: the agents do not know more than a well-prompted Claude, they just refuse to skip the RED phase.

Hub-and-spoke routing: what /van and @task-orchestrator actually do

The mechanism is a single entry point. The README states that the /van command routes to @task-orchestrator, described as "Central routing hub that picks the right specialist". From there the documented flow is: research phase using Context7, tests written first, minimal implementation to make tests pass, refactoring while keeping tests green, then delivery. The delivery contract is quoted in the README as a fixed block listing the RED, GREEN and REFACTOR phases plus a test result count, which is how you tell whether an agent actually followed the process or just claimed to. The repository layout backs this up: .claude/agents/ holds the agent definitions as Markdown files, .claude/agents/lib/research-analyzer.js is described as a complexity analysis engine, and .claude/hooks/ contains test-driven-handoff.sh and collective-metrics.sh. So the coordination is not a runtime service. It is Markdown instructions plus shell hooks plus one JavaScript analyzer, installed into your project and executed by Claude Code. That is a lightweight design, and it also means the routing quality depends on prompt text you can read and edit yourself.

Installing claude-code-collective and running a first task

The README gives a quick install through npx. Node.js >= 16.0.0 is required, and package.json confirms the engines field.

npx claude-code-collective init

The default install writes CLAUDE.md, .claude/settings.json, .claude/agents/ with 30+ agent files, .claude/hooks/ with the TDD enforcement scripts, and a .claude-collective/ directory holding test framework templates, metrics and a package.json for a Vitest setup. If you want less, the README lists narrower modes: --minimal for core agents only, --testing-only, --hooks-only, and --interactive for a guided setup. After installing, the documented verification steps are:

npx claude-code-collective validate
npx claude-code-collective status

validate checks installation integrity and status reports what is installed and working. Both are also exposed as npm scripts in package.json (validate runs lib/validator.js). The README then states that you must restart Claude Code because the hook system requires it, a limitation it attributes to Claude Code rather than the package. Once restarted, the suggested first test is to ask Claude Code to "Build a simple todo app with React" and expect routing to research, task breakdown, tests, then implementation. The management commands are clean (remove everything) and repair (fix broken installations).

Where the collective gets in the way

The README has a section titled "Current state (honest assessment)" and it is worth reading before you install. It lists what is experimental or rough: some agents are still being refined, the research phase can be slow, the hook system requires a restart, and documentation is scattered across files. The known limitations are equally direct: Node.js >= 16, a required Claude Code restart, an opinionated stance on TDD ("if you don't like tests, skip this"), and the admission that some agents might be too thorough or slow for simple tasks. That last point is the real trade-off. A one-line change to a config file can still be routed through research, task decomposition and a test cycle, and the README's own troubleshooting entry for slow research suggests checking .claude-collective/metrics/ for timing data rather than assuming a bug. There is also a practical failure mode: the README says tests may not run if your project has no test runner such as Jest or Vitest, so installing this into a repository without one produces agents that write tests into a void. Finally, the README documents clean and repair but does not document rollback of a partial install, so if init fails halfway you are relying on repair.

How it differs from plain Claude Code subagents and TaskMaster

Claude Code supports sub-agents directly, and the common alternative is to write a handful of Markdown agent files yourself and invoke them by name. That approach gives you full control and no dependency, but it gives you no enforcement: nothing stops an agent from writing implementation before tests, and nothing routes a request to the right specialist. This collective adds three things on top of the raw feature: a fixed entry point (/van), shell hooks that enforce the TDD handoff, and a complexity analyzer in .claude/agents/lib/research-analyzer.js that decides how a request gets decomposed. The other comparison the package itself invites is TaskMaster, since its description mentions "TaskMaster Task ID integration" and the repository topics include both task-master and taskmaster. TaskMaster-style tooling focuses on task breakdown and tracking; this project's differentiator is the test-first contract and the Context7 documentation lookup, with task IDs used as the identifier that ties handoffs together. If you already have a task tracker you like, the routing and hooks are the parts worth evaluating, not the task model. If you want zero installed files in your repository, neither this nor a hand-rolled agent set will satisfy you, because both live in .claude/.

Maintenance, licensing and the cost of upgrading

The package is MIT licensed, which the README badge and package.json both confirm, so you can fork, modify the agent Markdown and ship the result inside a commercial product. That matters more than usual here because the agents are prompt files: the realistic upgrade path is editing them, and a permissive licence makes that legitimate rather than tolerated. On maintenance, the last push to the repository was on 2026-04-20, which is roughly five months before today, so the project is not archived but it is also not receiving frequent commits; treat the version you install as the version you will be running. The package version in package.json is 2.0.8, and the README labels the installer experimental, so pinning is sensible if you script the install. Upgrade cost is mostly re-installation: because init writes into CLAUDE.md, .claude/settings.json and .claude/agents/, any local edits you make to those files are the thing at risk on a re-run. The README does not describe a merge strategy for existing files, so back up CLAUDE.md and .claude/settings.json before running init again. Nothing in the README addresses how the hooks behave under Windows or in a repository without a shell, so verify that on your own platform before rolling it out.

Editorial conclusion

Adopt it if you already write tests first and want that discipline pushed into Claude Code through hooks and specialist agents; the installer is a single npx command and the MIT licence keeps the exit cheap. Skip it if you do not want TDD enforced, if you are on Node.js below 16, or if you need documented rollback, because the README covers clean and repair but not reverting a partial install. Before trusting it, run npx claude-code-collective validate and npx claude-code-collective status, then restart Claude Code so the hooks in .claude/settings.json load, and confirm that a trivial request actually produces test files before you point it at a real repository.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. vanzan01/claude-code-sub-agent-collective on GitHub