# Agent Teams Development

> Use when executing implementation plans that benefit from coordinated multi-agent teams with defined roles — complex multi-phase tasks, cross-cutting concerns, or work requiring persistent shared context between agents

- Skill: `aws-sbg-at-the-university-of-kentucky/agent-teams-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aws-sbg-at-the-university-of-kentucky/agent-teams-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-sbg-at-the-university-of-kentucky/agent-teams-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: AWS-SBG-at-the-University-of-Kentucky (https://skillmd.com/u/aws-sbg-at-the-university-of-kentucky)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aws-sbg-at-the-university-of-kentucky/agent-teams-development

---


# Agent Teams Development

Execute implementation plans using Claude Code's team infrastructure (`TeamCreate`, `Agent`, `SendMessage`, `Task*` tools) with role-based agents that coordinate through a shared task list and messaging.

**Why teams over subagents:** Teams maintain persistent agents that can message each other, share context through an archivist, and coordinate through a task list. Subagent-driven development dispatches fresh, isolated agents per task. Teams are better when tasks have cross-cutting concerns, shared state, or benefit from persistent reviewer/context agents across the full implementation.

**Core principle:** Defined roles + shared task list + persistent agents = coordinated execution for complex plans.

**Announce at start:** "I'm using the agent-teams-development skill to execute this plan with a coordinated team."

## When to Use

```dot
digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Multiple phases or cross-cutting concerns?" [shape=diamond];
    "Need persistent shared context?" [shape=diamond];
    "agent-teams-development" [shape=box];
    "subagent-driven-development" [shape=box];

    "Have implementation plan?" -> "Multiple phases or cross-cutting concerns?" [label="yes"];
    "Have implementation plan?" -> "subagent-driven-development" [label="no"];
    "Multiple phases or cross-cutting concerns?" -> "agent-teams-development" [label="yes"];
    "Multiple phases or cross-cutting concerns?" -> "Need persistent shared context?" [label="no"];
    "Need persistent shared context?" -> "agent-teams-development" [label="yes"];
    "Need persistent shared context?" -> "subagent-driven-development" [label="no"];
}
```

**Use when:**
- Plan has 5+ tasks with dependencies or shared concerns
- Multiple subsystems need coordinated changes
- Quality review needs full-project context (not just per-task)
- Decisions in early tasks affect later tasks (archivist tracks these)

**Don't use when:**
- Tasks are fully independent (subagent-driven is simpler and faster)
- Small plans (< 4 tasks) — team overhead not worth it
- Single-subsystem changes

## Core Agent Roles

### 1. Orchestrator — The Coordinator

Receives the user's goal, decomposes into subtasks, delegates to specialists, synthesizes the final result. Has broad context but does NOT do deep implementation work.

**Implementation:** This is YOU (the main Claude session). You:
- Read the plan and create the team via `TeamCreate`
- Spawn teammates via `Agent` with `team_name` and `name` parameters
- Create tasks via `TaskCreate` and assign with `TaskUpdate`
- Coordinate via `SendMessage` when teammates need guidance
- Synthesize results and report to the user

### 2. Specialist — The Worker

Receives a narrow, well-defined task from the orchestrator. Has access to specific tools (code, search, execution). Keeps a minimal context window. Returns a structured result.

**Implementation:** Spawned via `Agent` tool with:
- `subagent_type`: `"general-purpose"` (for implementation) or domain-specific type
- `team_name`: the team name
- `name`: descriptive name (e.g., `"api-specialist"`, `"ui-specialist"`)
- `model`: match to task complexity (haiku for mechanical, sonnet for integration, opus for architecture)

**Use when:** You need parallelism, isolation, or domain-specific expertise (e.g., "a search agent" or a "summarizer agent").

### 3. Quality Gate — The Critic/Reviewer

Receives a draft output and evaluates it against a rubric or set of criteria. Returns structured feedback or a pass/fail signal that the orchestrator can act on.

**Implementation:** Spawned via `Agent` tool with:
- `subagent_type`: `"code-reviewer"` or `"security-reviewer"`
- `team_name`: the team name
- `name`: `"quality-gate"`
- Prompt includes: the spec/rubric, what to evaluate, expected output format

**Use when:** Output quality is critical and you can define what "good" looks like in advance.

### 4. Archivist — Memory/Context Keeper

Maintains a persistent store of facts, decisions, or user preferences. Other agents query it rather than passing long context between calls. Reduces lost context and keeps agents focused.

**Implementation:** Spawned via `Agent` tool with:
- `subagent_type`: `"general-purpose"`
- `team_name`: the team name
- `name`: `"archivist"`
- Prompt: "You maintain shared context for this team. When teammates message you with decisions, patterns, or important context, record them. When teammates ask for context, provide relevant information."
- The archivist writes to a shared context file (e.g., `docs/superpowers/team-context.md`) that other agents can read

**Use when:** The pipeline spans multiple tasks and agents need shared state (e.g., "we decided to use pattern X in task 2, task 5 needs to know").

### 5. Traffic Director — The Router/Dispatcher

Classifies an incoming request and routes it to the correct specialist agent or workflow. Lightweight — its only job is a routing decision, not producing content.

**Implementation:** Used by the orchestrator as a decision pattern, not necessarily a separate agent. When the plan has mixed task types (frontend, backend, testing, docs), the orchestrator routes each task to the appropriate specialist type:
- Frontend tasks → specialist with `subagent_type: "frontend-engineer"`
- Backend tasks → specialist with `subagent_type: "backend-engineer"`
- Review tasks → quality gate with `subagent_type: "code-reviewer"`
- Security tasks → quality gate with `subagent_type: "security-reviewer"`

**Use when:** Multiple distinct task types arrive and need routing to different specialists.

### 6. Planner/Executor Split — Two-Stage Decomposition

A planner agent produces a step-by-step plan (JSON or markdown). A separate executor agent carries each step out, one at a time, using tools. Separates reasoning from action.

**Implementation:** When a task is complex enough to warrant sub-planning:
1. Spawn a Plan agent (`subagent_type: "Plan"`) to break the task into micro-steps
2. Spawn an executor agent (`subagent_type: "general-purpose"`) to execute each step
3. The planner does NOT execute; the executor does NOT plan

**Use when:** Tasks involve long action sequences where the plan itself is worth reviewing before execution.

## The Process

```dot
digraph process {
    rankdir=TB;

    "Read plan file" [shape=box];
    "Create team (TeamCreate)" [shape=box];
    "Spawn persistent agents (Quality Gate, Archivist)" [shape=box];
    "Create all tasks (TaskCreate)" [shape=box];

    subgraph cluster_per_task {
        label="Per Task (or parallel batch)";
        "Route task to specialist type (Traffic Director pattern)" [shape=box];
        "Spawn specialist with task assignment" [shape=box];
        "Specialist implements, tests, commits" [shape=box];
        "Specialist notifies orchestrator" [shape=box];
        "Send to Quality Gate for review" [shape=box];
        "Quality Gate approves?" [shape=diamond];
        "Specialist fixes issues" [shape=box];
        "Notify Archivist of decisions/patterns" [shape=box];
        "Mark task complete (TaskUpdate)" [shape=box];
    }

    "More tasks?" [shape=diamond];
    "Final review (Quality Gate reviews full implementation)" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan file" -> "Create team (TeamCreate)";
    "Create team (TeamCreate)" -> "Spawn persistent agents (Quality Gate, Archivist)";
    "Spawn persistent agents (Quality Gate, Archivist)" -> "Create all tasks (TaskCreate)";
    "Create all tasks (TaskCreate)" -> "Route task to specialist type (Traffic Director pattern)";
    "Route task to specialist type (Traffic Director pattern)" -> "Spawn specialist with task assignment";
    "Spawn specialist with task assignment" -> "Specialist implements, tests, commits";
    "Specialist implements, tests, commits" -> "Specialist notifies orchestrator";
    "Specialist notifies orchestrator" -> "Send to Quality Gate for review";
    "Send to Quality Gate for review" -> "Quality Gate approves?";
    "Quality Gate approves?" -> "Specialist fixes issues" [label="no"];
    "Specialist fixes issues" -> "Send to Quality Gate for review";
    "Quality Gate approves?" -> "Notify Archivist of decisions/patterns" [label="yes"];
    "Notify Archivist of decisions/patterns" -> "Mark task complete (TaskUpdate)";
    "Mark task complete (TaskUpdate)" -> "More tasks?";
    "More tasks?" -> "Route task to specialist type (Traffic Director pattern)" [label="yes"];
    "More tasks?" -> "Final review (Quality Gate reviews full implementation)" [label="no"];
    "Final review (Quality Gate reviews full implementation)" -> "Use superpowers:finishing-a-development-branch";
}
```

## Step-by-Step

### Step 1: Setup

1. Read the plan file
2. Create team: `TeamCreate({ team_name: "<feature-name>", description: "<goal>" })`
3. Spawn persistent agents:
   - **Quality Gate**: `Agent({ name: "quality-gate", team_name: "<name>", subagent_type: "code-reviewer", prompt: "..." })`
   - **Archivist**: `Agent({ name: "archivist", team_name: "<name>", subagent_type: "general-purpose", prompt: "..." })`
4. Create all tasks from plan via `TaskCreate`

### Step 2: Execute Tasks

For each task (or parallel batch of independent tasks):

1. **Route** — Determine specialist type based on task domain
2. **Spawn specialist** — `Agent({ name: "task-N-specialist", team_name: "<name>", subagent_type: "<type>", prompt: "<full task text + context>" })`
3. **Wait for completion** — Specialist implements, tests, commits, then messages orchestrator
4. **Quality Gate review** — `SendMessage({ to: "quality-gate", message: "Review task N: <what changed, spec to check against>" })`
5. **Handle feedback** — If Quality Gate flags issues, send fixes back to specialist (or spawn fix agent)
6. **Update Archivist** — `SendMessage({ to: "archivist", message: "Task N decided: <key decisions, patterns, context for later tasks>" })`
7. **Mark complete** — `TaskUpdate({ id: N, status: "completed" })`

### Step 3: Final Review

After all tasks:
1. Quality Gate reviews the full implementation against the original plan
2. Address any cross-cutting issues found
3. **REQUIRED SUB-SKILL:** Use `superpowers:finishing-a-development-branch`

## Model Selection

Same principle as subagent-driven-development — use the least powerful model that handles each role:

| Role | Model | Why |
|------|-------|-----|
| Orchestrator | opus | Broad coordination, synthesis |
| Specialist (mechanical) | haiku | Isolated, clear spec, 1-2 files |
| Specialist (integration) | sonnet | Multi-file, judgment needed |
| Quality Gate | sonnet | Pattern recognition, rubric evaluation |
| Archivist | haiku | Simple storage and retrieval |
| Traffic Director | (orchestrator) | Routing logic, not a separate agent |

## vs. Subagent-Driven Development

| Aspect | Subagent-Driven | Agent Teams |
|--------|----------------|-------------|
| Agent lifetime | Fresh per task | Persistent across tasks |
| Context sharing | None (by design) | Via Archivist |
| Review scope | Per-task only | Per-task + cross-cutting |
| Coordination | Sequential dispatch | Message-based collaboration |
| Overhead | Low | Higher (team setup, messaging) |
| Best for | Independent tasks | Interdependent, multi-phase work |

## Red Flags

**Never:**
- Start implementation on main/master branch without explicit user consent
- Let the orchestrator do deep implementation work (delegate to specialists)
- Skip Quality Gate reviews
- Spawn too many specialists in parallel on the same files (conflicts)
- Let agents communicate outside of `SendMessage` (no shared mutable state except through Archivist)
- Forget to shut down the team when done (`SendMessage` with `{type: "shutdown_request"}`)

**If a specialist is blocked:**
- Provide context via `SendMessage`
- Escalate to a more capable model if needed
- Break the task into smaller pieces
- Escalate to the user if the plan is wrong

## Integration

**Required workflow skills:**
- **superpowers:using-git-worktrees** — REQUIRED: Set up isolated workspace before starting
- **superpowers:writing-plans** — Creates the plan this skill executes
- **superpowers:finishing-a-development-branch** — Complete development after all tasks

**Specialists should use:**
- **superpowers:test-driven-development** — Follow TDD for each task

**Alternative workflows:**
- **superpowers:subagent-driven-development** — Use for independent tasks (simpler, faster)
- **superpowers:executing-plans** — Use for inline execution without subagents