Agent Team Workflows

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. SlotIDGeneric FunctionCore ResponsibilityLead(session)OrchestratorAssign tasks, relay context, quality gate, synthesize final outputSlot AarchitectPlannerFrame problem, decompose tasks, produce plan/spec/blueprintSlot BdeveloperBuilderProduce primary artifact (code, draft, dataset, model, proposal)Slot CtesterValidatorCheck against acceptance criteria, test, evaluate correctnessSlot DreviewerCriticAssess quality, risk, consistency, compliance, suggest improvements

Role Cards (Domain Remapping)

Each domain preset provides Role Cards that specialize the generic functions: DomainPlannerBuilderValidatorCriticSoftware DevArchitectDeveloperTesterCode ReviewerContent CreationProducerWriterFact-CheckerEditorData AnalysisAnalyst LeadData EngineerStatisticianPeer ReviewerBusiness StrategyStrategistBusiness AnalystFinancial ModelerRisk AdvisorResearchResearch LeadResearcherMethodology AuditorPeer 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: Objective — specific deliverable Domain — select preset or define custom Role Cards Pattern — which pipeline pattern fits Constraints — tools, tech stack, tone, compliance, budget Inputs — source material, existing assets, context files 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:
• Role Card — their domain title + specific responsibilities
• Assigned task — what to produce
• Input artifact — output from previous step (Lead must relay this)
• Output artifact contract — exact format and content expected
• Constraints — domain rules, style guides, compliance
• 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: Lead receives output via message Lead validates output against acceptance criteria Lead passes artifact + relevant context to next teammate via message If output is insufficient → send specific feedback, ask to revise

Step 7: Synthesize & Deliver

After all steps complete: Collect all artifacts Verify all Definition of Done criteria are met Summarize what was done (traceability: each criterion → which step satisfied it) List remaining TODOs or known issues Present final deliverable to user

Lead Discipline Rules

Delegate only — Lead does NOT produce primary artifacts. Use delegate mode (Shift+Tab). Relay all context — Teammates have no shared history. Lead MUST forward relevant artifacts between steps. Direct messages — Use direct messages, not broadcast (saves 4× tokens). Broadcast only for parallel-merge sync points. Right-size tasks — 5-6 tasks per teammate max. Split large work. Gate high-risk actions — Require user approval for: irreversible changes, external publication, legal/compliance, high-cost operations, production deployments. Wait for teammates — Never proceed or implement yourself. Wait for teammate completion before next step.

Handling Failures

SituationActionTeammate stuckMessage with additional context, hints, or simplified sub-taskBad outputSend specific feedback citing acceptance criteria, ask to reviseTeammate stopsSpawn replacement with same context + summary of work already doneConflict between teammatesLead mediates, makes final decision, messages both with resolutionTask too largeLead splits into subtasks, reassigns across teammatesIterative loop exceeds maxAsk user whether to approve more rounds or finalize current state

Cost Guidelines

PatternEst. CostWorth It Whensequential~4-5× singleWork spans 3+ artifacts/files with clear pipelineparallel-merge~4× single3+ independent perspectives needediterative-review~3-4× singleQuality requires creator-critic dialoguefan-out-fan-in~5× singleLarge 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)

PresetRecommended PatternKey Artifactssoftware-devsequential / fan-out-fan-inDesign doc, source code, test suite, review reportcontent-creationiterative-reviewContent brief, draft, fact-check report, final editdata-analysisfan-out-fan-inAnalysis plan, datasets/transforms, statistical evaluation, findings reportbusiness-strategyparallel-mergeStrategy framework, market analysis, financial model, risk assessmentresearchparallel-mergeResearch 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