1.5: Agent Teams

Key Terms

• Agent Team: Multiple AI agents coordinated by a lead agent
• Team Lead: The orchestrating agent that spawns and coordinates teammates
• Teammate: Independent agent working on assigned tasks
• Task List: Shared work items that teammates claim and complete
• Delegate Mode: Lead restricted to coordination-only tools
• Subagent: Helper agent that reports back to parent (compare with teammate)

Learning Objectives

After completing this chapter, you will be able to:

• Determine when Agent Teams are appropriate versus single agents or subagents
• Design team structures with appropriate roles and responsibilities
• Coordinate parallel work using shared task lists
• Integrate Agent Teams into ASPICE process workflows
• Apply best practices for multi-agent collaboration

29.05.1 Introduction

When a single AI agent is not enough, you build a team.

Agent Teams represent a paradigm shift from single-agent workflows to coordinated multi-agent collaboration. Unlike subagents that report back to a parent, teammates in an Agent Team:

• Communicate directly with each other
• Share a task list for self-coordination
• Work in independent context windows
• Can challenge and synthesize each other's findings

This chapter covers team architecture, role definitions, coordination patterns, and ASPICE integration.

29.05.2 When to Use Agent Teams

Agent Teams excel when parallel exploration adds real value to the task.

Research and Review

Multiple teammates investigate different aspects simultaneously, then share and challenge findings.

Example: Parallel Code Review

Lead spawns three reviewers:
├── Security Reviewer → authentication, input validation, secrets
├── Performance Reviewer → algorithms, memory, latency
└── Test Coverage Reviewer → edge cases, missing tests

New Modules or Features

Teammates each own a separate piece without stepping on each other.

Example: Cross-Layer Feature Development

Lead coordinates:
├── Frontend Agent → UI components, user interactions
├── Backend Agent → API endpoints, business logic
├── Test Agent → integration tests, E2E scenarios
└── Docs Agent → API documentation, user guides

Debugging with Competing Hypotheses

Teammates test different theories in parallel and converge faster.

Example: Root Cause Investigation

Lead spawns investigators:
├── Theory A: Memory leak in connection pool
├── Theory B: Race condition in async handler
├── Theory C: External service timeout
└── Theory D: Configuration drift

Investigators actively try to disprove each other's theories. The theory that survives is more likely to be the actual root cause.

When NOT to Use Teams

Agent Teams add coordination overhead and use significantly more tokens. Avoid them for:

• Sequential tasks with dependencies
• Same-file edits (causes conflicts)
• Simple, focused work one agent handles easily
• Tasks where discussion overhead exceeds benefit

29.05.3 Team Architecture

Core Components

Architecture Diagram

The following diagram shows the multi-agent team structure, including the lead agent, specialist teammates, shared context, and communication patterns between agents.

Context and Communication

Each teammate has its own context window (the maximum amount of text the model processes at once). When spawned:

• Loads project context (CLAUDE.md — the project configuration file, MCP servers — Model Context Protocol servers that give agents access to tools and external systems, skills — reusable task scripts defined in .claude/skills/)
• Receives spawn prompt from lead
• Does NOT inherit lead's conversation history

Communication happens through:

• Direct messages: One teammate to another
• Broadcast: Lead to all teammates (use sparingly)
• Task list updates: Visible to entire team
• Idle notifications: Automatic when teammate finishes

29.05.4 Team Roles

The Lead

The lead orchestrates the team but doesn't necessarily do the work.

Responsibilities:

• Break down work into parallelizable tasks
• Spawn appropriate teammates with clear prompts
• Monitor progress and redirect when needed
• Synthesize findings from multiple teammates
• Clean up team when finished

Delegate Mode: Restricts lead to coordination-only tools. Use when you want pure orchestration without the lead touching code.

Specialist Roles

The Challenger Role

The Challenger (Devil's Advocate) explicitly looks for problems:

Spawn a challenger teammate with the prompt:
"Your job is to find holes in the team's approach. 
Challenge assumptions, identify risks, and propose 
alternatives. Be constructive but thorough."

This prevents groupthink and catches issues early.

29.05.5 Task Coordination

Shared Task List

Tasks have three states:

• Pending: Not yet started
• In Progress: Claimed by a teammate
• Completed: Finished

Tasks can depend on other tasks. A pending task with unresolved dependencies cannot be claimed until those dependencies complete.

Task Assignment Patterns

Lead Assigns:

"Assign the authentication refactor to the Security teammate"

Self-Claim: After finishing a task, teammates automatically pick up the next unassigned, unblocked task.

Dependency Management:

Task: Implement API endpoints
  └── Depends on: Define API schema (must complete first)

Task: Write integration tests
  └── Depends on: Implement API endpoints

Avoiding Conflicts

Critical Rule: Never have two teammates edit the same file simultaneously.

Break work so each teammate owns different files:

✅ Good:
├── Teammate A → src/auth/*.py
├── Teammate B → src/api/*.py
└── Teammate C → tests/*.py

❌ Bad:
├── Teammate A → Fix bug in main.py
├── Teammate B → Add feature to main.py  ← CONFLICT

29.05.6 ASPICE Process Integration

Agent Teams map naturally to ASPICE work products and parallel activities.

System Engineering (SYS)

Software Engineering (SWE)

Verification (SUP.2)

Perfect for Agent Teams:

Lead: "Review PR #142 for ASPICE compliance"
├── Requirements Reviewer → Traceability complete?
├── Design Reviewer → Architecture alignment?
├── Code Reviewer → MISRA compliance?
├── Test Reviewer → Coverage adequate?
└── Documentation Reviewer → Work products complete?

29.05.7 Comparison with Subagents

Use Subagents when:

• Task is focused and results just need to come back
• No inter-agent discussion needed
• Token efficiency matters

Use Agent Teams when:

• Teammates need to share findings
• Work benefits from debate and challenge
• Tasks are complex enough to warrant coordination overhead

29.05.8 Best Practices

Give Teammates Enough Context

Teammates don't inherit the lead's conversation. Include details in spawn prompts:

"Review the authentication module at src/auth/ for security 
vulnerabilities. Focus on token handling, session management, 
and input validation. The app uses JWT tokens stored in 
httpOnly cookies. Report issues with severity ratings."

Size Tasks Appropriately

Monitor and Steer

Don't let teams run unattended too long:

• Check progress regularly
• Redirect approaches that aren't working
• Synthesize findings as they come in

Start with Research

New to Agent Teams? Start with non-code tasks:

• PR reviews
• Architecture research
• Bug investigation
• Documentation review

29.05.9 Quality Gates with Hooks

Hooks are Python scripts that the agent framework runs automatically at defined lifecycle events. They act as enforcement checkpoints — a hook that exits with code 2 sends feedback to the agent and keeps it working rather than letting it finish. Place hook scripts in your project's hooks/ directory and register them in your agent configuration.

Enforce rules when teammates finish:

TeammateIdle Hook

Runs when a teammate is about to go idle:

# hooks/teammate_idle.py
if not all_tests_pass():
    print("Tests failing - fix before finishing")
    sys.exit(2)  # Exit code 2 = send feedback, keep working

TaskCompleted Hook

Runs when a task is being marked complete:

# hooks/task_completed.py
if coverage < 80:
    print("Coverage below 80% - add more tests")
    sys.exit(2)  # Exit code 2 = prevent completion

29.05.10 Token Considerations

Agent Teams use significantly more tokens than single sessions:

• Each teammate has its own context window
• Token usage scales with number of active teammates
• Broadcast messages multiply by team size

When it's worth it:

• Research and review (parallel exploration valuable)
• Complex debugging (faster convergence)
• Large features (true parallelism)

When it's not worth it:

• Routine tasks
• Sequential dependencies
• Simple, focused work

29.05.11 Limitations

Current limitations to be aware of:

1. No session resumption: Can't restore teammates after resume
2. Task status lag: Teammates may forget to mark tasks complete
3. Slow shutdown: Teammates finish current work before exiting
4. One team per session: Clean up before starting new team
5. No nested teams: Teammates can't spawn their own teams
6. Fixed lead: Can't transfer leadership
7. Permissions at spawn: All teammates start with lead's permissions

Self-Assessment Quiz

Test your understanding of Agent Teams:

Question 1: When should you use Agent Teams instead of subagents?

A) When you need quick, focused results
B) When teammates need to discuss and challenge each other
C) When token efficiency is the priority
D) When tasks are sequential

Question 2: What is the primary role of the Team Lead?

A) Write all the code
B) Coordinate work and synthesize results
C) Review every teammate's output in detail
D) Run tests

Question 3: How should you prevent file conflicts in Agent Teams?

A) Use file locking
B) Have teammates work on different files
C) Let the lead resolve conflicts
D) Merge frequently

Question 4: What does "delegate mode" do for the Team Lead?

A) Gives the lead more permissions
B) Restricts lead to coordination-only tools
C) Automatically assigns all tasks
D) Enables faster communication

Summary

Agent Teams enable parallel AI collaboration for complex tasks:

• Lead coordinates, teammates execute independently
• Shared task list enables self-coordination
• Direct messaging allows inter-agent discussion
• Best for research, review, debugging, and parallel features
• Avoid for sequential tasks or same-file edits
• Higher token cost but faster results for suitable tasks

The key insight: Agent Teams are not just about parallelism — they enable AI agents to debate, challenge, and synthesize results the way human teams do.

References

• Claude Code Documentation: Agent Teams
• Chapter 29.00: Agent Framework
• Chapter 29.01: Agent Roles and Responsibilities
• Chapter 30.00: Process Execution Instructions