Agent teams

You will learn

• Why a team of focused agents outperforms one generalist agent.
• The 12 specialists TRW ships and what each one is scoped to touch.
• The four coordination formations and when to pick each.
• How file ownership is declared and enforced at the hook layer.
• How waves and shards decide parallel versus sequential execution.
• How to enable agent-team spawning in your client.

What agent teams solves

One agent trying to do everything produces worse output. Split attention across research, implementation, and review degrades each of them. A focused specialist reading a narrow slice of the codebase finds more relevant signal than a generalist reading everything while also writing code. Specialization is the lever — and the lever works the same way for language models as it does for humans.

TRW's team layer makes specialization operational. Each agent has a declared role, a declared file scope, and a declared handoff. The orchestrator composes them into a formation that matches the work. Parallel execution becomes safe because conflicts are prevented at declaration time, not discovered at merge time.

The 12 specialists

Full agent definitions live in the agent roster; this table is the quick-reference of who does what.

Formations

A formation is the topology of a team — not whether to use multiple agents, but how they relate to each other. TRW ships four formations. The orchestrator picks one based on the shape of the work.

Pipeline

Sequential stages with clean handoffs. Each agent completes before the next begins. Use when every stage depends on the previous output and cannot start early — the default for most feature implementations.

Map-reduce

A researcher fans out to parallel shards that read independent axes of the codebase, then results merge into a single implementer. Use when the reading can be parallelized and the outputs have a single downstream consumer — reduces wall-clock time on large codebases.

Planner-executor-reflector

A three-node triangle: the planner defines work, the executor implements it, the reflector reads the diff and feeds observations back to the planner before the next wave. Use when iterative design matters more than raw throughput.

Debate-critic-judge

Two implementers propose competing approaches. An adversarial critic probes both. A judge delivers the verdict. Use when correctness matters more than speed — it is expensive, and the evidence it produces justifies the cost for quality-critical decisions.

File ownership

Every spawned agent declares its file scope at startup as a set of glob patterns. Writes outside the declared scope are rejected at the hook layer before the filesystem is touched. Silent overlap between parallel agents is structurally impossible — not a convention, not a guideline, not something any human has to remember.

A typical split: trw-implementer owns src/module.* and trw-tester owns tests/test_module.*. Both run in the same wave. Neither can write to the other's scope. The same model works for any language — scopes are glob patterns, not language rules.

Waves and shards

Work decomposes into two nested units. A wave is a sequential boundary: wave 2 cannot begin until wave 1 exits. A shard is a parallel unit within a wave: shards in the same wave run concurrently. This is the knob that decides what waits and what races.

The orchestrator writes a wave manifest before spawning agents, and each shard writes its findings back before returning. Wave 1 typically handles foundation work, wave 2 handles integration, and a final serial wave synthesizes the outputs. Parallelism lives inside each wave; ordering lives between them.

Enabling agent teams per client

Multi-agent spawning is gated behind an explicit opt-in in every supported client while the orchestration hardens. Without the opt-in set, team-creation calls silently fail — the framework will not spawn agents without your permission.

// .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}