Claude Agent Team Workflows 0.1.0

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.

| 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:

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

Agent Teams must be enabled. Add to ~/.claude/settings.json:

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