1. Module Introduction — From Manual Orchestration to Agent Teams

Description

In Phase 1 you learned to create subagents with an identity of their own, to give them persistent memory, and to delegate tasks to them in parallel. You coordinated everything manually — you decided which agent did what, when it started, how dependencies were resolved, and what happened when one agent finished before another. It worked. But if you're honest, you noticed the pattern: as you add more agents and more dependencies, manual coordination becomes the bottleneck. It's not the code that slows you down — it's the logistics.

Agent Teams formalize that coordination. Instead of you being the orchestra conductor who moves each piece, you define a team with a team lead that coordinates and teammates that execute. The team lead knows which tasks exist, who can do them, what depends on what, and when to reassign work. You go from "agent director" to "team designer" — you configure the structure once and let the team lead resolve the execution.

This module opens Phase 2 because Agent Teams are the natural evolution of everything you built in Phase 1. The custom subagents from module 1 become teammates. The memory from module 2 gives context to each team member. The parallel delegation from module 3 is automated with a task board and explicit dependencies. Agent Teams don't replace what you learned — they package it into an abstraction that scales.

By the end, you'll have a team of 3 agents (team lead + frontend agent + backend agent) with a task board of 5+ tasks and real dependencies. Not as a demo — as a functional system you can adapt to your project.

---

⚠️ EXPERIMENTAL FEATURE

Agent Teams is an experimental Claude Code feature. The API, configuration, and behavior may change significantly between versions. This module teaches the mental model (team lead, teammates, task board, dependencies) that is transferable regardless of the specific API, and the practical configuration according to the implementation available as of March 2026.

If Agent Teams isn't accessible in your version of Claude Code, each capsule includes a manual alternative section using the Phase 1 patterns. Don't get stuck.

Last functionality check: March 2026

---

Where Are We in the Guide?

Context in the Guide

This guide has 8 modules organized into 3 phases:

Phase 1: Advanced Subagents (Modules 1-3)            ← COMPLETED
├── Module 1: Custom Subagents                        ✅
├── Module 2: Agent Memory and Scopes                 ✅
└── Module 3: Parallel Sub-Agent Delegation            ✅

Phase 2: Agent Teams and Plugins (Modules 4-6)
├── Module 4: Agent Teams                              ← YOU ARE HERE
├── Module 5: Plugins: Creating and Distributing
└── Module 6: Advanced Hooks and Headless SDK

Phase 3: Orchestration (Modules 7-8)
├── Module 7: Remote Control and CLAUDE.md for Teams
└── Module 8: Project: Complete Multi-Agent System

Total estimated duration: 8-10 hours (self-paced).

What changes in Phase 2?

In Phase 1 you learned the building blocks: subagents with identity, memory, and parallel delegation. You controlled everything — every prompt, every sequence, every merge. Phase 2 introduces coordination abstractions: Agent Teams automate the orchestration, plugins package reusable configurations, and hooks + SDK give programmatic control. The mental shift is: you stop operating individual agents and start designing systems.

---

The Problem: Manual Coordination Doesn't Scale

What you experienced in Phase 1

In module 3 you delegated tasks in parallel. Maybe something like this:

"Run in parallel:
 1. The reviewer analyzes src/api/ looking for security problems
 2. The implementer adds input validation to the endpoints
 3. The tester runs the integration test suite

 When they all finish, consolidate the results."

It worked with 3 agents. But there was friction:

• Implicit dependencies: The tester should run after the implementer, but you launched it in parallel and it had to use the pre-change code.
• File conflicts: The reviewer and the implementer touched the same files simultaneously.
• Manual merge: Consolidating 3 reports with slightly different formats required you (or Claude) to interpret each output.
• No visibility: You didn't know which agent was doing what until they all finished.

Scale the scenario to 5 agents

Imagine a real development team:

1. architect    → Designs the feature structure
2. frontend     → Implements the UI components
3. backend      → Implements the API endpoints
4. tester       → Writes and runs tests
5. reviewer     → Reviews the frontend and backend code

The dependencies are now complex:

architect ─────→ frontend ─────→ reviewer
           └──→ backend  ──┬──→ reviewer
                           └──→ tester

Frontend and backend depend on the architect. The reviewer depends on frontend AND backend. The tester depends on backend. Coordinating this manually means:

1. Launch the architect first
2. Wait for it to finish
3. Launch frontend and backend in parallel
4. Wait for both to finish
5. Launch reviewer and tester in parallel
6. Consolidate everything

And if the backend fails halfway through, what happens to the tester that was waiting for it? And the reviewer that needs both? Each branch multiplies the complexity of your orchestration prompt.

What Agent Teams solve

With Agent Teams, that coordination is declared, not programmed:

Team Lead: "I have 5 tasks with these dependencies.
            I assign each one to the appropriate teammate.
            When a task finishes, I check dependencies
            and launch the next ones automatically."

You define the team structure and the dependencies. The team lead resolves the execution. If a teammate fails, the team lead decides whether to reassign, retry, or escalate. That's what this module teaches.

---

Agent Teams: The Mental Model

The 4 components

┌─────────────────────────────────────────────────┐
│                  AGENT TEAM                      │
│                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │ Teammate │    │ Teammate │    │ Teammate │   │
│  │ frontend │    │ backend  │    │ tester   │   │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘   │
│       │               │               │          │
│       └───────┬───────┘───────────────┘          │
│               │                                  │
│        ┌──────┴──────┐                           │
│        │  Team Lead  │                           │
│        │ (coordinates)│                          │
│        └──────┬──────┘                           │
│               │                                  │
│        ┌──────┴──────┐                           │
│        │  Task Board │                           │
│        └─────────────┘                           │
└─────────────────────────────────────────────────┘

1. Team Lead — The main agent that coordinates. It doesn't execute code tasks directly — it assigns work, monitors progress, resolves dependencies and conflicts. It's configured as the main agent with claude --agent team-lead.

2. Teammates — Specialized subagents available to the team lead. Each teammate has its role, tools, and expertise defined in an agent file. The team lead knows their capabilities and assigns them appropriate tasks.

3. Task Board — The list of tasks with states (pending, in-progress, done, blocked), dependencies, and priorities. The team lead manages the task board, deciding which task to launch and when.

4. Dependencies — Relationships between tasks: "test depends on implementation," "review depends on frontend AND backend." Dependencies determine the execution order — a task isn't launched until its dependencies are complete.

The right analogy

Don't think of Agent Teams as "subagents with a manager." Think of a kanban board with automatic assignment:

BACKLOG          IN PROGRESS       DONE
┌──────────┐     ┌──────────┐     ┌──────────┐
│ design   │ ──→ │ frontend │ ──→ │ backend  │
│ review   │     │ (agent)  │     │ (done)   │
│ tests    │     └──────────┘     └──────────┘
└──────────┘

Dependencies:  frontend → waits for design
               tests → waits for backend
               review → waits for frontend AND backend

The team lead is the one who moves the cards. When a task goes to DONE, it checks which blocked tasks get unblocked and assigns them to the appropriate teammate.

Agent Teams vs Subagents: the key difference

Aspect	Subagents (Phase 1)	Agent Teams (Phase 2)
Who coordinates	You (or Claude as a proxy)	The team lead
Dependencies	Implicit in the prompt order	Explicit and declared
Visibility	You see the result at the end	Task board with states
Failure of an agent	You decide what to do	Team lead reassigns or escalates
Scalability	2-3 agents comfortable	5+ agents manageable
Configuration	Orchestration prompt	Agent files + team config

The inversion of control is the fundamental change: in Phase 1, the control is yours. In Agent Teams, the control belongs to the team lead — you define the rules, it executes them.

---

Module Objective

By the end of this module you'll be able to:

• ✅ Configure an Agent Team with a team lead and 2+ teammates using agent files
• ✅ Define the roles and specialties of each teammate with clear boundaries
• ✅ Create a task board with 5+ tasks, explicit dependencies, and priorities
• ✅ Configure messaging between teammates for direct coordination
• ✅ Handle conflicts and failures: a teammate that fails, contradictory results, reassignment
• ✅ Observe and analyze how the team lead resolves the execution of a complex task board

Professional objective

Agent Teams represents what development with AI will look like in the coming years: not a single agent that does everything, but teams of specialized agents with automatic coordination. Mastering the mental model of team lead, task board, and dependencies prepares you for any multi-agent orchestration framework — the specific API may change, but the coordination patterns are universal.

---

Module Roadmap

Capsule map

#	Capsule	What you'll learn	Type
01	Introduction (this one)	Context, mental model, why Agent Teams matter	Intro
02	Team Lead: Configuration	Configuring the team lead, its system prompt, model, and teammate list	Technical
03	Teammates: Roles and Limits	Defining teammates with specialties, skills, and clear boundaries	Technical
04	Task Board and Dependencies	Creating and managing a task board with dependencies between tasks	Technical
05	Messaging and Conflicts	Communication between teammates, conflict resolution, failure modes	Technical
06	Project: Team of 3 Agents	Team lead + frontend + backend with a task board and real dependencies	Project

Learning flow

First you'll understand how the team lead is configured — the agent that coordinates everything and the central piece of the team (capsule 02). Then you'll learn to define teammates with clear roles and limits — because a team without specialization is just a group of generic agents (capsule 03). Next you'll see how the task board works — assigning tasks, declaring dependencies, managing priorities (capsule 04). You'll continue with messaging between teammates and conflict resolution — the communication that makes the team work as a unit (capsule 05). Finally, you'll build a functional team of 3 agents with a real task board (capsule 06).

The progression is: configure the lead → define the members → assign the work → resolve problems → build the system.

Each capsule builds on the previous one. The task board (04) needs defined teammates (03), which in turn need a configured team lead (02). Don't skip capsules.

Estimated module duration: 1.25-1.5 hours.

---

Connection to the Project

Module project: Team of 3 Agents with a Task Board

In capsule 06 you'll build a functional team:

1. Team Lead — Coordinates the team, assigns tasks from the task board, resolves dependencies and conflicts. It doesn't write code directly.

2. Frontend Agent — Specialized in UI components, styles, and frontend structure. It only touches files in frontend directories.

3. Backend Agent — Specialized in API endpoints, business logic, and data access. It only touches files in backend directories.

Your prompt:
"Implement the user profile feature with data editing"

↓

Team Lead:
├── Task 1: "Design the data schema"   → backend agent
├── Task 2: "Endpoint GET /profile"    → backend agent (depends on T1)
├── Task 3: "Endpoint PUT /profile"    → backend agent (depends on T1)
├── Task 4: "ProfilePage component"    → frontend agent (depends on T2)
├── Task 5: "Editing form"             → frontend agent (depends on T3, T4)
└── Task 6: "Integration and review"   → team lead (depends on T2-T5)

Connection to the final project (Module 8)

The team of 3 agents is the prototype of the capstone project's 5-agent system. In module 8, you'll expand the team lead to coordinate architect, frontend, backend, tester, and reviewer. The task board, dependency, and conflict resolution patterns you learn here apply directly — only the scale changes.

---

Prerequisites

Required knowledge

• ✅ Modules 1-3 completed — Custom subagents, memory scopes, parallel delegation
• ✅ Subagent files — You know how to create Markdown files with YAML frontmatter
• ✅ Tool restriction — You understand allowlists, denylists, and permission modes
• ✅ Parallel delegation — You've run multiple subagents simultaneously
• ✅ Output parsing — You know how to design system prompts that produce parseable outputs

Quick check

If you can answer "yes" to these questions, you're ready:

1. Can you create a subagent as a .md file with YAML frontmatter in under 5 minutes?
2. Do you know the difference between tools (allowlist) and disallowedTools (denylist)?
3. Have you delegated at least 2 tasks in parallel and consolidated the results?
4. Can you explain why a reviewer shouldn't have access to Write?
5. Do you understand the concept of "only the final message returns to the parent"?

You don't need

• ❌ Prior experience with Agent Teams — covered completely here
• ❌ Knowledge of plugins — covered in module 5
• ❌ Experience with the headless SDK — covered in module 6
• ❌ A large project — it works with any codebase of 5+ files

---

Module Setup

What you need to have ready

1. Claude Code up to date:

claude --version

Make sure you have the most recent version. Agent Teams requires support for agent files with the field that defines teammates.

2. The Phase 1 subagents available:

If you completed modules 1-3, you already have subagent files in .claude/agents/. We'll adapt them for Agent Teams in this module.

ls .claude/agents/

3. Directory for the team:

mkdir -p .claude/agents

4. Verify Agent Teams support:

claude --help | grep -i agent

If the --agent flag appears in the help, you have support for running agent files as an entry point. If Agent Teams with team lead and teammates isn't available in your version, the capsules include manual alternatives.

---

Limits: What Is NOT Covered in This Module

• ❌ Plugins — Covered in Module 5. Here the agent files are local, not packaged
• ❌ Advanced hooks and SDK — Covered in Module 6. Here we use basic hooks when necessary
• ❌ Remote control — Covered in Module 7. Here everything is local
• ❌ More than 5 teammates — We cover teams of 2-3 teammates. Larger teams follow the same patterns but with additional complexity
• ❌ Agent Teams in CI/CD — Covered in the CI/CD Pipelines guide. Here everything is interactive

---

Manual Alternative: If Agent Teams Isn't Available

If your version of Claude Code doesn't support Agent Teams as a formal feature, you can implement the same mental model with the Phase 1 patterns:

Team Lead     → A "coordinator" subagent with Agent(teammate1), Agent(teammate2)
Task Board    → The coordinator's system prompt with the task list and dependencies
Dependencies  → Logic in the system prompt: "Don't launch Task B until Task A reports DONE"
Messaging     → The coordinator passes outputs between subagents manually

Each capsule includes a "Manual alternative" section with the equivalent pattern. The mental model is identical — the difference is that with Agent Teams the coordination is automatic, and without them you program it in the coordinator's system prompt.

The advantage of learning Agent Teams even if you use the alternative: when the feature is GA, you already understand the concepts and the migration is direct.

---

Evidence of Success

By the end of this module, you'll know you succeeded if:

• ✅ You can configure a team lead with its teammate list in an agent file
• ✅ Each teammate has a clear role with boundaries the team lead respects
• ✅ The task board has 5+ tasks with dependencies and priorities
• ✅ The team lead assigns tasks to the correct teammate based on its description
• ✅ The teammates can exchange information when they need to coordinate
• ✅ The team lead resolves at least one case of conflict or failure during execution
• ✅ You can explain the difference between manual orchestration (Phase 1) and Agent Teams

Quick self-assessment test

If you can answer these questions by the end:

1. What's the difference between a team lead and a coordinator subagent?
2. How is a dependency between tasks declared?
3. What happens when a teammate fails in the middle of a task?
4. How do you configure which teammates the team lead can invoke?
5. Why shouldn't the team lead execute code tasks directly?

---

Summary

• This module marks the transition from manual orchestration to team design — you define the structure, the team lead resolves the execution
• Agent Teams have 4 components: team lead (coordinates), teammates (execute), task board (task list), and dependencies (execution order)
• The key difference from Phase 1: the dependencies are explicit and the team lead coordinates automatically instead of you doing it
• Agent Teams is an experimental feature (last check: March 2026) — the module teaches transferable patterns and provides manual alternatives
• The project builds a team of 3 agents (team lead + frontend + backend) with a task board and real dependencies
• Everything learned in Phase 1 (subagents, memory, parallel delegation) is the foundation — Agent Teams package those building blocks into an abstraction that scales

---

Additional Resources

1. Claude Code Sub-Agents (Anthropic Docs) — Official documentation of subagents as the foundation of Agent Teams
2. Create Custom Subagents — Reference for agent files, YAML frontmatter, and tool restriction
3. Claude Code CLI Reference — The --agent flag to run an agent file as an entry point
4. Claude Code Best Practices — Delegation and coordination best practices
5. Claude Code Settings — Permission and tool configuration
6. Claude Code Overview — General context of Claude Code as an agent
7. Prompt Engineering: System Prompts — System prompt principles applicable to the team lead
8. Multi-Agent Orchestration Patterns — Anthropic's multi-agent coordination patterns

---

Next capsule: In capsule 02 you'll configure the team lead — the agent that coordinates the whole team. You'll see what makes it different from a regular subagent, how to define its system prompt for coordination (not execution), how to declare the list of available teammates, and which model to use so it makes good assignment decisions.