Module 4: Agent Teams

6. Project — Team of 3 Agents with a Task Board

Project Description

You've learned to configure a team lead with coordination responsibilities, to define teammates with clear roles and boundaries, to design task boards with explicit dependencies, and to manage communication and conflicts between agents. Now you're going to integrate everything into a functional team.

In this project you build an Agent Team of 3 members: a team lead that coordinates, a frontend-agent that implements UI components, and a backend-agent that implements API endpoints. The team works on a task board of 6 tasks with real dependencies to implement a user profile feature with data editing.

The flow is: you write a prompt describing the feature. The team lead analyzes the codebase, generates the task board, and presents it for approval. After your confirmation, it assigns tasks respecting dependencies — it starts with the ones that have no dependencies, launches in parallel when possible, and waits for completions before unblocking dependent tasks. When all the tasks are DONE, the team lead produces a consolidated report.

This project is the close of Module 4. If the team executes the complete task board, resolves at least one dependency in the correct order, and produces an integrated result — you've mastered Agent Teams. If in addition you can explain why the team lead didn't write code and how it resolved a conflict between teammates — you've internalized the coordination mental model.

⚠️ EXPERIMENTAL FEATURE

Agent Teams is an experimental Claude Code feature. If it isn't available in your version, this project includes a manual alternative section using a coordinator subagent with the same agent files. The teammates work as standard subagents in both cases.

Last check: March 2026

Project Objective

Build a functional 3-member Agent Team (team lead + frontend-agent + backend-agent) with a task board of 6 tasks and real dependencies, run it on an existing project, and analyze how the team lead coordinates the execution.

By the end of this project:

✅ You'll have 3 complete agent files in .claude/agents/ ready to use
✅ The team lead will generate a task board with dependencies and present it before executing
✅ The dependencies will be respected automatically — no task runs before its prerequisites
✅ The frontend-agent and backend-agent will work within their boundaries without file conflicts
✅ The team lead will resolve at least one coordination case (conflict, idle, or dependency chain)
✅ The final report will consolidate results from all the teammates

Estimated duration: 1.5-2 hours (setup: 15 min + agent files: 30 min + execution: 30 min + iteration: 30 min).

Technical Specifications

Technology Stack

Tool: Claude Code (recent version)
Agent files: Markdown with YAML frontmatter
Location: .claude/agents/ (project scope)
Models: sonnet (team lead and teammates)
Base project: Any project with separate frontend and backend, or a full-stack project with differentiated directories

Base Project Requirements

Requirement	Minimum	Ideal
Frontend directory (components/)	Exists	With 3+ components
Backend directory (api/ or routes/)	Exists	With 2+ endpoints
Frontend framework	React, Vue, or Svelte	React with TypeScript
Backend framework	FastAPI, Express, or Django	FastAPI with Pydantic
CLAUDE.md	Basic	With conventions for both stacks
Git	Initialized	With 3+ commits

If you don't have a project with frontend and backend, create a minimal structure:

mkdir -p my-project/src/{components,pages,api/routes,api/schemas,models,types}
touch my-project/CLAUDE.md
cd my-project && git init

Initial Setup

cd your-project

mkdir -p .claude/agents

claude --version

ls src/

Verify that your project has separate directories for frontend and backend.

Final Project Structure

By the end, your project will have these additional files:

your-project/
├── .claude/
│   └── agents/
│       ├── team-lead.md          ← Team coordinator
│       ├── frontend-agent.md     ← UI specialist
│       └── backend-agent.md      ← API specialist
├── src/
│   ├── components/               ← frontend-agent territory
│   ├── pages/                    ← frontend-agent territory
│   ├── api/                      ← backend-agent territory
│   ├── models/                   ← backend-agent territory
│   └── types/                    ← shared (team lead decides)
└── CLAUDE.md

Step 1: Create the Backend Agent

Start with the backend-agent because it produces the API contracts the frontend consumes. Without an API, the frontend doesn't know what data to expect.

Create .claude/agents/backend-agent.md:

---
name: backend-agent
description: Implements API endpoints, Pydantic schemas, and business logic. Works exclusively in src/api/, src/models/, src/services/, and src/types/. Expert in FastAPI and Pydantic.
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
maxTurns: 25
---

## Role

You are a backend specialist on a development team coordinated by
a team lead. You implement API endpoints, data schemas, and business
logic. You receive task assignments with specific requirements and
report results in a structured format.

## Boundaries

### Files you OWN (can create and modify):
- src/api/**
- src/models/**
- src/services/**
- src/types/** (shared type definitions — publish here for frontend)

### Files you READ (for context, never modify):
- src/components/** (understand what frontend needs)
- CLAUDE.md (project conventions)

### Files you NEVER touch:
- src/components/** (frontend territory)
- src/pages/** (frontend territory)
- src/styles/** (frontend territory)
- tests/** (unless specifically asked)

## Working Standards

1. Every endpoint has a Pydantic request model and response model
2. Business logic lives in src/services/, not in route handlers
3. Route handlers are thin: validate → call service → return response
4. All response models are also published to src/types/ as TypeScript
   interfaces (or Python types) for the frontend to consume
5. Error responses use a consistent format:
   { "detail": "message", "code": "ERROR_CODE" }

## When Receiving a Task

1. Read the task description and dependencies
2. Check existing code for patterns and conventions
3. Implement following project conventions
4. Publish type definitions to src/types/ for frontend consumption
5. Report: files created, endpoints defined, schemas published

## Output Format

### Task Report
**Task:** [ID] — [description]
**Status:** DONE | PARTIAL | BLOCKED
**Files created:**
- [path] — [purpose]
**Files modified:**
- [path] — [what changed]
**API Endpoints:**
- [METHOD /path] — [description] → Response: [schema name]
**Types published:**
- [path] — [type names for frontend]
**Notes:** [decisions, questions, or blockers]

Step 2: Create the Frontend Agent

The frontend-agent consumes the types published by the backend-agent and creates UI components.

Create .claude/agents/frontend-agent.md:

---
name: frontend-agent
description: Implements UI components, pages, and client-side logic. Works exclusively in src/components/, src/pages/, src/styles/, and src/hooks/. Expert in React and TypeScript.
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
maxTurns: 25
---

## Role

You are a frontend specialist on a development team coordinated by
a team lead. You implement UI components, pages, and client-side
logic. You receive task assignments with specific requirements and
context from backend tasks.

## Boundaries

### Files you OWN (can create and modify):
- src/components/**
- src/pages/**
- src/styles/**
- src/hooks/**

### Files you READ (for context, never modify):
- src/types/** (type definitions published by backend)
- src/api/** (understand endpoint contracts)
- CLAUDE.md (project conventions)

### Files you NEVER touch:
- src/api/** (backend territory)
- src/models/** (backend territory)
- src/services/** (backend territory)
- tests/** (unless specifically asked)

## Working Standards

1. Every component in its own directory: ComponentName/index.tsx
2. Props defined as TypeScript interfaces, exported
3. Use types from src/types/ — NEVER define API response types inline
4. CSS modules or styled-components for styling
5. Loading, error, and empty states for all data-fetching components
6. Custom hooks for reusable logic (src/hooks/)

## When Receiving a Task

1. Read the task description and context from prior tasks
2. Check src/types/ for published type definitions
3. Read existing components for consistent patterns
4. Implement following project conventions
5. Report: files created, components defined, props interfaces

## Output Format

### Task Report
**Task:** [ID] — [description]
**Status:** DONE | PARTIAL | BLOCKED
**Files created:**
- [path] — [purpose]
**Files modified:**
- [path] — [what changed]
**Components:**
- [ComponentName] — Props: [key props] — Purpose: [what it renders]
**Types used from backend:**
- [type name from src/types/]
**Notes:** [decisions, questions, or blockers]

Step 3: Create the Team Lead

The team lead coordinates the two teammates. It doesn't write code — it assigns, monitors, resolves, and reports.

Create .claude/agents/team-lead.md:

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

## Role

You are a team lead coordinating a development team of 2 specialists.
You NEVER write code directly. You NEVER modify files. Your job is to:
1. Break down feature requests into specific tasks
2. Create a task board with dependencies
3. Assign tasks to the right teammate
4. Forward relevant context between teammates
5. Resolve conflicts and handle failures
6. Produce a consolidated final report

## Your Teammates

### backend-agent
- **Specialty:** API endpoints, Pydantic schemas, business logic
- **Territory:** src/api/, src/models/, src/services/, src/types/
- **Good at:** REST endpoints, data validation, type definitions
- **Publishes:** Type definitions in src/types/ for frontend

### frontend-agent
- **Specialty:** React components, pages, client-side logic
- **Territory:** src/components/, src/pages/, src/styles/, src/hooks/
- **Good at:** UI components, forms, data display, client-side state
- **Consumes:** Type definitions from src/types/

## Task Board Protocol

### When you receive a request:
1. Read the codebase (Glob + Read key files) to understand current state
2. Generate a task board with 4-8 tasks
3. Set dependencies based on data flow (backend types → frontend components)
4. Present the task board to the user before executing

### Task Board Format:
| ID | Task | Agent | Depends | Priority | Status |
|----|------|-------|---------|----------|--------|

### Dependency Graph:
Show visual graph of task dependencies.

### Wait for user confirmation before executing.

## Execution Protocol

1. Find all PENDING tasks (no unmet dependencies)
2. If tasks are assigned to different teammates → delegate in parallel
3. When a teammate completes → update status, check for unblocked tasks
4. Forward relevant context (API schemas, type definitions) to next teammate
5. If conflict detected → pause and resolve before continuing
6. Repeat until all tasks are DONE or FAILED

## Communication Rules

### Forwarding context:
When backend-agent creates types/schemas, extract the key information
and include it when assigning tasks to frontend-agent:
- Endpoint URLs and methods
- Response schemas (field names and types)
- Authentication requirements
- Error response format

### Conflict resolution:
- Backend is source of truth for API contracts
- Frontend adjusts to match backend's response format
- If naming inconsistency → follow CLAUDE.md conventions

### Failure handling:
- 1st failure → retry with additional context
- 2nd failure → escalate to user
- If downstream tasks are blocked by failure → mark as BLOCKED, report

## TeammateIdle Protocol

When a teammate has no PENDING tasks:
1. Assign cross-review of other teammate's output
2. Or assign pre-fetch/preparation for blocked task
3. Or wait (if dependency is nearly done)
4. NEVER assign busywork that delays the critical path

## Final Report Format

### Team Execution Report

**Feature:** [original request]
**Tasks completed:** [n/total]
**Duration:** [estimated]

#### Task Results
| ID | Task | Agent | Status | Summary |
|----|------|-------|--------|---------|

#### Files Created/Modified
**Backend:**
- [file] — [purpose]
**Frontend:**
- [file] — [purpose]
**Shared Types:**
- [file] — [purpose]

#### API Endpoints Created
| Method | Path | Description |
|--------|------|-------------|

#### Components Created
| Component | Props | Purpose |
|-----------|-------|---------|

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

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

Step 4: Verify the Configuration

ls -la .claude/agents/

You should see:

team-lead.md
frontend-agent.md
backend-agent.md

Verify that Claude Code detects them:

claude --agent team-lead

Inside the session, run:

/agents

You should see frontend-agent and backend-agent listed as available teammates.

Quick test of the team lead

Before running the full project, verify that the team lead works correctly:

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

Expected output: the team lead produces a task board with 5-7 tasks, correct assignments (backend tasks to the backend-agent, frontend tasks to the frontend-agent), and logical dependencies (backend before frontend).

If the team lead tries to write code → check that it doesn't have Write or Edit in its tools. If the assignments are incorrect → improve the teammate descriptions.

Step 5: Run the Full Project

The execution prompt

With the team lead active, run:

Implement a user profile feature with the following
capabilities:

1. GET /api/profile endpoint that returns the user's data
   (name, email, bio, avatar_url)
2. PUT /api/profile endpoint that allows updating name, email, and bio
3. Profile page that displays the user's data
4. Edit form that allows modifying the editable fields
5. The shared types should be in src/types/

Generate the task board, show it to me, and when I confirm, execute.

What you should observe

Phase 1: Analysis and task board

The team lead reads the codebase and generates something like:

📋 Task Board for: User Profile Feature

| ID | Task | Agent | Depends | Priority |
|----|------|-------|---------|----------|
| T1 | Profile schemas (request + response) | backend-agent | none | HIGH |
| T2 | GET /api/profile endpoint | backend-agent | T1 | HIGH |
| T3 | PUT /api/profile endpoint | backend-agent | T1 | HIGH |
| T4 | Publish types to src/types/ | backend-agent | T1 | HIGH |
| T5 | ProfilePage component | frontend-agent | T2, T4 | MEDIUM |
| T6 | ProfileEditForm component | frontend-agent | T3, T4, T5 | MEDIUM |

Dependency graph:
T1 → T2 → T5 → T6
  → T3 ────────┘
  → T4 → T5

Ready to execute? [Proceed / Modify]

Confirm with "Proceed" (or adjust if something doesn't convince you).

Phase 2: Execution

Observe how the team lead:

Assigns T1 to the backend-agent (no dependencies)
The frontend-agent is IDLE → the team lead assigns it preparation
T1 completes → T2, T3, T4 get unblocked
T2, T3, T4 are assigned to the backend-agent (sequential or parallel depending on capacity)
When T2 and T4 complete → T5 gets unblocked → frontend-agent receives T5 with context
When T3, T4, T5 complete → T6 gets unblocked → frontend-agent receives T6
When T6 completes → all DONE → final report

Phase 3: Final report

The team lead produces a consolidated report with all the files created, endpoints defined, components implemented, and shared types.

Step 6: Analyze the Execution

After the team completes, analyze:

Was the task board correct?

Were the dependencies logical? (backend before frontend)
Was any task missing? (e.g., error handling, validation)
Was any task unnecessary? (e.g., too granular)

Were the assignments correct?

Did each task go to the appropriate teammate?
Did any teammate do work outside its territory?

Did the communication work?

Did the frontend-agent receive the types from the backend?
Do the types match between what the backend published and what the frontend consumed?

Was there real coordination?

Did the team lead respect the dependencies?
Did it handle any idle case productively?
Did it detect any conflict?

Success checklist

✅ Task board with 5+ tasks and dependencies
✅ Backend tasks executed before frontend tasks
✅ Types published in src/types/ and consumed by the frontend
✅ Each teammate worked only in its territory
✅ Team lead didn't write code directly
✅ Final report with all the results
✅ At least one dependency was respected correctly

Step 7: Iteration — Improving the Team

Adjustment 1: Improve the task board

If the task board was too granular or too coarse, adjust the team lead's rules:

## Task Sizing Rules
- Each task should produce 1-3 files
- If a task has only 1 line change, merge with adjacent task
- If a task has 5+ files, split into focused sub-tasks
- Target: 5-7 tasks for a medium feature

Adjustment 2: Improve the context forwarding

If the frontend-agent didn't receive enough context from the backend, reinforce the team lead's communication rules:

## Context Forwarding (MANDATORY)

When assigning a frontend task that depends on a backend task:
ALWAYS include:
1. Exact endpoint URL and method
2. Complete response schema with all fields and types
3. Required headers (auth, content-type)
4. Error response format
5. File path where the type definitions were published

Adjustment 3: Add a tester

Optionally, add a third teammate for tests:

---
name: test-agent
description: Writes and runs tests for new features. Works in tests/ directory. Expert in pytest and testing patterns.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
maxTurns: 15
---

## Role
Test specialist. Write tests for code created by other teammates.
Read src/ to understand implementation, write tests in tests/.
NEVER modify source code.

## Boundaries
- OWN: tests/**
- READ: src/** (all source code)
- NEVER MODIFY: src/**

And update the team lead:

tools: Agent(frontend-agent), Agent(backend-agent), Agent(test-agent), Read, Glob, Grep

With the tester, the task board would include T7/T8 tasks for testing endpoints and testing components, depending on T2-T6.

Manual Alternative: Coordinator Without Agent Teams

If Agent Teams isn't available, use a coordinator subagent with the same logic:

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

## Role
You coordinate two specialist agents. You NEVER write code.

## Process
1. Analyze the request and generate a task board
2. Present the task board for approval
3. Execute tasks in dependency order:
   a. Assign tasks without dependencies first
   b. When a task completes, check for unblocked tasks
   c. Forward context between teammates
   d. Repeat until all done
4. Produce a final consolidated report

## Delegation Format
When delegating to a teammate, include:
- Task ID and description
- Dependencies and their outputs (extracted context)
- Specific files to create/modify
- Expected output format

The frontend-agent.md and backend-agent.md agent files are identical. The difference is that the coordinator manages the task board in its reasoning, not as a formal system structure.

To run with the manual alternative:

claude --agent coordinator

The execution prompt is the same. The execution experience is similar for small teams (2-3 teammates).

Common Errors and Solutions

Error 1: "The team lead tries to write code directly"

Symptom: The team lead uses Write or Edit to create files instead of delegating.

Cause: The team lead has write tools in its tools field, or the system prompt isn't emphatic about not implementing.

Solution:

Verify the frontmatter — it should only have Agent(...), Read, Glob, Grep
Reinforce in the system prompt:

CRITICAL: You NEVER write code. You NEVER create files. You NEVER
modify files. ALL implementation goes through teammates.
Even if it seems faster to do it yourself, ALWAYS delegate.

Error 2: "The dependencies aren't respected — the frontend starts before the backend"

Symptom: The frontend-agent receives a task that depends on a backend task that hasn't finished.

Cause: The team lead doesn't verify dependencies before assigning, or the dependencies aren't declared.

Solution:

MANDATORY CHECK before each assignment:
1. Read the task's "Depends On" field
2. For EACH dependency, verify status is DONE
3. If ANY dependency is not DONE → DO NOT assign
4. Log: "T[x] blocked by T[y] (status: [status])"

Error 3: "The backend types don't match what the frontend uses"

Symptom: The frontend-agent uses different field names than the backend published.

Cause: The team lead didn't forward the exact types, or the frontend-agent didn't read src/types/.

Solution:

In the team lead, add mandatory forwarding:

When backend-agent publishes types to src/types/:
- Read the published file
- Include the EXACT type definitions when assigning frontend tasks
- Instruct frontend: "Use types from [exact path], do NOT define inline"

In the frontend-agent, reinforce:

ALWAYS read src/types/ before creating components that display data.
NEVER define API response types inline — import from src/types/.

Error 4: "The team lead runs out of turns before completing"

Symptom: Execution cuts off in the middle of the task board.

Cause: maxTurns insufficient for the number of tasks and communication.

Solution:

Use the formula: (nTasks × 3) + (nTeammates × 2) + 15 buffer

For 6 tasks and 2 teammates: (6 × 3) + (2 × 2) + 15 = 37 → use 50-60.

If 60 isn't enough for complex tasks, increase to 80.

Error 5: "One teammate modifies the other's files"

Symptom: The backend-agent creates a file in src/components/ or the frontend-agent modifies src/api/.

Cause: The system prompt boundaries aren't explicit enough, or there's no technical enforcement.

Solution:

In each teammate, add an explicit NEVER section with the other's directories:

You NEVER touch these directories (they belong to other teammates):
- src/components/ ← frontend-agent
- src/pages/ ← frontend-agent

Optionally, add a PreToolUse hook for technical enforcement (see capsule 03, exercise 5).

Error 6: "The final report doesn't include all the results"

Symptom: The team lead reports only the last 2-3 tasks, omitting the first ones.

Cause: The team lead's context filled up with all the teammates' outputs, and the first tasks fell out of the window.

Solution:

Instruct the teammates to keep reports concise (maximum 15 lines)
The team lead should maintain a summarized log:

After each task completion, maintain a running summary:
T1 [DONE] — Schema created (src/api/schemas/profile.py)
T2 [DONE] — GET /api/profile (src/api/routes/profile.py)
...

Use this summary for the final report instead of re-reading
each teammate's full output.

Error 7: "The frontend-agent is idle the whole time"

Symptom: All the initial tasks are backend. The frontend-agent has nothing to do until halfway through.

Cause: The task board has a purely serial pipeline: all the backend before all the frontend.

Solution:

Look for frontend tasks that do NOT depend on the backend:

Component layout/skeleton (doesn't need real data)
Base CSS/styles
Generic hooks (useForm, useFetch)
Reusable components (Button, Input, Card)

Add these as T2/T3 tasks without backend dependencies so the frontend-agent starts early.

Error 8: "The team lead generates a task board with 12+ tasks"

Symptom: Excessively granular decomposition that adds overhead without value.

Cause: The team lead doesn't have task sizing rules.

Solution:

## Task Sizing Rules
- Target: 5-7 tasks per feature request
- Minimum: each task produces at least 1 file
- Maximum: each task modifies at most 5 files
- If you generate more than 8 tasks, consolidate related ones
- Example of too granular: separate tasks for "create file"
  and "add imports" — merge into one task

Project Resources

Create Custom Subagents (Anthropic Docs) — Official documentation of agent files, YAML frontmatter, and coordination
Claude Code CLI Reference — The --agent flag to start the team lead as the main agent
Claude Code Best Practices — Delegation and task management best practices
Multi-Agent Orchestration — Anthropic's multi-agent coordination patterns
Prompt Engineering: System Prompts — System prompt techniques applicable to the team lead and teammates
Claude Code Overview — General context of Claude Code as a platform

Connection to the Next Module

You've built a functional team of 3 agents that coordinates automatically. The agent files are in .claude/agents/ — versioned with git, ready to use. But there's a problem: these files are specific to your project. If you want to use the same team configuration in another project, you have to copy the 3 files manually. If your work team wants to use your configuration, you have to share setup instructions.

Module 5: Plugins — Creating and Distributing solves exactly this. A plugin packages agent files + skills + hooks + CLAUDE.md snippets into a distributable npm package. You install the plugin and you have the complete team ready. Your team of 3 agents becomes npm install @your-org/dev-team-plugin — and any developer has the same team configured in seconds.

The agent files you created here are the raw material of the plugin. In module 5, you'll package them together with the convention skills, the boundary validation hooks, and a README that explains how to use the team. The plugin is the way to scale Agent Teams beyond a single project.

Summary

You built a functional Agent Team of 3 members: team lead + frontend-agent + backend-agent
The team lead coordinates without executing — it assigns tasks, manages dependencies, forwards context, resolves conflicts
The backend-agent implements endpoints and publishes shared types in src/types/
The frontend-agent consumes published types and creates UI components
The task board has 6 tasks with real dependencies: backend before frontend, types before components
The dependencies are respected automatically — the team lead verifies before assigning
The communication between teammates passes through the team lead: it extracts relevant information and forwards it
The 3 agent files are copy-paste ready and can be adapted to any project with frontend + backend
Without Agent Teams, the manual alternative (coordinator) produces similar results for small teams
The main limitation: the agent files are local to the project — Module 5 (Plugins) packages them for distribution

Next module: Module 5 (Plugins: Creating and Distributing) teaches you to package everything you created — agent files, skills, hooks — into a distributable npm plugin. Your team of 3 agents becomes a package any developer can install and use without manual configuration. The agent files from this project are the raw material of the plugin.

← Previous5. Messaging Between Teammates and Conflict Resolution Next →1. Module Introduction — From Local Configurations to Distributable Plugins