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:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Generic Roles

Teammate IDs are fixed. Their function is remapped per domain via Role Cards.

Role Cards (Domain Remapping)

Each domain preset provides Role Cards that specialize the generic functions:

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

Cost Guidelines

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)

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