Multi-Agent
Workflow Builder

Six dispatch patterns · Prompt generator · CLAUDE.md rules · Custom agent template

Select a dispatch pattern

Key principle

Each sub-agent gets its own 200k context window. Parallelising 4 tasks costs roughly the same time as the slowest single task. Context isolation also prevents quality degradation on large codebases.

Watch out for

Sub-agents cannot spawn their own sub-agents (no nesting). If two agents modify the same file simultaneously, merge conflicts occur — assign clear file boundaries per agent. Use --dangerously-skip-permissions only in isolated CI containers.

Build your multi-agent prompt

Tasks (one per sub-agent)

Dispatch mode

Output format

Automatic routing rules

Add these rules to .claude/CLAUDE.md so Claude automatically picks the right pattern — no need to specify it each time.

Pattern	Conditions	Example use case
Parallel	ALL must be true 3+ unrelated tasks No shared state Clear file boundaries	Explore 4 dirs simultaneously; research 5 competitors
Sequential	ANY triggers it B depends on A's output Shared files or state Unclear scope upfront	Plan → implement → review pipeline
Background	Research or analysis only Not blocking current work Results deferred	Auth research while coding the UI
Fan-out	Large batch of similar items N files / docs / sections Results need synthesis	Summarise 20 meeting transcripts, combine into digest

CLAUDE.md snippet

.claude/CLAUDE.md

## Sub-agent routing

**Parallel dispatch** — ALL conditions must be met:
- 3+ unrelated tasks or independent domains
- No shared state between tasks
- Clear file boundaries with no overlap

**Sequential dispatch** — ANY condition triggers:
- Tasks have dependencies (B needs output from A)
- Shared files or state (merge conflict risk)
- Unclear scope (understand before proceeding)

**Background dispatch**:
- Research or analysis tasks (not file modifications)
- Results aren't blocking your current work

**Invocation requirements** — every sub-agent dispatch must include:
1. Explicit scope and file references
2. Expected output format (file path or summary)
3. Success criteria
4. Dependencies on other agents (if any)

Pro tip

Be explicit: "use 5 parallel tasks" is clearer than "parallelise this". Specify what each agent focuses on to prevent overlap. Scoped file ownership is the single biggest factor in conflict-free parallel runs.

Built-in sub-agents

Explore

Fast read-only agent for searching and analysing codebases. Optimised for file discovery and code search. Makes no writes.

auto-invoked read-only

Plan

Codebase research during plan mode. Prevents infinite nesting by handling deep research in its own context window.

plan mode

General-purpose

Handles multi-step tasks requiring both exploration and file modification. Delegates subtasks when scope grows.

read + write

Custom agents

Define specialist agents in .claude/agents/ with custom prompts, tool restrictions, and permission modes.

user-defined reusable

Custom agent template

.claude/agents/frontend-specialist.md

---
name: frontend-specialist
description: >
  Handles React components, CSS, and UI implementation.
  Invoke when building or modifying frontend files in
  src/components/, src/pages/, or src/styles/.
model: claude-haiku-4-5  # cheaper for routine UI work
tools:
  - read_file
  - write_file
  - search_files
allowed_paths:
  - src/components/**
  - src/pages/**
  - src/styles/**
---

You are a frontend specialist. Focus exclusively on:
- React components with TypeScript
- Tailwind CSS styling
- Accessibility (ARIA, semantic HTML)
- Component tests with React Testing Library

Save your output to the file path provided.
Return a one-paragraph summary of what you built.

Cost tip

Set specialist agents to use claude-haiku-4-5 for routine tasks (UI boilerplate, test generation, docs). Reserve Sonnet for the orchestrator and Opus for architecture decisions. This cuts token costs by 5–10× on large fan-outs.