Agent Team Orchestrator

The Problem

You throw a full-stack feature request at a single AI agent: design the API, build the backend, create the frontend, write tests, and review for security. The agent tries to do all five roles simultaneously. It designs the API while building the backend, then realizes the design needs to change mid-implementation. The frontend uses types that the backend already implemented differently. The tests are written against the final state, missing the intermediate decisions. By the end, you have a tangled codebase where the architect, builder, and reviewer were the same entity — and the output shows it.

What You Get

• Choose from four proven team topologies — Gatekeeper (one lead delegates to workers), Pipeline (sequential specialist chain), Swarm (parallel competing solutions), Supervisor (monitor with auto-recovery) — each matched to a specific project type
• Define agent roles with CLAUDE.md instructions — each agent gets a focused config specifying its identity, constraints, input/output paths, and handoff protocol, preventing scope creep between roles
• Create orchestration plans — a single markdown file defining topology, agent list, dependency chain, conflict zones, and success criteria that all agents read as shared context
• Dispatch agents with file-system isolation — each agent works in its own directory (agents/architect/, agents/builder/) with explicit read/write boundaries to prevent cross-agent file conflicts
• Implement structured handoff protocols — agents write summary files with what-was-done, decisions-made, and next-agent-needs-to-know sections, plus STATUS: DONE markers for completion verification
• Aggregate results and validate quality gates — orchestrator reads handoff files, verifies completion markers, checks quality criteria, and produces a consolidated results summary

Why This Beats Prompting It Yourself

Running claude agents or opening three Cursor windows doesn't make them a team — it makes them three independent agents with no coordination. Without role definition, each agent makes different assumptions about the architecture. Without handoff protocols, they don't share context. Without conflict zones, they edit the same files and corrupt each other's work. This skill provides the missing orchestration layer: topology selection, role scoping, dependency management, and result synthesis.

Example Session

You: "Build an authentication system — API, database schema, React login form, and tests"

Agent produces orchestration plan:

### Orchestration Plan: Auth System

**Topology:** Pipeline

**Agents:**
1. **Architect** — Design auth API spec, DB schema, UI flow
   Output: agents/architect/output/spec.md
2. **Builder** — Implement Express.js auth routes + React login form
   Input: agents/architect/output/spec.md
   Output: src/auth/, src/components/Login.tsx
3. **Reviewer** — Security review (JWT handling, injection, XSS)
   Input: src/auth/
   Output: agents/reviewer/output/review.md

**Dependency Chain:** Architect → Builder → Reviewer

**Conflict Zones:**
- src/shared/types.ts (Architect defines, Builder implements)

**Success Criteria:**
- All specs implemented and reviewed
- All tests passing
- No CRITICAL or HIGH security findings

Agent then dispatches:

[ORCHESTRATOR] Dispatching Architect to agents/architect/
[ORCHESTRATOR] Architect STATUS: DONE — spec.md written
[ORCHESTRATOR] Dispatching Builder (reads spec.md)
[ORCHESTRATOR] Builder STATUS: DONE — 3 files written
[ORCHESTRATOR] Dispatching Reviewer (reads src/auth/)
[ORCHESTRATOR] Reviewer STATUS: DONE — 2 HIGH findings

Use Cases

• Full-stack feature development (API + frontend + tests as separate specialist agents)
• Performance optimization swarm (3 agents try different approaches: query tuning, caching, schema redesign)
• CI/CD pipeline supervision (build → test → deploy with auto-recovery on failure)
• Code review pipelines (architect → builder → security-reviewer → test-writer)
• Large refactoring projects split across independent modules
• Competitive analysis (swarm: multiple agents implement the same feature in different ways)

Known Limitations

Multi-agent workflows add overhead — don't use for tasks under 20 minutes of agent time. Shared file conflicts between agents require strict directory isolation and can still occur with poorly defined conflict zones. Agent handoff quality depends on how well the orchestrator communicates — vague handoffs produce vague results. Non-Claude agents (Cursor, Codex CLI) lack native agent views and require manual directory-scoped window management.