Hybrid architecture: Agent Teams + subagents in Claude Code

Overview

The system has two layers:

1. Agent Team — Lead + 3 teammates that debate to build the artifact
2. Subagents — 3 agents the Lead launches for scoped tasks (research, validate, publish)

The separation is not cosmetic — it defines available tools, assigned models and communication structure.

Architecture diagram

┌─────────────────────────────────────────────────────────────────┐
│                          AGENT TEAM                             │
│                                                                 │
│   ┌─────────────────────────────────┐                           │
│   │              LEAD               │                           │
│   │         Model: Sonnet           │                           │
│   └─────────────────────────────────┘                           │
│         │              │              │                          │
│      PHASE 1        PHASE 2        PHASE 3                       │
│    (subagent)      (teammates)    (subagents)                    │
│         │              │              │                          │
│         v              v              v                          │
│                                                                 │
│  ┌──────────────┐      │      ┌──────────────┐  ┌────────────┐  │
│  │ Investigator │      │      │  Validator   │  │ Publisher  │  │
│  └──────────────┘      │      └──────────────┘  └────────────┘  │
│  Subagent              │      Subagents — run inside the Lead    │
│  No own session        │                                        │
│                        v                                        │
│          ┌─────────────────────────────┐                        │
│          │      Shared Task List       │                        │
│          └──────┬──────────┬───────────┘                        │
│                 │          │          │                          │
│                 v          v          v                          │
│          ┌──────────┐ ┌──────────┐ ┌──────────┐                 │
│          │Architect │◇│ Reviewer │◇│Optimizer │                  │
│          └──────────┘ └──────────┘ └──────────┘                 │
│          Teammates — Model: Opus (always)                        │
│          Own session. Communicate via Mailbox                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

The 3 pipeline phases

Phase 1 — Lead only

1. Lead receives user request
2. Lead detects blocking ambiguities → asks before starting
3. Lead launches Investigator (subagent, WITHOUT team_name) → receives research

The Lead doesn’t start work without the research. If the Investigator didn’t find a primary source for a command, it reports it — the Architect doesn’t invent commands without a source.

Phase 2 — Team enters with context

4. Lead creates task list with dependencies
5. Lead spawns Architect + Reviewer + Optimizer (WITH team_name)
   → includes Investigator research in spawn prompt
6. Architect writes SKILL.md using the researched information
7. Reviewer challenges → direct debate with Architect (max 2 rounds)
8. Optimizer compresses → removes what Claude already knows (< 500 lines)

Phase 3 — Validation and publishing

9. Lead launches Validator (subagent, WITHOUT team_name) → PASS or FAIL
10. If PASS: Lead launches Publisher (subagent, WITHOUT team_name) → verifies in portal

The Publisher doesn’t run if the Validator failed.

The Task Tool asymmetry

This is the critical behavior that defines the architecture:

Teammates do NOT have access to the Task Tool. Only the Lead can launch subagents.

If a teammate tries to launch a subagent, it either fails silently or the system converts it into an additional teammate (with team_name), which changes the model from Sonnet to Opus and breaks the design.

Caution

In demos where the Investigator was accidentally launched with team_name, it ran on Opus instead of Sonnet. The cost difference is significant when a skill requires multiple search iterations.

The rule:

• Investigator, Validator, Publisher → launched by Lead WITHOUT team_name = subagents on Sonnet
• Architect, Reviewer, Optimizer → launched by Lead WITH team_name = teammates on Opus

The model routing discovery

Agent Teams assigns Opus to teammates automatically, regardless of what you configure.

Mechanism	Works
model: haiku in CLAUDE.md	No — ignored
”Use Sonnet model” in spawn prompt	No — it’s text, not a system parameter
Global model for all teammates	Yes — but no per-role differentiation
Lead session model	Yes — subagents inherit from Lead

Real data from 37 analyzed calls:

Component	Requested	Actual
Lead	Haiku	Sonnet (inherits from user)
All teammates	Haiku / Sonnet per role	Opus always
Subagents (without team_name)	Haiku	Sonnet (inherits from Lead)
Haiku used	—	Never, in any demo

Exit conditions per role

Each role has an explicit exit condition to prevent loops:

Role	Exit condition
Lead	Skill published and verified in portal
Investigator	Searched max 2 primary sources
Architect	SKILL.md written and Reviewer approved
Reviewer	Max 2 rounds of objections
Optimizer	Body < 500 lines AND removed at least 1 block
Validator	Ran validate.sh and returned result
Publisher	Published to portal and verified with curl

→ See roles in detail: contracts and rules