How vanzan01/claude-code-sub-agent-collective works
Claude Code Sub-Agent Collective is an experimental installer and runtime framework for Claude Code, providing TDD-oriented specialist agents, routing, handoffs, research support, and installation management. The main user-to-result flow is: a developer invokes the install command, the installer configures the project from templates, and the installed /van workflow routes a request through the task orchestrator to specialist agents, with tests-first implementation and delivery. The graph also preserves validation, dynamic agent management, and research metrics. Some template capabilities are documented in the README but their runtime wiring was not sampled, so those links are documented or left unasserted.
Main entry points: ResearchMetricsSystem.js Research metrics system · claude-code-collective.js Collective CLI · installer.js Project installer · AgentSpawnCommand.js Agent spawn command
Components 29
Installation and management
- Collective CLI
bin/claude-code-collective.js - Project installer
lib/installer.js - Install configurator
lib/configurator.js - Template mapping
lib/file-mapping.js - Settings merge
lib/merge-strategies.js - Collective templates
templates - Installation validator
lib/validator.js
Agent runtime
- Command interface
lib/command-system.js - Command parser
lib/command-parser.js - Agent spawn command
lib/AgentSpawnCommand.js - Agent spawner
lib/AgentSpawner.js - Agent templates
lib/AgentTemplateSystem.js - Agent registry
lib/AgentRegistry.js - Agent lifecycle
lib/AgentLifecycleManager.js
Development workflows
- `/van` entry
templates/commands/van.md - Task orchestrator
templates/agents/task-orchestrator.md - Specialist agents
templates/agents
Quality and research
- Research agent
templates/agents/research-agent.md - TDD enforcement hooks
templates/hooks - Contract validation
lib/TestContractValidator.js - VAN maintenance
lib/van-maintenance.js
Metrics and experiments
- Research metrics system
lib/metrics/ResearchMetricsSystem.js - Metrics storage
lib/metrics/MetricsCollector.js - JIT metrics
lib/metrics/JITLoadingMetrics.js - Hub-spoke metrics
lib/metrics/HubSpokeMetrics.js - Handoff metrics
lib/metrics/TDDHandoffMetrics.js - Experiment framework
lib/metrics/ExperimentFramework.js
Other components
- Developer
- Context7 docs
Connections 29
- Developer → Collective CLI: runs
README.md - Collective CLI → Project installer: installs
bin/claude-code-collective.js - Collective CLI → Installation validator: validates
- Project installer → Template mapping: maps files
lib/installer.js - Project installer → Settings merge: merges settings
lib/installer.js - Project installer → Collective templates: installs from
lib/installer.js - Collective CLI → Install configurator: configures install
- Developer → `/van` entry: invokes
README.md - `/van` entry → Task orchestrator: routes to
README.md - Task orchestrator → Specialist agents: delegates to
README.md - Research agent → Context7 docs: looks up docs
README.md - Specialist agents → TDD enforcement hooks: enforced by
README.md - Specialist agents → Contract validation: validates contracts
- Command interface → Command parser: parses commands
lib/command-system.js - Command parser → Agent spawn command: dispatches spawn
lib/command-parser.js - Agent spawn command → Agent spawner: delegates spawning
lib/AgentSpawnCommand.js - Agent spawn command → Agent registry: uses registry
lib/AgentSpawnCommand.js - Agent spawn command → Agent lifecycle: uses lifecycle
lib/AgentSpawnCommand.js - Agent spawner → Agent templates: loads templates
lib/AgentSpawner.js - Agent lifecycle → Agent registry: listens to events
lib/AgentLifecycleManager.js - Command parser → VAN maintenance: runs maintenance
lib/command-parser.js - Research metrics system → Metrics storage: initializes
lib/metrics/ResearchMetricsSystem.js - Research metrics system → JIT metrics: records context
lib/metrics/ResearchMetricsSystem.js - Research metrics system → Hub-spoke metrics: tracks routing
lib/metrics/ResearchMetricsSystem.js - Research metrics system → Handoff metrics: tracks handoffs
lib/metrics/ResearchMetricsSystem.js - Research metrics system → Experiment framework: manages experiments
lib/metrics/ResearchMetricsSystem.js - JIT metrics → Metrics storage: stores metrics
lib/metrics/JITLoadingMetrics.js - Hub-spoke metrics → Metrics storage: stores metrics
lib/metrics/HubSpokeMetrics.js - Handoff metrics → Metrics storage: stores metrics
lib/metrics/TDDHandoffMetrics.js