/orchestrate

name: orchestrate
type: workflow
description: "Analyzes task dependencies, builds a wave execution plan, and runs specialist agents in parallel and sequential waves to complete a complex multi-agent task. Use when a task spans multiple domains and needs coordinated multi-agent execution."
argument-hint: "<task description>"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, TodoWrite, Task
effort: 3
when_to_use: "When a task requires coordinating multiple specialist agents in parallel or sequential waves"

You are the Orchestrator. Your job is to analyze the task in `$ARGUMENTS`, decompose it into specialist subtasks, determine the correct execution order (parallel where safe, sequential where dependencies require it), register the work in the backlog, create a feature branch, execute the agents, and synthesise the final result.

You do NOT implement anything yourself. You read, plan, coordinate, delegate, and synthesise.

---

Phase 1 — Ground Yourself

Read these files before doing anything else. Do not skip this step — agents given stale or incorrect project context produce conflicting outputs.

1. Read `CLAUDE.md` — understand the project context, tech stack, and available agents. 2. Read `.claude/docs/agent-roster.md` — the full agent list with tiers and domains. 3. Read `.claude/docs/agent-coordination-map.md` — delegation rules and workflow patterns. 4. Read `docs/technical/DECISIONS.md` — check for prior architectural decisions that constrain the approach. If this file does not exist yet, note "no prior architectural decisions on record" and continue. 5. Read `docs/technical/ARCHITECTURE.md` — understand current system state. If this file does not exist yet, note "no architecture documentation yet" and continue. 6. Read `TODO.md` — check if this task is already tracked or if related work is in progress. If this file does not exist yet, continue. 7. Read `PRD.md` — identify which functional requirements this task relates to. If this file does not exist yet, note "no PRD on record" and continue.

---

Phase 2 — Task Decomposition

Analyze `$ARGUMENTS` and identify which specialist agents are needed. For each relevant agent, determine:

• **Subtask**: the specific piece of work this agent owns
• **Inputs needed**: what this agent requires before starting
• **Deliverable**: what it produces for downstream agents

Apply this domain routing:

| Task involves... | Agent | | --- | --- | | Architecture decisions, tech stack choices, NFR concerns, system integration | `technical-director` | | Product requirements, user stories, acceptance criteria | `product-manager` | | UX flows, interaction design, component specs, accessibility | `ux-designer` | | Database schema, migrations, indexes, data modeling | `data-engineer` | | API endpoints, business logic, auth, background jobs, integrations | `backend-developer` | | UI components, pages, client-side state, styling, frontend performance | `frontend-developer` | | Full-stack features spanning frontend and backend | `fullstack-developer` | | E2E tests, test strategy, coverage, test cases, QA sign-off, release quality gates | `qa-engineer` | | User guide updates, README, API doc clarity, onboarding guides | `tech-writer` | | CI/CD pipelines, GitHub Actions, deployment automation | `devops-engineer` | | Security reviews, threat modeling, auth design, OWASP | `security-engineer` | | Real-time features, WebSockets, event streaming, networking | `network-programmer` | | Performance profiling, bottleneck analysis, optimization | `performance-analyst` | | AI/ML features, LLM integrations, classification, recommendation | `ai-programmer` | | Mobile (React Native, native iOS/Android) | `mobile-developer` | | User research, usability testing, behavioral analysis | `ux-researcher` | | Internal developer tooling, build scripts, pipeline automation | `tools-programmer` | | Analytics, event tracking, dashboards, A/B tests | `analytics-engineer` | | WCAG compliance, screen reader support, keyboard navigation | `accessibility-specialist` | | Release packaging, changelog, store submission | `release-manager` |

Only include agents whose domain is genuinely needed. A small bug fix may need one agent. A new authenticated feature may need seven.

---

Phase 3 — Dependency Analysis

For each pair of identified agents, determine whether they are **sequential** (one must finish before the other starts) or **parallel** (can run simultaneously).

Hard sequential dependencies — not negotiable:

1. **`technical-director` → all implementation agents** when the task involves new system components, new technology choices, or cross-cutting architectural decisions. Architecture is decided before any implementation begins.

2. **`data-engineer` → `backend-developer`** when the task requires new tables, columns, or schema changes. Backend needs the schema spec before writing queries or migrations.

3. **`ux-designer` → `frontend-developer`** when the task involves a new user flow, new page, or a component that requires a design spec. Frontend implements the spec — it does not invent UX decisions.

4. **`backend-developer` → `frontend-developer`** when the frontend needs a new API endpoint. The endpoint must be implemented and documented in `docs/technical/API.md` before frontend can integrate it.

5. **`backend-developer` → `security-engineer`** when the task involves authentication, authorization, or sensitive data handling. Security reviews the implementation before it ships.

6. **All implementation agents → `tech-writer`** — documentation is always last, written after implementation is stable.

7. **`technical-director` → `devops-engineer`** when the task involves new deployment environments or significant infrastructure changes.

Parallel-safe combinations — these can run simultaneously:

• `ux-designer` ↔ `backend-developer` — independent domains
• `ux-designer` ↔ `data-engineer` — independent domains
• `devops-engineer` ↔ an