Agent teams: lead + teammates

The previous guides cover working with Claude in a single session. This one covers the next tier: agent teams, where a lead session coordinates multiple teammate agents running in parallel, each implementing work in a different repository simultaneously.

This is not a feature for every task. It is the right tool for a specific shape of work, and understanding when it applies is as important as knowing how it works.

The Problem It Solves

Some stories touch multiple repositories. A feature might require changes to an API, a consumer service, a database migration script, and a portal. These are independent tasks, they do not need to happen sequentially, they do not share implementation state, and the work in each repo is well-defined enough to hand off.

Without agent teams, you implement each repo yourself in sequence. With agent teams, you hand off all four simultaneously and they run in parallel while you do something else. The wall clock time for four-repo work collapses to roughly the time of the longest single task.

The compound benefit is the same as guide 02 (agents): teammates run in their own contexts, and their file reads, compile cycles, and test runs never touch your main session.

How It Works

An agent team consists of:

• A lead, your main Claude Code session. The lead is a coordinator, not an implementer. It understands the work, spawns teammates, routes tasks, reviews results, and handles exceptions. The lead never reads repo files, runs build commands, or writes code directly.
• Teammates, sub-agents spawned by the lead, each assigned to a specific repository and task. Each teammate runs in its own isolated context, implements the task, runs verification, and reports back.

Communication flows through SendMessage. The lead sends structured task assignments to teammates. Teammates report completion (or problems) back to the lead via SendMessage. The lead presents results to you and waits for your direction before taking any irreversible action (push, PR creation).

The hard rule: no teammate pushes code or creates a PR without explicit user approval. The lead surfaces the completion summary and stops. You say “push it” and then it happens. This is non-negotiable regardless of how confident the teammate is in its result.

The Task Assignment Format

When the lead sends work to a teammate, it uses a structured format. Freeform messages get ignored or misinterpreted. Every assignment looks like this:

## Task: {short description}

Steps:
1. {first action}
2. {second action}
...
N. Report results back to the lead:
   - What was done
   - Test results
   - Any issues encountered

These steps are not optional. Do not proceed past a step that fails. If stuck, message the lead.

The final step is always a reporting step. Without it, teammates finish and go silent. With it, you get a completion signal you can act on.

What Teammates Receive

Each teammate receives a task spec in their spawn prompt. The spec should be narrow and focused on exactly what that teammate needs to accomplish. This is not just a structural preference; it is the same context principle from guide 02 applied to task assignment. Everything you put in a teammate’s spec is something it will carry and consider for the entire task. Information that does not directly relate to the work at hand does not help; it competes for attention with the information that does, and it increases the chance that the teammate anchors on something irrelevant.

Give a teammate what it needs to do its specific job: the target files, the pattern to follow, the acceptance criteria, the verification approach. Leave out everything else. A spec that is comprehensive about the right things and silent about the wrong ones produces better results than one that tries to be thorough by including every piece of surrounding context.

A Concrete Example: /sith:implement-team

The implement-team skill in our planning repo is the entry point for agent team implementation. You invoke it with a work item number:

/sith:implement-team 181646

The skill:

1. Reads the story and its tasks from the planning repo
2. Presents a summary for your approval before spawning anyone
3. Spawns one teammate per task (one per repository requiring changes)
4. Sends each teammate their task spec via SendMessage
5. Tracks which teammates have reported back
6. Surfaces completion summaries to you when all teammates are done
7. Waits for your explicit direction before pushing anything

Each teammate runs the implementation workflow independently: creates a branch, implements, runs tests, runs a code review agent, and reports. If a teammate hits a blocker, it messages the lead. The lead surfaces the blocker to you. You decide what to do.

The structure means a four-repo story becomes: approve the plan, wait for four parallel reports, review the summaries, say “push them all.” The sequential implementation time is replaced by the time of the longest single task, plus your review time.

When to Use Agent Teams

Agent teams add coordination overhead. For simple single-repo work, that overhead is not worth it. Use agent teams when:

• The work spans multiple repositories and the tasks are genuinely independent
• The task specs are comprehensive enough to hand off without extensive back-and-forth. Teammates cannot ask you questions mid-task the way you can iterate in a main session. The spec needs to be right before they start.
• You have other work to do while they run. If you are going to sit and watch, a single session is simpler.
• The stories come from the planning repo and have self-contained task specs. Tasks written with exact file paths, code references, and acceptance criteria are what make autonomous implementation reliable.

Do not use agent teams for exploratory work, ambiguous requirements, or anything where you expect to change the direction mid-implementation. Those situations need a single session where you can iterate.

What Can Go Wrong

Teammates going silent: if a teammate hits a hard error (build failure, missing dependency, blocked tool call) and does not message the lead, the lead has no signal from the message channel alone. But Claude Code gives you direct access to each teammate’s session. You can tab into any running teammate’s session, inspect its current state, see what it was doing when it stopped, and get it back on track directly. The idle-check hook also fires after 30 minutes of inactivity, requiring the teammate to write a session state file before going idle, which gives you a breadcrumb in the file system. Between the session tab and the state file, a stuck teammate is never a black box.

Spec errors discovered mid-task: if the task spec references a file that does not exist or a pattern that has changed, the teammate will either adapt (if it can) or message the lead with the discrepancy. The lead surfaces it to you. This is the right behavior, a teammate that silently adapts without reporting is harder to trust than one that flags the deviation explicitly.

Context loss on long tasks: the compaction context injector hook ensures teammates retain their behavioral rules across compaction events. But for very long tasks, context can still degrade. Session state snapshots (written every 20 tool calls via the session state hooks) let a replacement teammate pick up where the original left off without re-doing completed work.

Lead prematurely shutting down a teammate: the lead can terminate a teammate session. It can do this when it concludes the teammate is stuck, has finished, or is no longer needed. The problem is that the lead may be wrong, and a terminated teammate loses all in-progress work. This is one of the more painful failures because it is silent from your perspective and irreversible without re-spawning.

Two mitigations work together. First, add a rule to your global CLAUDE.md that the lead must never automatically shut down a teammate without explicit user instruction. This makes the constraint unconditional rather than something the lead exercises its own judgment about. Second, when starting a team session, explicitly tell the lead in your first message not to terminate any teammates without being told to. The global rule handles the case where you forget; the explicit prompt reinforces it for the session at hand. Neither is sufficient alone because the global rule can be overridden by in-session reasoning and the in-session prompt is forgotten after compaction. Together they cover both failure modes.

The Lead’s Job

The lead’s job is coordination, not implementation. In practice this means:

• Route every user request to the appropriate teammate rather than handling it directly
• Send structured task assignments, not freeform instructions
• Track which teammates have outstanding assignments and which have reported
• Surface findings to the user when teammates respond
• Never commit, push, or create PRs without explicit user approval

If you find the lead reading files, running builds, or writing code, something has gone wrong with the role separation. The lead should be a thin coordination layer, not a second implementer.

The next guide in this series covers testing and validation: how to structure verification so the evidence is real, the pre-change baseline that makes test attribution arithmetic, and the purpose-built validation tools that fill the gaps unit tests leave open.