title: "Agent Teams" last_updated: 2026-03-21 status: experimental difficulty: advanced prerequisites: [05-sub-agents, 07-session-architecture]

Agent Teams

Coming in V2. This module is scaffolded with an outline.

Core Question

How do multiple agents collaborate on complex tasks?

Module Outline

Concepts

  1. From sub-agents to teams — Sub-agents handle isolated tasks. Agent teams coordinate across roles: implementer, reviewer, tester, architect.

  2. Team topologies — Patterns for organizing agent collaboration:

    • Pair: implementer + reviewer
    • Pipeline: architect → implementer → tester → reviewer
    • Swarm: multiple agents working on independent parts simultaneously
    • Hierarchy: lead agent delegates to specialist agents

  3. Role definition — Each agent in a team needs a clear role, capabilities, and boundaries. Unclear roles lead to duplication and conflicts.

  4. Coordination mechanisms — How agents share information: shared files, git branches, structured handoff documents, plan files.

  5. Conflict resolution — When agents disagree (e.g., a reviewer rejects an implementer's code). Patterns for resolving this automatically vs. escalating to the human.

  6. The human's role in agent teams — You become the architect and reviewer of the process, not the executor of each step.

  7. Cost and complexity tradeoffs — Agent teams multiply token usage. When the coordination cost exceeds the benefit, use simpler patterns.

Tool-Specific Content

  • Claude Code: Agent teams via custom agents directory, orchestration scripts, worktree-based isolation
  • Codex CLI: Team patterns using Agents SDK, multi-instance coordination

Exercises

  1. Set up a simple pair: implementer agent + review agent
  2. Build a pipeline: plan → implement → test → review
  3. Run a parallel swarm on a multi-file refactoring task
  4. Measure and compare: team vs. single-agent on the same task