{"skill":{"slug":"agent-team-orchestration","displayName":"Agent Team Orchestration","summary":"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.","description":"---\nname: agent-team-orchestration\ndescription: \"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.\"\n---\n\n# Agent Team Orchestration\n\nProduction playbook for running multi-agent teams with clear roles, structured task flow, and quality gates.\n\n## Quick Start: Minimal 2-Agent Team\n\nA builder and a reviewer. The simplest useful team.\n\n### 1. Define Roles\n\n```\nOrchestrator (you) — Route tasks, track state, report results\nBuilder agent     — Execute work, produce artifacts\n```\n\n### 2. Spawn a Task\n\n```\n1. Create task record (file, DB, or task board)\n2. Spawn builder with:\n   - Task ID and description\n   - Output path for artifacts\n   - Handoff instructions (what to produce, where to put it)\n3. On completion: review artifacts, mark done, report\n```\n\n### 3. Add a Reviewer\n\n```\nBuilder produces artifact → Reviewer checks it → Orchestrator ships or returns\n```\n\nThat's the core loop. Everything below scales this pattern.\n\n## Core Concepts\n\n### Roles\n\nEvery agent has one primary role. Overlap causes confusion.\n\n| Role | Purpose | Model guidance |\n|------|---------|---------------|\n| **Orchestrator** | Route work, track state, make priority calls | High-reasoning model (handles judgment) |\n| **Builder** | Produce artifacts — code, docs, configs | Can use cost-effective models for mechanical work |\n| **Reviewer** | Verify quality, push back on gaps | High-reasoning model (catches what builders miss) |\n| **Ops** | Cron jobs, standups, health checks, dispatching | Cheapest model that's reliable |\n\n→ *Read [references/team-setup.md](references/team-setup.md) when defining a new team or adding agents.*\n\n### Task States\n\nEvery task moves through a defined lifecycle:\n\n```\nInbox → Assigned → In Progress → Review → Done | Failed\n```\n\n**Rules:**\n- Orchestrator owns state transitions — don't rely on agents to update their own status\n- Every transition gets a comment (who, what, why)\n- Failed is a valid end state — capture why and move on\n\n→ *Read [references/task-lifecycle.md](references/task-lifecycle.md) when designing task flows or debugging stuck tasks.*\n\n### Handoffs\n\nWhen work passes between agents, the handoff message includes:\n\n1. **What was done** — summary of changes/output\n2. **Where artifacts are** — exact file paths\n3. **How to verify** — test commands or acceptance criteria\n4. **Known issues** — anything incomplete or risky\n5. **What's next** — clear next action for the receiving agent\n\nBad handoff: *\"Done, check the files.\"*\nGood 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.\"*\n\n### Reviews\n\nCross-role reviews prevent quality drift:\n\n- **Builders review specs** — \"Is this feasible? What's missing?\"\n- **Reviewers check builds** — \"Does this match the spec? Edge cases?\"\n- **Orchestrator reviews priorities** — \"Is this the right work right now?\"\n\nSkip the review step and quality degrades within 3-5 tasks. Every time.\n\n→ *Read [references/communication.md](references/communication.md) when setting up agent communication channels.*\n→ *Read [references/patterns.md](references/patterns.md) for proven multi-step workflows.*\n\n## Reference Files\n\n| File | Read when... |\n|------|-------------|\n| [team-setup.md](references/team-setup.md) | Defining agents, roles, models, workspaces |\n| [task-lifecycle.md](references/task-lifecycle.md) | Designing task states, transitions, comments |\n| [communication.md](references/communication.md) | Setting up async/sync communication, artifact paths |\n| [patterns.md](references/patterns.md) | Implementing specific workflows (spec→build→test, parallel research, escalation) |\n\n## Common Pitfalls\n\n### Spawning without clear artifact output paths\nAgent 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.\n\n### No review step = quality drift\n\"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.\n\n### Agents not commenting on task progress\nSilent agents create coordination blind spots. Require comments at: start, blocker, handoff, completion. If an agent goes silent, assume it's stuck.\n\n### Not verifying agent capabilities before assigning\nAssigning browser-based testing to an agent without browser access. Assigning image work to a text-only model. Check capabilities before routing.\n\n### Orchestrator doing execution work\nThe 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.\n\n## When NOT to Use This Skill\n\n- **Single-agent setups** — Just follow standard AGENTS.md conventions. Team orchestration adds overhead that solo agents don't need.\n- **One-off task delegation** — Use `sessions_spawn` directly. This skill is for sustained workflows with multiple handoffs.\n- **Simple question routing** — If you're just forwarding a question to a specialist, that's a message, not a workflow.\n\nThis skill is for **sustained team workflows** — recurring collaboration patterns where agents depend on each other's output over multiple tasks.\n","tags":{"latest":"1.0.0"},"stats":{"comments":3,"downloads":25240,"installsAllTime":287,"installsCurrent":286,"stars":76,"versions":1},"createdAt":1770912001303,"updatedAt":1778488085397},"latestVersion":{"version":"1.0.0","createdAt":1770912001303,"changelog":"Initial release introducing structured orchestration for multi-agent teams.\n\n- Provides a detailed playbook for managing teams of 2+ agents, including roles, task lifecycles, handoff protocols, and review workflows.\n- Outlines best practices for defining roles (Orchestrator, Builder, Reviewer, Ops) and structuring task flow.\n- Introduces clear guidelines for task state transitions, artifact handoffs, and review processes to prevent quality drift.\n- Documents common pitfalls, such as skipping reviews and unclear artifact paths.\n- Includes references and practical guidance for communication, workflow patterns, and when not to use this skill.","license":null},"metadata":null,"owner":{"handle":"arminnaimi","userId":"s17891ek5xp4af475aa3tr4e2s884smt","displayName":"arminn","image":"https://avatars.githubusercontent.com/u/4364977?v=4"},"moderation":null}