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

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

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:

vs. Subagent-Driven Development

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