Agent Team Orchestration

Orchestrate multi-agent teams with defined roles, task lifecycles, handoff protocols, and review workflows. Use when: (1) Setting up a team of 2+ agents with different specializations, (2) Defining task routing and lifecycle (inbox → spec → build → review → done), (3) Creating handoff protocols between agents, (4) Establishing review and quality gates, (5) Managing async communication and artifact sharing between agents.

Security Scan

The skill is an instruction-only playbook for coordinating multi-agent teams and its requested/declared surface is consistent with that purpose.

Purpose & Capability

Name/description (team orchestration) align with the content: role definitions, task lifecycle, handoffs, reviews, and file conventions. No unexpected credentials, binaries, or external services are requested.

Instruction Scope

SKILL.md and reference files stick to orchestration concerns (spawning/sending sessions, shared artifact paths, state transitions, escalation). The instructions reference platform primitives (spawn, sessions_send) and shared file paths (/shared, /workspace) which are appropriate for coordination. They do not instruct reading arbitrary host files, exfiltrating data, or contacting external endpoints.

Install Mechanism

This is an instruction-only skill with no install spec and no code files, so nothing is written to disk or fetched during install. Low install risk.

Credentials

No environment variables, credentials, or config paths are required. The docs do mention 'missing access or credentials' as a blocker to escalate, which is a reasonable run-time procedure rather than a demand for secrets.

Persistence & Privilege

The skill is not always-included (always: false). disable-model-invocation is false (agent may invoke autonomously), which is the platform default and reasonable for an orchestration skill. The skill does not request modification of other skills or system-level config.

Assessment

This playbook appears coherent and appropriate for orchestrating agent teams, but before installing consider: (1) Confirm how the platform implements /shared and /workspace — ensure those are sandboxed and don't map to sensitive host paths. (2) Enable artifact versioning or backups (the playbook suggests overwriting in place, which risks data loss). (3) Verify session spawn/send behavior and logging to ensure no unintended external transmission of artifacts. (4) Enforce least privilege for agents (don't give orchestrator or builders more host access than needed). (5) If your workflows require credentials (APIs, infra), ensure those secrets are stored and accessed via secure platform-managed vaults — the skill itself does not request or justify direct credential access. If you want a tighter assessment, provide the platform's mapping of /shared and the exact spawn/send APIs so I can check for any platform-level leakage vectors.

Production playbook for running multi-agent teams with clear roles, structured task flow, and quality gates.

Quick Start: Minimal 2-Agent Team

A builder and a reviewer. The simplest useful team.

1. Define Roles

Orchestrator (you) — Route tasks, track state, report results
Builder agent     — Execute work, produce artifacts

2. Spawn a Task

1. Create task record (file, DB, or task board)
2. Spawn builder with:
   - Task ID and description
   - Output path for artifacts
   - Handoff instructions (what to produce, where to put it)
3. On completion: review artifacts, mark done, report

3. Add a Reviewer

Builder produces artifact → Reviewer checks it → Orchestrator ships or returns

That's the core loop. Everything below scales this pattern.

Core Concepts

Roles

Every agent has one primary role. Overlap causes confusion.

Role	Purpose	Model guidance
Orchestrator	Route work, track state, make priority calls	High-reasoning model (handles judgment)
Builder	Produce artifacts — code, docs, configs	Can use cost-effective models for mechanical work
Reviewer	Verify quality, push back on gaps	High-reasoning model (catches what builders miss)
Ops	Cron jobs, standups, health checks, dispatching	Cheapest model that's reliable

→ Read references/team-setup.md when defining a new team or adding agents.

Task States

Every task moves through a defined lifecycle:

Inbox → Assigned → In Progress → Review → Done | Failed

Rules:

• Orchestrator owns state transitions — don't rely on agents to update their own status
• Every transition gets a comment (who, what, why)
• Failed is a valid end state — capture why and move on

→ Read references/task-lifecycle.md when designing task flows or debugging stuck tasks.

Handoffs

When work passes between agents, the handoff message includes:

1. What was done — summary of changes/output
2. Where artifacts are — exact file paths
3. How to verify — test commands or acceptance criteria
4. Known issues — anything incomplete or risky
5. What's next — clear next action for the receiving agent

Bad handoff: "Done, check the files." Good handoff: "Built auth module at /shared/artifacts/auth/. Run npm test auth to verify. Known issue: rate limiting not implemented yet. Next: reviewer checks error handling edge cases."

Reviews

Cross-role reviews prevent quality drift:

• Builders review specs — "Is this feasible? What's missing?"
• Reviewers check builds — "Does this match the spec? Edge cases?"
• Orchestrator reviews priorities — "Is this the right work right now?"

Skip the review step and quality degrades within 3-5 tasks. Every time.

→ Read references/communication.md when setting up agent communication channels. → Read references/patterns.md for proven multi-step workflows.

Reference Files

File	Read when...
team-setup.md	Defining agents, roles, models, workspaces
task-lifecycle.md	Designing task states, transitions, comments
communication.md	Setting up async/sync communication, artifact paths
patterns.md	Implementing specific workflows (spec→build→test, parallel research, escalation)

Common Pitfalls

Spawning without clear artifact output paths

Agent produces great work, but you can't find it. Always specify the exact output path in the spawn prompt. Use a shared artifacts directory with predictable structure.

No review step = quality drift

"It's a small change, skip review." Do this three times and you have compounding errors. Every artifact gets at least one set of eyes that didn't produce it.

Agents not commenting on task progress

Silent agents create coordination blind spots. Require comments at: start, blocker, handoff, completion. If an agent goes silent, assume it's stuck.

Not verifying agent capabilities before assigning

Assigning browser-based testing to an agent without browser access. Assigning image work to a text-only model. Check capabilities before routing.

Orchestrator doing execution work

The orchestrator routes and tracks — it doesn't build. The moment you start "just quickly doing this one thing," you've lost oversight of the rest of the team.

When NOT to Use This Skill

• Single-agent setups — Just follow standard AGENTS.md conventions. Team orchestration adds overhead that solo agents don't need.
• One-off task delegation — Use sessions_spawn directly. This skill is for sustained workflows with multiple handoffs.
• Simple question routing — If you're just forwarding a question to a specialist, that's a message, not a workflow.

This skill is for sustained team workflows — recurring collaboration patterns where agents depend on each other's output over multiple tasks.