# 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`