# vanzan01/claude-code-sub-agent-collective architecture

> Architecture diagram of the GitHub repository vanzan01/claude-code-sub-agent-collective, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vanzan01/claude-code-sub-agent-collective
- Repository: https://github.com/vanzan01/claude-code-sub-agent-collective

## Overview

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: [`lib/metrics/ResearchMetricsSystem.js`](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/ResearchMetricsSystem.js) (Research metrics system), [`bin/claude-code-collective.js`](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/bin/claude-code-collective.js) (Collective CLI), [`lib/installer.js`](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/installer.js) (Project installer), [`lib/AgentSpawnCommand.js`](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentSpawnCommand.js) (Agent spawn command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_installation["Installation and management"]
  node_cli["Collective CLI"]
  node_installer["Project installer<br/>[installer.js]"]
  node_configurator["Install configurator<br/>[configurator.js]"]
  node_file_mapping["Template mapping<br/>[file-mapping.js]"]
  node_merge["Settings merge"]
  node_templates["Collective templates"]
  node_validator["Installation validator<br/>[validator.js]"]
end

subgraph group_agent_runtime["Agent runtime"]
  node_command_system["Command interface<br/>[command-system.js]"]
  node_command_parser["Command parser<br/>[command-parser.js]"]
  node_spawn_command["Agent spawn command"]
  node_spawner["Agent spawner<br/>[AgentSpawner.js]"]
  node_agent_templates["Agent templates"]
  node_registry[("Agent registry<br/>[AgentRegistry.js]")]
  node_lifecycle["Agent lifecycle"]
end

subgraph group_workflows["Development workflows"]
  node_van_command["&#96;/van&#96; entry<br/>[van.md]"]
  node_orchestrator["Task orchestrator"]
  node_specialists["Specialist agents"]
end

subgraph group_quality_research["Quality and research"]
  node_research_agent["Research agent<br/>[research-agent.md]"]
  node_tdd_hooks["TDD enforcement hooks"]
  node_contract_validator["Contract validation"]
  node_maintenance["VAN maintenance<br/>[van-maintenance.js]"]
end

subgraph group_telemetry["Metrics and experiments"]
  node_metrics_system["Research metrics system"]
  node_metrics_collector[("Metrics storage")]
  node_jit_metrics["JIT metrics"]
  node_hub_metrics["Hub-spoke metrics<br/>[HubSpokeMetrics.js]"]
  node_handoff_metrics["Handoff metrics"]
  node_experiments["Experiment framework"]
end

node_developer(("Developer"))
node_context7["Context7 docs"]

node_developer -->|"runs"| node_cli
node_cli -->|"installs"| node_installer
node_cli -->|"validates"| node_validator
node_installer -->|"maps files"| node_file_mapping
node_installer -->|"merges settings"| node_merge
node_installer -->|"installs from"| node_templates
node_cli -->|"configures install"| node_configurator
node_developer -->|"invokes"| node_van_command
node_van_command -->|"routes to"| node_orchestrator
node_orchestrator -->|"delegates to"| node_specialists
node_research_agent -.->|"looks up docs"| node_context7
node_specialists -.->|"enforced by"| node_tdd_hooks
node_specialists -.->|"validates contracts"| node_contract_validator
node_command_system -->|"parses commands"| node_command_parser
node_command_parser -->|"dispatches spawn"| node_spawn_command
node_spawn_command -->|"delegates spawning"| node_spawner
node_spawn_command -->|"uses registry"| node_registry
node_spawn_command -->|"uses lifecycle"| node_lifecycle
node_spawner -->|"loads templates"| node_agent_templates
node_lifecycle -->|"listens to events"| node_registry
node_command_parser -->|"runs maintenance"| node_maintenance
node_metrics_system -->|"initializes"| node_metrics_collector
node_metrics_system -->|"records context"| node_jit_metrics
node_metrics_system -->|"tracks routing"| node_hub_metrics
node_metrics_system -->|"tracks handoffs"| node_handoff_metrics
node_metrics_system -->|"manages experiments"| node_experiments
node_jit_metrics -->|"stores metrics"| node_metrics_collector
node_hub_metrics -->|"stores metrics"| node_metrics_collector
node_handoff_metrics -->|"stores metrics"| node_metrics_collector

click node_cli "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/bin/claude-code-collective.js"
click node_installer "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/installer.js"
click node_configurator "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/configurator.js"
click node_file_mapping "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/file-mapping.js"
click node_merge "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/merge-strategies.js"
click node_templates "https://github.com/vanzan01/claude-code-sub-agent-collective/tree/main/templates"
click node_validator "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/validator.js"
click node_command_system "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/command-system.js"
click node_command_parser "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/command-parser.js"
click node_spawn_command "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentSpawnCommand.js"
click node_spawner "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentSpawner.js"
click node_agent_templates "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentTemplateSystem.js"
click node_registry "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentRegistry.js"
click node_lifecycle "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentLifecycleManager.js"
click node_van_command "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/templates/commands/van.md"
click node_orchestrator "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/templates/agents/task-orchestrator.md"
click node_specialists "https://github.com/vanzan01/claude-code-sub-agent-collective/tree/main/templates/agents"
click node_research_agent "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/templates/agents/research-agent.md"
click node_tdd_hooks "https://github.com/vanzan01/claude-code-sub-agent-collective/tree/main/templates/hooks"
click node_contract_validator "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/TestContractValidator.js"
click node_maintenance "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/van-maintenance.js"
click node_metrics_system "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/ResearchMetricsSystem.js"
click node_metrics_collector "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/MetricsCollector.js"
click node_jit_metrics "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/JITLoadingMetrics.js"
click node_hub_metrics "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/HubSpokeMetrics.js"
click node_handoff_metrics "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/TDDHandoffMetrics.js"
click node_experiments "https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/ExperimentFramework.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_installer,node_configurator,node_file_mapping,node_merge,node_templates,node_validator toneBlue
class node_command_system,node_command_parser,node_spawn_command,node_spawner,node_agent_templates,node_registry,node_lifecycle toneAmber
class node_van_command,node_orchestrator,node_specialists toneMint
class node_research_agent,node_tdd_hooks,node_contract_validator,node_maintenance toneRose
class node_metrics_system,node_metrics_collector,node_jit_metrics,node_hub_metrics,node_handoff_metrics,node_experiments,node_developer,node_context7 toneIndigo
```

## Components

### Installation and management

- [Collective CLI](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/bin/claude-code-collective.js): `bin/claude-code-collective.js`
- [Project installer](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/installer.js): `lib/installer.js`
- [Install configurator](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/configurator.js): `lib/configurator.js`
- [Template mapping](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/file-mapping.js): `lib/file-mapping.js`
- [Settings merge](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/merge-strategies.js): `lib/merge-strategies.js`
- [Collective templates](https://github.com/vanzan01/claude-code-sub-agent-collective/tree/main/templates): `templates`
- [Installation validator](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/validator.js): `lib/validator.js`

### Agent runtime

- [Command interface](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/command-system.js): `lib/command-system.js`
- [Command parser](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/command-parser.js): `lib/command-parser.js`
- [Agent spawn command](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentSpawnCommand.js): `lib/AgentSpawnCommand.js`
- [Agent spawner](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentSpawner.js): `lib/AgentSpawner.js`
- [Agent templates](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentTemplateSystem.js): `lib/AgentTemplateSystem.js`
- [Agent registry](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentRegistry.js): `lib/AgentRegistry.js`
- [Agent lifecycle](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/AgentLifecycleManager.js): `lib/AgentLifecycleManager.js`

### Development workflows

- [`/van` entry](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/templates/commands/van.md): `templates/commands/van.md`
- [Task orchestrator](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/templates/agents/task-orchestrator.md): `templates/agents/task-orchestrator.md`
- [Specialist agents](https://github.com/vanzan01/claude-code-sub-agent-collective/tree/main/templates/agents): `templates/agents`

### Quality and research

- [Research agent](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/templates/agents/research-agent.md): `templates/agents/research-agent.md`
- [TDD enforcement hooks](https://github.com/vanzan01/claude-code-sub-agent-collective/tree/main/templates/hooks): `templates/hooks`
- [Contract validation](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/TestContractValidator.js): `lib/TestContractValidator.js`
- [VAN maintenance](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/van-maintenance.js): `lib/van-maintenance.js`

### Metrics and experiments

- [Research metrics system](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/ResearchMetricsSystem.js): `lib/metrics/ResearchMetricsSystem.js`
- [Metrics storage](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/MetricsCollector.js): `lib/metrics/MetricsCollector.js`
- [JIT metrics](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/JITLoadingMetrics.js): `lib/metrics/JITLoadingMetrics.js`
- [Hub-spoke metrics](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/HubSpokeMetrics.js): `lib/metrics/HubSpokeMetrics.js`
- [Handoff metrics](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/TDDHandoffMetrics.js): `lib/metrics/TDDHandoffMetrics.js`
- [Experiment framework](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/lib/metrics/ExperimentFramework.js): `lib/metrics/ExperimentFramework.js`

### Other components

- **Developer**
- **Context7 docs**

## Connections

- Developer → Collective CLI: runs (evidence: `README.md`)
- Collective CLI → Project installer: installs (evidence: `bin/claude-code-collective.js`)
- Collective CLI → Installation validator: validates
- Project installer → Template mapping: maps files (evidence: `lib/installer.js`)
- Project installer → Settings merge: merges settings (evidence: `lib/installer.js`)
- Project installer → Collective templates: installs from (evidence: `lib/installer.js`)
- Collective CLI → Install configurator: configures install
- Developer → `/van` entry: invokes (evidence: `README.md`)
- `/van` entry → Task orchestrator: routes to (evidence: `README.md`)
- Task orchestrator → Specialist agents: delegates to (evidence: `README.md`)
- Research agent → Context7 docs: looks up docs (evidence: `README.md`)
- Specialist agents → TDD enforcement hooks: enforced by (evidence: `README.md`)
- Specialist agents → Contract validation: validates contracts
- Command interface → Command parser: parses commands (evidence: `lib/command-system.js`)
- Command parser → Agent spawn command: dispatches spawn (evidence: `lib/command-parser.js`)
- Agent spawn command → Agent spawner: delegates spawning (evidence: `lib/AgentSpawnCommand.js`)
- Agent spawn command → Agent registry: uses registry (evidence: `lib/AgentSpawnCommand.js`)
- Agent spawn command → Agent lifecycle: uses lifecycle (evidence: `lib/AgentSpawnCommand.js`)
- Agent spawner → Agent templates: loads templates (evidence: `lib/AgentSpawner.js`)
- Agent lifecycle → Agent registry: listens to events (evidence: `lib/AgentLifecycleManager.js`)
- Command parser → VAN maintenance: runs maintenance (evidence: `lib/command-parser.js`)
- Research metrics system → Metrics storage: initializes (evidence: `lib/metrics/ResearchMetricsSystem.js`)
- Research metrics system → JIT metrics: records context (evidence: `lib/metrics/ResearchMetricsSystem.js`)
- Research metrics system → Hub-spoke metrics: tracks routing (evidence: `lib/metrics/ResearchMetricsSystem.js`)
- Research metrics system → Handoff metrics: tracks handoffs (evidence: `lib/metrics/ResearchMetricsSystem.js`)
- Research metrics system → Experiment framework: manages experiments (evidence: `lib/metrics/ResearchMetricsSystem.js`)
- JIT metrics → Metrics storage: stores metrics (evidence: `lib/metrics/JITLoadingMetrics.js`)
- Hub-spoke metrics → Metrics storage: stores metrics (evidence: `lib/metrics/HubSpokeMetrics.js`)
- Handoff metrics → Metrics storage: stores metrics (evidence: `lib/metrics/TDDHandoffMetrics.js`)
