Universal multi-agent workflow orchestration using Claude Code Agent Teams. Use when user asks to run a team workflow, create an agent team, or coordinate pa...
---
name: agent-team-workflows
description: "Universal multi-agent workflow orchestration using Claude Code Agent Teams. Use when user asks to run a team workflow, create an agent team, or coordinate parallel work across multiple teammates — for any domain (software, content, data, strategy, research, etc.)."
---
# Agent Team Workflows
Universal orchestration framework for 5-agent teams (1 Lead + 4 Teammates) across any domain.
## Prerequisites
Agent Teams must be enabled. Add to `~/.claude/settings.json`:
```json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
```
## Generic Roles
Teammate IDs are fixed. Their **function** is remapped per domain via **Role Cards**.
| Slot | ID | Generic Function | Core Responsibility |
|------|----|------------------|---------------------|
| **Lead** | (session) | Orchestrator | Assign tasks, relay context, quality gate, synthesize final output |
| **Slot A** | `architect` | **Planner** | Frame problem, decompose tasks, produce plan/spec/blueprint |
| **Slot B** | `developer` | **Builder** | Produce primary artifact (code, draft, dataset, model, proposal) |
| **Slot C** | `tester` | **Validator** | Check against acceptance criteria, test, evaluate correctness |
| **Slot D** | `reviewer` | **Critic** | Assess quality, risk, consistency, compliance, suggest improvements |
### Role Cards (Domain Remapping)
Each domain preset provides **Role Cards** that specialize the generic functions:
| Domain | Planner | Builder | Validator | Critic |
|--------|---------|---------|-----------|--------|
| Software Dev | Architect | Developer | Tester | Code Reviewer |
| Content Creation | Producer | Writer | Fact-Checker | Editor |
| Data Analysis | Analyst Lead | Data Engineer | Statistician | Peer Reviewer |
| Business Strategy | Strategist | Business Analyst | Financial Modeler | Risk Advisor |
| Research | Research Lead | Researcher | Methodology Auditor | Peer Reviewer |
> Full role cards with artifact contracts → `reference/domain-presets.md`
## Pipeline Patterns
4 canonical control-flow patterns. Domain meaning comes from Role Cards, not the pattern itself.
### 1. sequential — Step-by-Step Pipeline
```
Planner → Builder → Validator → Critic → Lead Synthesis
```
**Use when:** Work is linear and each step depends on the previous output.
**Examples:** Feature dev, content creation, report writing.
### 2. parallel-merge — Parallel Exploration + Merge
```
Planner → (Builder ∥ Validator ∥ Critic) → Lead Merge → Validator Gate → Lead Synthesis
```
**Use when:** Multiple perspectives can work independently, then combine.
**Examples:** Research, strategy analysis, multi-angle evaluation.
### 3. iterative-review — Build-Critique Loop
```
Planner → Builder ↔ Critic (max N rounds) → Validator → Lead Synthesis
```
**Use when:** Quality requires iteration between creator and reviewer.
**Examples:** Content editing, design refinement, proposal drafting.
**Guard:** Default max 2 rounds. More requires user approval.
### 4. fan-out-fan-in — Map-Reduce
```
Planner → fan-out tasks to all 4 teammates → Lead fan-in merge → Critic Gate → Lead Synthesis
```
**Use when:** Large work can be split into independent chunks processed in parallel.
**Examples:** Multi-module features, large dataset processing, codebase audit.
> Pattern deep dives with sample task graphs → `reference/patterns.md`
## Coordination Protocol
Strict 6-step protocol, domain-agnostic.
### Step 1: Confirm Scope
Before spawning any team, confirm with user:
1. **Objective** — specific deliverable
2. **Domain** — select preset or define custom Role Cards
3. **Pattern** — which pipeline pattern fits
4. **Constraints** — tools, tech stack, tone, compliance, budget
5. **Inputs** — source material, existing assets, context files
6. **Definition of Done** — checkbox acceptance criteria the user agrees to
### Step 2: Build Workflow Instance Spec
Fill in the universal template:
```
WORKFLOW INSTANCE SPEC
─────────────────────
Objective: [deliverable]
Pattern: [sequential | parallel-merge | iterative-review | fan-out-fan-in]
Domain: [preset name or "custom"]
ROLE CARDS
Planner (architect): [domain title] — [specific responsibility]
Builder (developer): [domain title] — [specific responsibility]
Validator (tester): [domain title] — [specific responsibility]
Critic (reviewer): [domain title] — [specific responsibility]
ARTIFACTS (per step)
Step 1 → [artifact name]: [format/content description]
Step 2 → [artifact name]: [format/content description]
Step 3 → [artifact name]: [format/content description]
Step 4 → [artifact name]: [format/content description]
CONSTRAINTS: [tools, rules, limits]
INPUTS: [files, data, references]
DEFINITION OF DONE:
□ [criterion 1]
□ [criterion 2]
□ [criterion 3]
```
### Step 3: Create Team
```
Create a team of 4 teammates:
- architect: [Planner role card — context and responsibility]
- developer: [Builder role card — context and responsibility]
- tester: [Validator role card — context and responsibility]
- reviewer: [Critic role card — context and responsibility]
```
### Step 4: Create Tasks with Dependencies
Create tasks following the selected pattern's pipeline order. Each task MUST have:
- Clear description referencing role card
- Required input artifact (from previous step or original inputs)
- Required output artifact (format + content)
- Acceptance criteria
- Dependency on predecessor task
### Step 5: Spawn Teammates with Rich Context
Each teammate MUST receive in their spawn prompt:
1. **Role Card** — their domain title + specific responsibilities
2. **Assigned task** — what to produce
3. **Input artifact** — output from previous step (Lead must relay this)
4. **Output artifact contract** — exact format and content expected
5. **Constraints** — domain rules, style guides, compliance
6. **Handoff instruction** — "Message the lead with [artifact] when done"
**Universal spawn template:**
```
Spawn a [ID] teammate with the prompt:
"You are the [Domain Title] ([Generic Function]).
YOUR TASK: [task description]
INPUT: [paste or reference previous step's output]
PRODUCE: [artifact name]
Format: [expected format]
Must include: [required sections/elements]
CONSTRAINTS:
- [rule 1]
- [rule 2]
When done, message the lead with your complete [artifact name].
If you encounter blockers, message the lead immediately."
```
### Step 6: Coordinate Handoffs
When a teammate completes their step:
1. Lead receives output via message
2. Lead validates output against acceptance criteria
3. Lead passes artifact + relevant context to next teammate via message
4. If output is insufficient → send specific feedback, ask to revise
### Step 7: Synthesize & Deliver
After all steps complete:
1. Collect all artifacts
2. Verify all Definition of Done criteria are met
3. Summarize what was done (traceability: each criterion → which step satisfied it)
4. List remaining TODOs or known issues
5. Present final deliverable to user
## Lead Discipline Rules
1. **Delegate only** — Lead does NOT produce primary artifacts. Use delegate mode (`Shift+Tab`).
2. **Relay all context** — Teammates have no shared history. Lead MUST forward relevant artifacts between steps.
3. **Direct messages** — Use direct messages, not broadcast (saves 4× tokens). Broadcast only for parallel-merge sync points.
4. **Right-size tasks** — 5-6 tasks per teammate max. Split large work.
5. **Gate high-risk actions** — Require user approval for: irreversible changes, external publication, legal/compliance, high-cost operations, production deployments.
6. **Wait for teammates** — Never proceed or implement yourself. Wait for teammate completion before next step.
## Handling Failures
| Situation | Action |
|-----------|--------|
| Teammate stuck | Message with additional context, hints, or simplified sub-task |
| Bad output | Send specific feedback citing acceptance criteria, ask to revise |
| Teammate stops | Spawn replacement with same context + summary of work already done |
| Conflict between teammates | Lead mediates, makes final decision, messages both with resolution |
| Task too large | Lead splits into subtasks, reassigns across teammates |
| Iterative loop exceeds max | Ask user whether to approve more rounds or finalize current state |
## Cost Guidelines
| Pattern | Est. Cost | Worth It When |
|---------|-----------|---------------|
| sequential | ~4-5× single | Work spans 3+ artifacts/files with clear pipeline |
| parallel-merge | ~4× single | 3+ independent perspectives needed |
| iterative-review | ~3-4× single | Quality requires creator-critic dialogue |
| fan-out-fan-in | ~5× single | Large work divisible into independent chunks |
**Rule of thumb:** If one agent can finish in one session, don't use a team. Teams shine when work is parallelizable or benefits from multiple specialized perspectives.
## Domain Presets (Quick Reference)
| Preset | Recommended Pattern | Key Artifacts |
|--------|-------------------|---------------|
| `software-dev` | sequential / fan-out-fan-in | Design doc, source code, test suite, review report |
| `content-creation` | iterative-review | Content brief, draft, fact-check report, final edit |
| `data-analysis` | fan-out-fan-in | Analysis plan, datasets/transforms, statistical evaluation, findings report |
| `business-strategy` | parallel-merge | Strategy framework, market analysis, financial model, risk assessment |
| `research` | parallel-merge | Research plan, literature review, methodology audit, synthesis paper |
> Full presets with role cards, artifacts, and worked examples → `reference/domain-presets.md`
> Ready-to-use prompt templates → `reference/prompt-templates.md`
> Pattern deep dives → `reference/patterns.md`
don't have the plugin yet? install it then click "run inline in claude" again.