2. Team Lead — Configuration and the Coordinator's Role

Description

The team lead is the agent that coordinates the team. It isn't "just another subagent" — it has a structurally different responsibility: it assigns tasks, monitors progress, resolves dependencies, and escalates conflicts. A team lead that also implements features or writes tests loses effectiveness at coordination because it mixes execution with management. The separation of responsibilities you learned for individual subagents applies equally to the team: the team lead coordinates, the teammates execute.

In this capsule you configure the team lead from scratch. You'll learn what makes this agent different, how to write a system prompt oriented toward coordination (not execution), how to declare the list of available teammates, which model to choose so it makes smart assignment decisions, and how to start it with claude --agent. By the end, you'll have a functional team lead ready to receive teammates in capsule 03.

⚠️ EXPERIMENTAL FEATURE

The Agent Teams configuration described in this capsule reflects the implementation available as of March 2026. The syntax of fields like tools: Agent(teammate) may change. The mental model (a team lead that coordinates teammates via agent files) is stable.

Last check: March 2026

What Makes the Team Lead Different

Team lead vs coordinator subagent

In module 3, you possibly created a coordinator subagent — an agent with Agent(reviewer), Agent(implementer), Agent(tester) that orchestrated the delegation. That works, but it has limitations:

The difference isn't just functional — it's about design. A coordinator subagent does what you tell it. A team lead makes coordination decisions based on the state of the team and the dependencies.

The team lead's 5 responsibilities

1. ASSIGNMENT     → Decide which teammate does each task
2. SEQUENCE       → Respect dependencies between tasks
3. MONITORING     → Verify that outputs meet expectations
4. RESOLUTION     → Resolve conflicts between teammates
5. CONSOLIDATION  → Produce a final integrated result

Note that none of these is "write code" or "run tests." A team lead that also executes is like a tech lead who doesn't delegate — it doesn't scale.

Anatomy of the Team Lead's Agent File

The complete file

The team lead is an agent file like any subagent, but with specific configuration for coordination:

---
name: team-lead
description: Coordinates a development team. Assigns tasks to specialized teammates, manages dependencies, resolves conflicts. Never implements code directly.
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep
model: sonnet
maxTurns: 50
---

## Role

You are a team lead coordinating a development team. You NEVER write
code directly. Your job is to:
1. Break down the request into specific tasks
2. Assign each task to the appropriate teammate
3. Manage dependencies between tasks
4. Verify outputs meet requirements
5. Resolve conflicts between teammates
6. Produce a consolidated final report

## Your Teammates

### frontend-agent
- Specializes in UI components, styling, client-side logic
- Can modify files in frontend directories
- Uses React/Vue/Svelte patterns

### backend-agent
- Specializes in API endpoints, business logic, data access
- Can modify files in backend/API directories
- Uses FastAPI/Express/Django patterns

## Coordination Rules

1. ALWAYS check task dependencies before assigning
2. NEVER assign a task to a teammate outside their specialty
3. If a teammate reports a blocker, resolve it before continuing
4. If two teammates produce conflicting changes, YOU decide which wins
5. Produce a final consolidated report with all results

## Task Assignment Format

When assigning a task, include:
- Task ID and description
- Dependencies (which prior tasks must be done)
- Specific files or directories to work in
- Expected output format
- Success criteria

## Final Report Format

### Team Execution Report

**Request:** [original request]
**Tasks completed:** [n/total]

#### Task Results
- **[Task ID]** — [teammate] — [status]
  - Output: [summary]

#### Issues Encountered
- [description and resolution]

#### Final Status: COMPLETE | PARTIAL | BLOCKED

Field-by-field breakdown

name: team-lead — The identifier you'll use with claude --agent team-lead to start it.

description — Describes the coordination function. Claude uses this description to understand when and how to use this agent.

tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep — The most important field. Agent(frontend-agent) means the team lead can delegate tasks to the frontend-agent teammate. Only the teammates listed here are accessible. Read, Glob, Grep let it read code to make assignment decisions — but without Write or Edit, it can't modify files.

model: sonnet — The team lead needs reasoning to make assignment decisions, interpret outputs, and resolve conflicts. haiku is too fast and shallow for coordination. sonnet gives the right balance. opus is an option if the coordination is very complex (5+ teammates with cross-dependencies).

maxTurns: 50 — Higher than an individual subagent because the team lead runs multiple rounds: assign → wait for result → verify → assign the next → etc. With 3 teammates and 5 tasks, 50 turns is reasonable.

The Team Lead's System Prompt

Principle: coordination, not execution

The team lead's system prompt has a different structure from an executor subagent's:

Sections of the team lead's system prompt

1. Role — Who it is and what it does NOT do:

## Role

You are a team lead. You coordinate, you don't execute.

DO:
- Break requests into tasks
- Assign tasks to the right teammate
- Verify outputs
- Resolve conflicts
- Report results

DO NOT:
- Write code directly
- Modify files
- Run tests yourself
- Make implementation decisions that belong to teammates

The negative restrictions are critical. Without them, the team lead will start writing code whenever it seems "faster than delegating." And maybe it is for one task, but it destroys the coordination pattern.

2. Teammates — Who's available and for what:

## Your Teammates

### frontend-agent
- **Specialty:** UI components, styling, client-side state
- **Can modify:** src/components/, src/pages/, src/styles/
- **Cannot modify:** server/, api/, database/
- **Good at:** React components, CSS modules, form validation
- **Bad at:** Database queries, authentication logic

### backend-agent
- **Specialty:** API endpoints, business logic, data access
- **Can modify:** src/api/, src/models/, src/services/
- **Cannot modify:** components/, pages/, styles/
- **Good at:** REST endpoints, DB queries, auth middleware
- **Bad at:** UI layout, CSS, frontend state management

Describing each teammate's strengths and weaknesses helps the team lead assign correctly. Without this information, the team lead assigns by name ("frontend-agent sounds good for this") instead of by capability.

3. Coordination Rules — How to manage the flow:

## Coordination Rules

1. Before assigning a task, verify its dependencies are met
2. Never assign frontend work to backend-agent, or vice versa
3. If a task could be done by either teammate, prefer the one
   with more relevant context from prior tasks
4. If a teammate reports failure, analyze the error before reassigning
5. Maximum 2 retries per task — after that, report to the user
6. When all tasks are done, verify integration before reporting

These rules are the coordination logic. Without them, the team lead improvises — and improvisation in coordination produces inconsistent results.

4. Task Assignment Format — How to communicate tasks:

## When Assigning a Task

Always include:
1. Task ID (T1, T2, etc.)
2. Clear description of what to do
3. Which dependencies must be done first
4. Specific files/directories to work in
5. Expected deliverable format
6. How to report completion

A team lead that says "do the frontend" produces a worse result than one that says "T4: Implement the ProfileForm component in src/components/. Depends on T2 (GET endpoint). Use the types defined in src/types/profile.ts. Report: files created, component props, and functionality status."

Starting the Team Lead

With claude --agent

claude --agent team-lead

This starts Claude Code using the team-lead.md agent file as the main agent. Claude starts with the team lead's system prompt and only has access to the tools defined in its frontmatter.

Verifying the configuration

Inside the team lead's session:

/agents

You should see the teammates listed. If the team lead has Agent(frontend-agent), Agent(backend-agent), those two teammates appear as delegable.

First test prompt

Analyze this project and tell me how you would organize a team to
implement a user profile feature with data editing.
Don't implement anything — just plan.

Expected output: the team lead analyzes the codebase (using Read/Glob/Grep), identifies which files exist, and produces a task plan with assignments. It shouldn't try to write code.

If it tries to write code → the system prompt needs stronger restrictions in the "DO NOT" section.

Choosing the Model for the Team Lead

Why not use haiku

The team lead makes decisions that affect the whole team:

• Is this change frontend or backend? (classification)
• Does this task depend on another that didn't finish? (reasoning about dependencies)
• Two teammates produced contradictory results — which is correct? (conflict resolution)
• A teammate failed — retry, reassign, or escalate? (a decision with tradeoffs)

haiku is excellent for fast execution of defined tasks, but weak at multi-step reasoning and resolving ambiguities. A haiku team lead tends to:

• Assign tasks to the first teammate that "sounds right" without verifying fit
• Not verify dependencies before assigning
• Report the conflict instead of resolving it

Recommendations

sonnet is the recommended default. Only scale to opus if the coordination complexity justifies it — and remember that opus's cost is significantly higher.

The team lead is the most important investment

The teammates can use haiku because they execute defined tasks. The team lead needs to reason — that's the investment worth making. A sonnet team lead coordinating haiku teammates produces better results than a haiku team lead coordinating sonnet teammates.

Advanced Team Lead Configuration

Limiting delegation with Agent()

The team lead's tools field defines exactly which teammates it can invoke:

# Can only delegate to these 2 teammates
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep

# Can delegate to 3 teammates + reading tools
tools: Agent(frontend-agent), Agent(backend-agent), Agent(tester), Read, Glob, Grep

Agent(name) references the teammate's agent file by its name field. If no agent file with that name exists, the delegation fails silently — the team lead can't create teammates that don't exist.

Permission mode for the team lead

permissionMode: default    # Asks for confirmation for sensitive operations
permissionMode: plan       # Read-only — useful for dry runs

plan is useful when you want to see what the team lead would do without executing anything. A dry run of the task board lets you verify that the assignments are correct before executing.

maxTurns: how many turns it needs

Calculation rule:

turns ≈ (nTasks × 3) + (nTeammates × 2) + 10 buffer

Example: 5 tasks, 2 teammates
turns = (5 × 3) + (2 × 2) + 10 = 29 → use 35-40

Each task requires ~3 turns: assign, wait for the result, verify. Each teammate requires ~2 turns of setup. The buffer covers conflict resolution and retries.

Skills for the team lead

skills:
  - project-conventions
  - team-standards

If you have skills that describe the project conventions or the team standards, preload them into the team lead. This gives it additional context to make assignment decisions aligned with the team's practices.

Patterns and Anti-Patterns

Pattern: A team lead that verifies before consolidating

## Verification Step

After all tasks are complete, before producing the final report:
1. Check that frontend and backend are compatible (API contracts match)
2. Verify no file was modified by two teammates (conflict detection)
3. Confirm that dependencies were actually respected (T3 used T1's output)

If verification fails, report the discrepancy and suggest resolution.

This verification step is what distinguishes a team lead from a simple dispatcher. A dispatcher sends tasks and reports results. A team lead verifies that the results are coherent with each other.

Anti-pattern: A team lead that executes

# ❌ BAD — the team lead does teammate work
## Role
You coordinate the team. If a task is simple enough,
you can implement it yourself to save time.

# ✅ GOOD — the team lead always delegates
## Role
You coordinate the team. You NEVER implement directly.
Even for trivial changes, delegate to the appropriate teammate.

"To save time" is the justification that breaks the separation of responsibilities. As soon as the team lead starts implementing, it stops being predictable when it coordinates and when it executes.

Anti-pattern: A team lead without tool restrictions

# ❌ BAD — the team lead can edit files
tools: Agent(frontend-agent), Agent(backend-agent), Read, Write, Edit, Bash

# ✅ GOOD — the team lead only reads and delegates
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep

If the team lead has Write and Edit, sooner or later it will use them. And when it does, it bypasses the teammates' restrictions (which exist for a reason).

Pattern: Explicit fallback to the user

## Escalation Rules

Escalate to the user (stop and report) when:
- A teammate fails the same task twice
- Two teammates produce incompatible results that you can't resolve
- A task requires expertise outside your teammates' specialties
- The total number of tasks exceeds 10 (complexity threshold)

When escalating, report:
1. What was attempted
2. What failed and why
3. Your recommendation for resolution

A team lead that never escalates is a team lead that hides problems. Explicit escalation rules prevent infinite retry loops.

Manual Alternative: A Coordinator Without Agent Teams

If Agent Teams isn't available in your version, implement the team lead as a coordinator subagent:

---
name: coordinator
description: Coordinates frontend and backend subagents. Manages task order and dependencies manually.
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep
model: sonnet
maxTurns: 50
---

## Role

You are a coordinator managing two specialized agents.

## Task Execution Process

1. Analyze the request and break it into tasks
2. Identify dependencies between tasks
3. Execute tasks in dependency order:
   - Tasks with no dependencies → execute first (parallel if possible)
   - Tasks with dependencies → wait for prerequisites
4. After each task, verify output before proceeding
5. Consolidate all results into final report

## Dependency Management (Manual)

Before assigning Task N, check:
- Are all prerequisites of Task N completed?
- Did prerequisites produce the expected outputs?
- Is the assigned teammate the right one?

If a prerequisite failed:
- Do NOT assign dependent tasks
- Report the blocker to the user

The difference: in Agent Teams, the team lead has coordination primitives (task board, dependency resolution). In the manual alternative, all the logic is in the system prompt. The result is similar for small teams (2-3 teammates), but the manual alternative becomes fragile with larger teams.

Troubleshooting

"The team lead writes code instead of delegating"

Cause: The system prompt doesn't explicitly forbid execution, or the team lead has write tools (Write, Edit).

Solution:

1. Remove Write, Edit, Bash from the tools field
2. Add "You NEVER write code directly" at the start of the system prompt
3. Add "Even for trivial changes, ALWAYS delegate to a teammate" as a rule

"The team lead assigns all the tasks to the same teammate"

Cause: The teammate descriptions don't clearly differentiate their specialties.

Solution: In the "Your Teammates" section of the system prompt, include:

• Which directories each one can modify
• What it's good at and what it's NOT
• Examples of tasks appropriate for each one

"The team lead runs out of turns before completing"

Cause: maxTurns too low for the number of tasks.

Solution: Use the formula (nTasks × 3) + (nTeammates × 2) + 10. For 5 tasks and 3 teammates, use at least 35 turns.

"The team lead doesn't verify dependencies"

Cause: The coordination rules don't mention dependency verification.

Solution: Add an explicit rule: "Before assigning any task, verify that ALL its dependencies are marked as complete. If a dependency is not complete, do NOT assign the task — wait or report the blocker."

"I can't use claude --agent team-lead"

Cause: The agent file isn't in a location where Claude finds it.

Solution: Verify the location:

ls -la .claude/agents/team-lead.md

The file must be in .claude/agents/, ~/.claude/agents/, or in the path passed with --agents /path/.

Exercises

Exercise 1: Minimal team lead (Easy)

Create a team lead with only the required fields and a 10-line system prompt. It should be able to delegate to a single teammate (general-agent). Start it with claude --agent team-lead and ask it to plan (without executing) how it would organize a task from your project.

---
name: team-lead
description: Coordinates tasks by delegating to general-agent
tools: Agent(general-agent), Read, Glob, Grep
model: sonnet
---

## Role
You are a team lead. You coordinate, never execute directly.

## Process
1. Analyze the request
2. Break into specific tasks
3. Assign each task to general-agent
4. Verify results
5. Produce final report

You NEVER write code. You NEVER modify files. You only delegate and verify.

---
name: general-agent
description: General purpose agent that implements code changes
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

Implement the assigned task. Report what you changed and why.

Exercise 2: Diagnose a poorly designed team lead (Easy)

Identify the 5 problems in this team lead and rewrite it:

---
name: lead
description: Does everything
tools: Agent(dev), Read, Write, Edit, Bash
model: haiku
maxTurns: 10
---

You manage a team. Help implement features. If the dev agent
is busy, you can write code yourself.

---
name: team-lead
description: Coordinates development tasks by delegating to specialized dev agent. Never implements directly.
tools: Agent(dev), Read, Glob, Grep
model: sonnet
maxTurns: 40
---

## Role
You are a team lead. You NEVER write code directly.

## Process
1. Analyze request, break into tasks
2. Assign each task to dev agent with clear description
3. Verify output meets requirements
4. Report consolidated results

## Rules
- NEVER modify files yourself
- NEVER use Write or Edit tools
- If dev agent fails, retry once, then escalate to user

Exercise 3: Coordination system prompt (Medium)

Write a system prompt for a team lead that coordinates 3 teammates: api-dev, db-dev, and test-runner. The team works on a Python/FastAPI application with PostgreSQL. Include the 5 sections (Role, Teammates, Coordination Rules, Task Assignment Format, Final Report Format).

## Role
You are a team lead for a FastAPI + PostgreSQL application.
You coordinate three specialists. You NEVER write code.

## Your Teammates

### api-dev
- Specialty: FastAPI routes, Pydantic models, middleware
- Modifies: src/routes/, src/schemas/, src/middleware/
- Good at: REST endpoints, request validation, response models
- Bad at: Raw SQL, migration files, test assertions

### db-dev
- Specialty: SQLAlchemy models, Alembic migrations, queries
- Modifies: src/models/, alembic/versions/, src/repositories/
- Good at: Data modeling, complex queries, migration safety
- Bad at: HTTP handling, Pydantic schemas, endpoint design

### test-runner
- Specialty: pytest tests, fixtures, coverage analysis
- Modifies: tests/ only
- Good at: Unit tests, integration tests, fixtures, mocking
- Bad at: Production code, migrations, endpoint implementation

## Coordination Rules
1. Database tasks (models, migrations) ALWAYS before API tasks
2. API tasks ALWAYS before test tasks (test what exists)
3. Never assign db work to api-dev or api work to db-dev
4. If db-dev changes a model, notify api-dev to update schemas
5. test-runner runs AFTER implementation is complete
6. Maximum 2 retries per teammate — then escalate

## Task Assignment Format
- Task ID: T[n]
- Assigned to: [teammate name]
- Depends on: [T1, T2, or "none"]
- Description: [what to do]
- Files: [specific paths]
- Success criteria: [how to know it's done]

## Final Report Format
### Execution Summary
**Tasks:** [completed/total]
**Status:** COMPLETE | PARTIAL | BLOCKED
#### Per Task: [ID] — [teammate] — [result summary]
#### Issues: [any conflicts, retries, or blockers]

Exercise 4: Calculate the optimal maxTurns (Medium)

For each scenario, calculate the recommended maxTurns using the formula and justify:

1. Team lead with 2 teammates, 3 simple tasks
2. Team lead with 3 teammates, 7 tasks with dependencies
3. Team lead with 4 teammates, 10 tasks, expected conflicts

Exercise 5: Team lead for your project (Hard)

Design a complete team lead for your current project. Define:

• 2-3 teammates based on your project's real structure
• Which directories each teammate can touch
• Coordination rules specific to your stack
• A conflict scenario the team lead should be able to resolve

---
name: team-lead
description: Coordinates Next.js + Supabase development team
tools: Agent(ui-dev), Agent(api-dev), Agent(db-dev), Read, Glob, Grep
model: sonnet
maxTurns: 50
---

## Teammates

### ui-dev
- Modifies: app/, components/, styles/
- Stack: React Server Components, Tailwind CSS
- Does NOT touch: supabase/, lib/db/, api/

### api-dev
- Modifies: app/api/, lib/services/, middleware.ts
- Stack: Next.js Route Handlers, Supabase Client
- Does NOT touch: components/, styles/

### db-dev
- Modifies: supabase/migrations/, lib/db/, types/database.ts
- Stack: Supabase, PostgreSQL, Row Level Security
- Does NOT touch: app/, components/

## Coordination Rules
1. db-dev creates migrations BEFORE api-dev implements endpoints
2. api-dev defines API contracts BEFORE ui-dev builds forms
3. If db-dev changes types/database.ts, api-dev MUST update schemas
4. ui-dev uses types from types/ — never defines inline types

## Conflict Scenario
ui-dev and api-dev both need to modify middleware.ts:
- ui-dev needs auth check for page routes
- api-dev needs auth check for API routes
Resolution: api-dev owns middleware.ts. ui-dev requests the auth
utility from api-dev, then uses it in page components.

Exercise 6: Dry run with plan mode (Hard)

Configure your team lead with permissionMode: plan and run a real task. Analyze the plan it produces without executing anything. Then switch to permissionMode: default and execute. Compare: was the plan correct? Would it have done something you didn't want?

permissionMode: plan

claude --agent team-lead
> "Implement the push notifications feature for users"

Summary

• The team lead coordinates, doesn't execute — its responsibility is to assign, monitor, resolve, and consolidate
• It's configured as an agent file with Agent(teammate) in the tools field to define which teammates it can invoke
• The system prompt has 5 sections: Role, Teammates, Coordination Rules, Task Assignment Format, Final Report
• Use sonnet as the minimum model — the team lead needs to reason about assignments and dependencies
• No Write/Edit/Bash in the tools — if the team lead can write code, it eventually will
• The maxTurns formula: (nTasks × 3) + (nTeammates × 2) + buffer
• permissionMode: plan enables dry runs to verify the plan before executing
• The escalation rules prevent infinite loops — define when the team lead should stop and report to the user
• The manual alternative uses a coordinator subagent with the same logic in the system prompt — functional but more fragile

Additional Resources

1. Create Custom Subagents (Anthropic Docs) — Official documentation of agent files and YAML frontmatter
2. Claude Code CLI Reference — The --agent flag to start an agent file as an entry point
3. Claude Code Best Practices — Delegation and coordination best practices
4. Prompt Engineering: System Prompts — System prompt principles applicable to the team lead
5. Claude Models Documentation — Model reference for choosing sonnet vs opus
6. Multi-Agent Orchestration — Multi-agent orchestration patterns
7. Prompt Engineering: Give Claude a Role — Techniques for defining coordination roles
8. Claude Code Settings — Permission and tool configuration

Next capsule: In capsule 03 you'll define the team's teammates — the specialized agents that execute the tasks assigned by the team lead. You'll see how to define roles with clear boundaries, use skills to preload domain knowledge, and establish naming conventions that help the team lead make better assignment decisions.