Agent Team Orchestration

Design, launch, steer, or audit Claude Code agent teams using official agent-team semantics, explicit coordination boundaries, and visible quality gates. Treat agent teams as an experimental Claude Code feature that is disabled by default and only appropriate when peer sessions need direct communication, a shared task list, and enough independent work to justify extra tokens. [DOC]

Activation

Activate when the request involves:

• Enabling or troubleshooting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. [DOC]
• Asking Claude Code to spawn teammates, name teammates, assign tasks, or wait for teammates. [DOC]
• Designing a team lead plus peer teammate plan with shared tasks and inter-agent messaging. [DOC]
• Comparing agent teams with subagents, agent view, dynamic workflows, or manual worktree sessions. [DOC]
• Adding quality gates for TeammateIdle, TaskCreated, or TaskCompleted hooks. [DOC]

Do not activate for generic project management, ordinary task lists, standalone subagent authoring, or workflow scripts unless the user explicitly asks for Claude Code agent teams. [INFERENCIA]

Source Authority

Use official Claude Code documentation as the runtime source of truth. Load these references when the answer affects behavior:

• references/official-agent-teams.md - Current official agent-team behavior, settings, coordination, and limits. [DOC]
• references/selection-boundaries.md - Selection rules for agent teams versus subagents, agent view, workflows, and worktrees. [DOC]
• references/coordination-quality-gates.md - Task design, messaging, hooks, permissions, and closeout gates. [DOC][CONFIG]
• assets/team-readiness-checklist.md - Reusable go/no-go checklist before proposing or launching a team. [CONFIG]

If the active Claude Code version cannot be verified, include coverage_gap: active Claude Code version not verified. If official docs cannot be fetched or are older than the local runtime, include the source date and mark version-sensitive details. [DOC][INFERENCIA]

Inputs Expected

• Goal, repository scope, and whether the user wants advice, launch instructions, or an orchestration plan.
• Candidate teammate roles, file ownership boundaries, and known dependencies.
• Permission posture, hook availability, terminal/display constraints, and token budget sensitivity.
• Need to distinguish agent teams from subagents, agent view, workflows, or worktrees.

Outputs Expected

• Activation decision: use agent team, subagent, agent view, workflow, worktree, or single session.
• Team design: lead responsibility, named teammates, teammate models when specified, and spawn prompt.
• Shared task-list plan with assignments, dependencies, claim rules, and file-conflict boundaries.
• Communication plan: direct messages, lead synthesis cadence, and intervention points.
• Quality gate plan: plan approval, hooks, permissions, validation, and shutdown criteria.
• Residual risks and coverage_gap items.

Procedure

1. Gate The Feature

Confirm that the workflow explicitly benefits from parallel peer sessions. Require enough independent work to offset coordination overhead and token use. For sequential work, same-file edits, routine implementation, or tasks where workers only need to report results, recommend a single session or subagents instead. [DOC][INFERENCIA]

Confirm enablement path. Agent teams are disabled by default and require CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the shell environment or Claude Code settings.json. Without that variable, do not claim teams will spawn or propose teammates. [DOC]

2. Choose The Coordination Surface

Use agent teams when teammates must message each other, self-coordinate through shared tasks, or challenge findings during parallel work. Use subagents for focused workers inside one session that return results to the caller. Use agent view for separately dispatched background sessions. Use workflows when the orchestration should live in rerunnable JavaScript and scale beyond a handful of peers. Use worktrees for manual isolated sessions without automated team coordination. [DOC]

3. Design The Team

Name the team lead as the main Claude Code session. Name every teammate predictably in the spawn request. Assign each teammate a distinct responsibility, owned file set, and deliverable. Specify teammate model only when the user or task requires it; teammates do not automatically inherit the lead model unless configured as the default teammate model. [DOC]

Use subagent definitions as teammate types when a reusable role already exists. Preserve the official boundary: the teammate honors the subagent definition's tools, model, and body instructions, but skills and mcpServers frontmatter fields are not applied through this path. [DOC]

4. Plan Before Writes

For risky or multi-file work, require teammate plan approval before implementation. Define the approval criteria in the lead prompt, such as test coverage, file ownership, no schema changes, or no production-side effects. Treat the teammate as read-only until the lead approves the plan. [DOC][INFERENCIA]

5. Build The Shared Task List

Break work into self-contained tasks with states pending, in progress, and completed. Add dependencies for tasks that cannot be claimed yet. Assign critical tasks explicitly. Allow self-claiming only for unassigned, unblocked work after a teammate finishes its current task. Keep each task large enough to justify coordination and small enough to produce a clear artifact. [DOC]

Avoid file conflicts by assigning disjoint file ownership. When overlap is unavoidable, make one teammate the owner and route reviews through messages rather than parallel edits. [DOC][INFERENCIA]

6. Define Communication

Make teammate names stable so messages can target the right recipient. Send one direct message per recipient when broadcasting is needed. Remind the lead that teammates get project context, MCP servers, skills, and the spawn prompt, but not the lead's conversation history. Include task-specific context in each spawn prompt. [DOC]

Monitor progress. Tell the lead to wait for teammates before synthesizing when the lead starts doing delegated work too early. Interrupt, redirect, or replace teammates that stop on errors or drift. [DOC]

7. Add Quality Gates

Use hooks when the environment supports them:

• TaskCreated: reject vague, overlapping, unsafe, or dependency-free tasks when dependencies exist. [DOC]
• TaskCompleted: block completion until required evidence, tests, and changed-file summaries exist. [DOC]
• TeammateIdle: send feedback and keep a teammate working when its output lacks the requested proof. [DOC]

Pair hooks with permission design. Teammates start with the lead's permission settings; --dangerously-skip-permissions applies to teammates too. Permission mode cannot be set per teammate at spawn time, though modes can be changed after spawning. [DOC]

8. Close The Team

Require lead synthesis after teammates finish. Include what each teammate did, what was accepted or rejected, validation evidence, unresolved conflicts, task-list status, and shutdown instructions. Ask named teammates to shut down when their work is complete. Note that shared task directories persist locally while team config cleanup is automatic at session end. [DOC]

Quality Criteria

• Experimental gate and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS are handled before launch.
• Team design names a lead, named teammates, roles, models when needed, and file ownership.
• Shared task list includes states, dependencies, assignment or self-claim rules, and no same-file parallel writes.
• Communication plan includes direct teammate messages and lead synthesis.
• Plan approval is required for risky work.
• Hook gates cover task creation, task completion, and teammate idle feedback when available.
• Permissions, context loading, token cost, and limitations are explicit.
• Output distinguishes agent teams from subagents, agent view, workflows, and worktrees.

Limitations To Surface

Agent teams are experimental. Surface limitations that affect the plan: no in-process teammate resumption with /resume or /rewind, task status lag, slow shutdown while a tool call is running, one team per session, no nested teams, fixed lead role, permission mode inherited at spawn, and split-pane constraints in terminals that lack tmux or iTerm2 support. [DOC]

Validation

Use the toolkit's canonical gate before final delivery. Per CONSTITUTION Art. 5, a skill is hardened only when ${CLAUDE_PLUGIN_ROOT}/scripts/check.sh passes; per Art. 6, a missing or failing gate is a red verdict. Run the gate from the plugin root:

bash "$CLAUDE_PLUGIN_ROOT/scripts/check.sh"
git diff --check -- skills/agent-team-orchestration

check.sh validates this skill's frontmatter, schema-v2 static eval contract, and lineage, then runs the packet, hardening, lint, relations, and integrity gates (validate_skill_contracts.py, validate_packet.py, harden_audit.py, lint_gate.py, validate_relations.py, integrity.py). This skill has no deterministic automation scripts/ of its own; its live team behavior remains not_executed until a runtime trace exists. [CÓDIGO][CONFIG]

Related katas (toolkit)

• katas-hub-and-spoke-isolation
• katas-multiagent-error-propagation

Contract

• Aceptación: equipos con lead + lista compartida y fronteras de propiedad por archivo/módulo/etapa. [EXPLICIT]
• Límites: experimental; mensajería de pares puede no estar en todos los runtimes. [EXPLICIT]
• Casos borde: ownership solapado → conflictos; definir equipo solo con límites explícitos. [EXPLICIT]
• Supuestos: SendMessage presente en la sesión [CÓDIGO]. [SUPUESTO]
• Trade-off: coordinación de pares vs un subagente — más capacidad, más complejidad de error. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output · assets/ recursos estáticos.