A Multi-Subagent System for Infrastructure Orchestration
Version 2.0 - January 2026
30-second understanding of the system
A coordinated team of AI subagents that work together to design, implement, test, and deploy infrastructure services. Each subagent specializes in a specific domain, ensuring expert-level execution at every stage.
Plans projects, coordinates subagents, synthesizes results
Designs systems, evaluates technology, creates specifications
Configures networks, authentication, Traefik routing
Implements code, deploys services, debugs issues
Creates tests, validates implementations, quality gates
How subagents work together with AI Review Board peer review
For major milestones only, the PM dispatches plans and designs to three AI CLIs running in Docker containers. Each CLI has full read-only access to all projects and returns structured JSON responses.
Google's CLI with web search + project read access
gemini
OpenAI's CLI with code analysis + project read access
codex
Anthropic's CLI with reasoning + project read access
claude
assessment, concerns, suggestions, and approval fields for consistent parsing.
Deep dive into each subagent's responsibilities and capabilities
~/.claude/agents/pm.md
$HOME/projects/data/claudeagents/pm/
plans/{project}/plan.md - Project plansreviews/{project}/ - Swarm review synthesestasks/{project}/ - Task breakdownsreports/{project}/ - Final reports~/projects/.claude/agents/architect.md
$HOME/projects/data/claudeagents/architect/
decisions/{project}/architecture.md - ADRsdecisions/{project}/design.md - Specificationsnotes/{project}/research-*.md - Evaluations~/projects/.claude/agents/security.md
$HOME/projects/data/claudeagents/security/
decisions/{project}/network.md - Network topologydecisions/{project}/traefik.md - Routing rulesdecisions/{project}/keycloak.md - Auth setup~/projects/.claude/agents/developer.md
$HOME/projects/data/claudeagents/developer/
specs/{project}/spec.md - Specs for QAnotes/{project}/deployment.md - Deployment logsnotes/{project}/debug-*.md - Debug notes~/projects/.claude/agents/qa.md
Tests execute in GitLab CI runners (not locally)
$HOME/projects/data/claudeagents/qa/
workspace/{project}/ - Git clonestests/{project}/ - Test files before commitresults/{project}/results.md - Pipeline resultsreports/{project}/quality-report.md - Quality assessmentAll subagents communicate through a shared file system. This enables asynchronous collaboration, persistent context, and a clear audit trail.
$HOME/projects/data/claudeagents/
├── pm/
│ ├── plans/ # Project plans
│ ├── reviews/ # AI Review Board review syntheses
│ ├── tasks/ # Task breakdowns
│ └── reports/ # Final reports
├── architect/
│ ├── decisions/ # Architecture Decision Records
│ └── notes/ # Research and evaluations
├── security/
│ └── decisions/ # Network, Traefik, Keycloak configs
├── developer/
│ ├── specs/ # Specifications for QA
│ └── notes/ # Deployment logs, debug notes
└── qa/
├── tests/ # Actual test files
├── results/ # Test execution results
└── reports/ # Quality reports
Skills, Hooks, and MCP Tools that power the agents
Reusable expertise modules that subagents invoke for specialized procedures
Lifecycle event handlers that run automatically at key moments
Runs when Claude Code starts. Detects project context and available subagents/skills.
Logs all user prompts for analytics and debugging purposes.
Security gate that blocks dangerous operations (force push, secrets deletion).
Audit logging of all tool calls with timestamps and subagent context.
Creates session summary and cleans up when subagent stops.
Model Context Protocol server providing external capabilities through code-executor
Subagents access one MCP server: code-executor. This server provides two pathways: execute_code for 71 tools across 9 servers, and dispatch_to_reviewboard for AI peer review.
The only MCP server subagents call directly. Executes TypeScript with access to all underlying tools.
These are not directly accessible to subagents. The code-executor imports their tool wrappers at runtime:
// Subagent calls code-executor to access underlying tools
mcp__code-executor__execute_code({
code: `
import { execute_query } from '/workspace/servers/postgres/execute_query.js';
const result = await execute_query({ sql: 'SELECT * FROM users' });
return result;
`
})The MCP code-executor implements lazy loading of tool definitions, achieving 96% token savings (275 tokens vs 7,683 tokens at boot).
Complete reference for all components
| Skill | Subagent | Description | Trigger |
|---|---|---|---|
architecture-diagram-creator |
Architect | Creates comprehensive HTML architecture diagrams | "create architecture diagram" |
service-deployment |
Developer | Complete Docker deployment with OAuth2, Traefik | "deploy service", "install" |
postgres-integration |
Developer | Database creation, user management, connections | "create database", "postgres" |
keycloak-setup |
Developer | OAuth2/OIDC client configuration | "keycloak client", "SSO" |
traefik-setup |
Developer | Routing, SSL/TLS, middleware configuration | "traefik routing", "SSL" |
logging-observability |
Developer | Loki, Promtail, Grafana, monitoring | "logging", "monitoring" |
troubleshooting |
Developer | Systematic debugging methodology | "debug", "troubleshoot" |
naming-validator |
Developer | Resource naming standards validation | "install", "create", "deploy" |
nginx-static-site |
Developer | Static website deployment | "deploy site", "static site" |
secrets-security |
Security | Secrets management, security hardening | "secrets", "security audit" |
network-config |
Security | Docker networks, port mappings, DNS | "network", "ports", "DNS" |
ai-communication |
General | AI-to-AI communication, swarm dispatch | "peer review", "aichat" |
gitlab-integration |
General | GitLab repository and CI/CD operations | "gitlab", "repository" |
skill-creator |
PM | Guide for creating new skills | "create skill" |
| Hook | Location | Trigger | Purpose |
|---|---|---|---|
session-start.sh |
~/.claude/hooks/ |
Claude Code starts | Load project context, detect available subagents |
user-prompt-submit.sh |
~/.claude/hooks/ |
User sends prompt | Log user prompts for analytics |
pre-tool-use.sh |
~/.claude/hooks/ |
Before any tool call | Block dangerous operations (force push, rm secrets) |
post-tool-use.sh |
~/.claude/hooks/ |
After any tool call | Audit logging to ~/.claude/audit/ |
stop.sh |
~/.claude/hooks/ |
Subagent stops | Create session summary, cleanup |
The template Developer uses to communicate with QA:
# Developer Specification: {Feature/Service}
## Overview
{What was implemented}
## API Endpoints
### POST /api/v1/resource
**Description**: Create a new resource
**Request Body**:
```json
{
"name": "string (required)",
"description": "string (optional)"
}
```
**Response** (201):
```json
{
"id": "int",
"name": "string",
"created_at": "ISO datetime"
}
```
**Errors**:
- 400: Invalid input
- 500: Database error
## Example Inputs/Outputs
### Happy Path
Input: {"name": "Test"}
Output: {"id": 1, "name": "Test", "status": "active"}
### Edge Cases
- Empty name: Should raise ValueError
- Max length (255 chars): Should acceptHow PM synthesizes feedback from multiple AI reviewers:
# Peer Review Synthesis: {Topic}
## Consensus (All Reviewers Agreed)
- {Point that all three models agreed on}
- {Another consensus point}
## Critical Issues (Must Address)
| Issue | Severity | Recommendation |
|-------|----------|----------------|
| {Issue description} | Critical | {How to fix} |
## Suggestions (Consider)
- Gemini: {Suggestion from Gemini}
- Codex: {Suggestion from Codex}
- Claude: {Suggestion from Claude}
## Conflicts (Need User Decision)
- {Topic where reviewers disagreed}
- Gemini says: X
- Codex says: Y
## Action Items
1. {Specific action to take}
2. {Another action}Tool calls are logged to ~/.claude/audit/YYYY-MM-DD.log
2026-01-17 16:45:32 | Subagent: developer | Tool: Bash | Session: abc123
Command: docker ps | grep analytics
2026-01-17 16:45:35 | Subagent: developer | Tool: Write | Session: abc123
2026-01-17 16:45:40 | Subagent: qa | Tool: Bash | Session: abc123
Command: pytest tests/ -v