Agent Teams — Orchestrating Multi-Session Work

Every agent dispatch covered in the previous lessons uses the same fundamental pattern: orchestrator spawns agents, agents work independently, agents report back to the orchestrator. The orchestrator is the hub. Agents are spokes.

This works well until agents need to coordinate with each other in real time. A backend developer finishes the API contracts and needs to hand them off to the frontend developer. A security auditor finds a vulnerability that blocks the feature work. These are cross-agent dependencies — and in the standard subagent model, they route through the orchestrator as a bottleneck.

Agent Teams solve this by enabling direct peer-to-peer messaging between team members.

Subagents vs. Agent Teams

The distinction is structural, not cosmetic.

Subagents are isolated sessions. When you spawn a subagent via the Agent tool, that agent runs in its own context window, executes its task, and returns a result to the parent. The parent is the only channel. Two subagents cannot communicate directly — they have no awareness of each other's existence.

Agent Team members are also separate sessions, but they have a shared communication layer. A team member can use SendMessage to address any other member by name. Messages are queued and delivered. The backend agent can message the frontend agent directly: "API endpoints ready at /api/auth — here is the schema." The QA agent can message the backend agent: "Tests failing on the session endpoint — repro in the attached trace."

The orchestrator's role changes from bottleneck to coordinator. Instead of routing every message, it monitors, resolves deadlocks, and runs the integration check at the end.

Enabling Agent Teams

Add the environment variable to your ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

With this enabled, the TeamCreate tool becomes available in your Claude Code session, and the Agent tool gains team-aware parameters.

Team Structure

Every team has one leader and any number of members. The leader is the orchestrating session — typically your primary Claude Code window or a top-level orchestrator agent. Members are spawned into the team using the Agent tool with a team assignment.

The team leader handles:

• Initial task assignment to each member
• Monitoring inbound messages from members
• Resolving blockers (forwarding dependencies, mediating conflicts)
• Running the final integration check once all members report done

Members handle:

• Their assigned work within their file territory
• Sending status updates to the leader
• Sending direct coordination messages to peers when handoffs occur

Communication Patterns

Three message flows emerge naturally in any team:

Leader to Member — task assignment at spawn time, plus clarifications when a member sends a blocker.

Leader → Backend Dev:
Implement the auth endpoints described in PRD section 3.
When the API contracts are finalized, send the schema to Frontend Dev via SendMessage.
Report done to Leader when tests pass.

Member to Leader — status, blockers, completion.

Backend Dev → Leader:
Auth endpoints implemented and passing unit tests.
Blocked on DB migration — needs review before integration tests can run.

Member to Member — handoffs and coordination. This is the capability that subagents cannot replicate.

Backend Dev → Frontend Dev:
Auth API ready. Endpoints:
  POST /api/auth/login → returns { token, user }
  DELETE /api/auth/logout → returns { success }
  GET /api/auth/me → returns { user }
Schema attached. You can begin integration work.

QA Engineer → Backend Dev:
Test suite failing on POST /api/auth/login.
Returns 500 on malformed payload — needs input validation.
Test case: { email: null, password: "" }

eliminates the round-trip through the orchestrator for routine coordination. The leader stays focused on strategic monitoring, not message relay.

File Territory Ownership — Non-Negotiable

Two agents editing the same file will produce merge conflicts. This is not a probability — it is a certainty if agents are working in parallel on overlapping files.

Define exclusive zones before spawning any team member. Every file belongs to exactly one agent. If a second agent needs changes in that file, they send a message to the owning agent describing the requirement, and the owner makes the change.

A production Feature Team territory map looks like this:

Backend Developer owns:

• app/api/ — all API route handlers
• lib/db/ — database access layer
• prisma/ — schema and migrations
• lib/types/ — shared TypeScript interfaces

Frontend Developer owns:

• app/(routes)/ — page components
• components/ — UI component library
• hooks/ — custom React hooks
• styles/ — CSS and Tailwind config

QA Engineer owns:

• __tests__/ — unit and integration tests
• e2e/ — Playwright end-to-end specs
• *.test.ts files — any test files adjacent to source

The rule for territory conflicts: if a feature requires a shared utility that both agents need, the Backend Developer creates it in lib/shared/ (their territory) and the Frontend Developer imports it. The QA Engineer does not touch source files — if a bug fix is needed to make a test pass, QA sends a message to the relevant owner.

Definition of Done — Write It Before Spawning

The QA Engineer's primary job is grading against acceptance criteria. Those criteria must exist before the QA agent is spawned, or the agent will invent its own interpretation of "done."

Write explicit acceptance criteria in your orchestrator prompt:

## Definition of Done

The feature is complete when ALL of the following are true:

- [ ] POST /api/auth/login returns token on valid credentials
- [ ] POST /api/auth/login returns 401 on invalid credentials
- [ ] POST /api/auth/login returns 422 on malformed input
- [ ] Login form validates email format client-side before submit
- [ ] Login form shows error state on 401 response
- [ ] Unit test coverage >= 90% on auth module
- [ ] E2E test covers happy path login and logout
- [ ] No TypeScript errors (tsc --noEmit passes)
- [ ] No lint errors (eslint passes)

QA Engineer: grade the implementation against this checklist.
Report each item as PASS or FAIL with evidence.
Do not report done until all items PASS.

The QA Engineer becomes a grader, not a guesser. The definition of done is a contract, and the team executes against it.

The Orchestrator's Monitoring Role

Once agents are spawned, the leader's job shifts to monitoring and unblocking.

Check inbound messages regularly. When a member reports a blocker, either resolve it directly (provide the missing information) or route it to the appropriate peer. If Backend Dev needs a decision about the data model that affects Frontend Dev's work, that is a cross-territory dependency — resolve it before both agents diverge.

The integration check is the final gate. After all members report done:

1. Verify the Definition of Done checklist independently
2. Run the test suite from a clean state
3. Check for any files that were edited outside their owner's territory
4. Confirm no merge conflicts in the working tree

Only then does the team work count as complete.

Current Limitations

Agent Teams are experimental and carry real constraints:

No shared context. Each team member has its own context window. The backend agent does not know what the frontend agent has read. Common patterns and conventions must be stated explicitly in each agent's prompt — you cannot say "you know the style guide" and assume all agents do.

Message delivery is not instantaneous. SendMessage queues messages. In practice, an agent sends a message and continues working. The recipient reads it on their next check. Do not design workflows that require synchronous blocking on a peer message.

Not all coordination patterns work smoothly. Complex multi-party negotiations (three agents needing to agree on an interface before any can proceed) are difficult to coordinate. Design the work to minimize these situations — define interfaces in the spawn prompt rather than letting agents negotiate them.

Lesson 186 Drill

Take a feature you have recently built solo and decompose it into a team assignment:

1. List the distinct work domains (backend, frontend, test)
2. Define the file territory boundaries — no overlaps allowed
3. Write the Definition of Done as a graded checklist
4. Identify the one or two peer handoffs that would have needed direct messaging (e.g., "API ready — here is the schema")
5. Write the orchestrator prompt that would have launched this team

You do not need to run the team. The exercise is the decomposition — it reveals where the coordination overhead lives and whether Agent Teams would reduce it.