# agents-orchestrator

> A Claude Code agent persona that runs an autonomous PM → Architect → Dev↔QA-loop → integration pipeline, gating each task on QA pass before advancing and capping retries at 3 before escalation.

**Use case**: Run a full spec-to-ship pipeline with task-level QA gates instead of one big agent call

**Canonical URL**: https://agentcookbooks.com/skills/agents-orchestrator/

**Topics**: claude-code, skills, subagents, planning

**Trigger phrases**: "orchestrate the pipeline", "run the full workflow", "spawn agents-orchestrator"

**Source**: [Michael Sitarzewski](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md)

**License**: MIT

---

## What it does

`agents-orchestrator` is the conductor persona in the agency-agents collection. It takes a single project spec, then drives the whole pipeline: spawn `project-manager-senior` to extract a task list, spawn `ArchitectUX` to lay technical foundations, then enter a per-task loop that alternates a developer agent with an `EvidenceQA` agent until QA returns PASS — and only then advances to the next task. After all tasks pass, it spawns `testing-reality-checker` for final integration sign-off.

The discipline the persona enforces is the gate: no task advances on a soft pass, retries are capped at 3, and a fourth failure escalates rather than papering over the issue. It's the opposite of "one prompt, hope for the best" — it's a finite-state machine described as a system prompt.

## When to use it

- A project spec exists and you want an autonomous run rather than steering each phase yourself
- The work decomposes cleanly into tasks where each one has a verifiable PASS/FAIL outcome
- You want explicit retry-and-escalate behavior instead of silent partial completion
- You're already comfortable spawning multiple subagents and want a coordinator on top of them

When *not* to reach for it:

- Exploratory work where the spec doesn't exist yet — the orchestrator expects a `project-specs/*-setup.md` file as input
- Single-task changes — the loop overhead isn't worth it for a one-file fix
- Work that can't produce screenshot or evidence-based QA — the gate becomes vibes, which defeats the purpose

## Install

From [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) at `specialized/agents-orchestrator.md`. Copy the file to `~/.claude/agents/` (or use the repo's `scripts/install.sh`). The orchestrator references a roster of other personas from the same repo (`project-manager-senior`, `ArchitectUX`, `EvidenceQA`, `testing-reality-checker`, plus per-task developer agents), so it works best when the rest of the agency-agents collection is also installed.

## What a session looks like

1. **Phase 1 — PM.** Orchestrator reads `project-specs/<project>-setup.md`, spawns `project-manager-senior`, waits for `project-tasks/<project>-tasklist.md` to land.
2. **Phase 2 — Architecture.** Spawns `ArchitectUX` to produce CSS scaffolding and `project-docs/<project>-architecture.md` from the spec + task list.
3. **Phase 3 — Dev↔QA loop.** For each task:
   - Spawn the right developer agent (Frontend Developer, Backend Architect, Mobile App Builder, etc.) scoped to that one task.
   - Spawn `EvidenceQA` to validate, requiring screenshot evidence.
   - On PASS: advance, reset retry counter. On FAIL: loop back to dev with the QA feedback. After 3 fails: escalate, mark task blocked, continue.
4. **Phase 4 — Integration.** Once all tasks pass, spawn `testing-reality-checker` for end-to-end validation. The reality-checker defaults to NEEDS WORK unless evidence proves otherwise.
5. **Status reporting.** The orchestrator emits structured progress reports between phases — current phase, task completion ratio, retry counts, last QA feedback.

The discipline that makes it work: the per-task QA gate. Without it, the orchestrator collapses into "spawn a bunch of agents and pray" — which is what most multi-agent prompts already do.

## Receipts

_TODO — to be filled in from a real orchestrated run. Once the persona has been used to drive a project from spec to integration, this section will capture: how many tasks the run held together before something broke, where the retry-3-then-escalate rule actually fired, whether the EvidenceQA gate caught real regressions or just rubber-stamped, and the wall-clock vs. doing-it-myself delta._

## Source and attribution

From [Michael Sitarzewski's agency-agents repository](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md), an MIT-licensed collection of 144+ AI agent personas across engineering, marketing, design, testing, and specialized roles.

License: MIT.

Quote from the persona body, verbatim: *"No phase advancement without meeting quality standards."* The whole orchestrator is built around making that gate stick.