Delegation — Agent Orchestration & Parallelization

What It Does

The Problem

How It Works

🚨 CRITICAL ROUTING — Two COMPLETELY Different Systems

• Custom agents = one-shot parallel workers with unique identities, launched via Task(), no shared state
• Agent teams = persistent coordinated teams with shared task lists, messaging, and multi-turn collaboration via TeamCreate

When the Algorithm Should Use This Skill

• 3+ independent workstreams exist at Extended+ effort level
• Multiple identical non-serial tasks need parallel execution
• Specialized expertise needed (architecture design, implementation, ISC optimization)
• Large codebase changes spanning 5+ files benefit from parallel workers
• Research + execution can proceed simultaneously
• "Create an agent team" — use TeamCreate for persistent coordinated teams
• Unattended autonomous work where auditability matters more than speed — spawn an Observer team (Agents skill → SPAWNOBSERVERS) alongside the primary agent, reading the tool-activity audit log, voting continue/halt/escalate. ONLY use when BOTH (a) time is not a constraint and (b) auditability is the primary requirement. Never for interactive or time-sensitive work. See Agents/SKILL.md "Observer Team Archetype" for shape and guardrails.

Delegation Patterns

1. Built-In Agents

2. Worktree-Isolated Agents

• Each agent gets its own working tree — no file conflicts with other agents
• Worktree auto-created on spawn, auto-cleaned when agent finishes (unless changes made)
• Use when multiple agents edit the same files or for competing approaches
• Can combine with run_in_background: true for non-blocking isolated work
• Built-in agents with isolation: worktree in frontmatter auto-isolate on every spawn

3. Background Agents

• Use when results aren't needed immediately
• Check output with Read tool on the output_file path
• Ideal for: research, long builds, parallel investigations

3b. Foreground Agents (the default — contrast to pattern 3, not a seventh pattern)

• Use when you need the result before proceeding
• Use for sequential dependencies
• Default mode — most common

4. Custom Agents (via Agents Skill)

# Step 1: Compose agent identity
bun run ~/.claude/skills/Agents/Tools/ComposeAgent.ts --traits "security,skeptical,thorough" --task "Review auth" --output json

# Step 2: Launch with composed prompt
Task(subagent_type="general-purpose", prompt=<ComposeAgent JSON .prompt field>)

• Each agent gets unique personality, voice, and color via ComposeAgent
• Use DIFFERENT trait combinations for each agent to get unique voices
• Never use built-in agent types for custom work — compose via the Agents skill
• Ideal for: domain experts, adversarial reviewers, creative brainstormers, parallel analysis

5. Agent Teams (via TeamCreate)

1. TeamCreate(team_name="my-project")           # Creates team + task list
2. TaskCreate(subject="Implement auth module")   # Create team tasks
3. Task(subagent_type="general-purpose", team_name="my-project", name="auth-engineer")  # Spawn teammate (senior-engineer/TDD brief in prompt)
4. TaskUpdate(taskId="1", owner="auth-engineer") # Assign task
5. SendMessage(type="message", recipient="auth-engineer", content="...")  # Coordinate

• Custom agents (Agents skill) = fire-and-forget parallel workers, no shared state
• Agent teams (TeamCreate) = persistent coordinated teams with shared task lists, messaging, multi-turn

• Use for 3+ independently workable criteria at Extended+
• Large complex coding tasks benefit most
• Each teammate works independently on assigned tasks via shared task list
• Parent coordinates via SendMessage, reconciles results
• Teammates go idle between turns — send messages to wake them

When to Use Teams vs Subagents (Decision Matrix)

• "Research 4 topics in parallel" → Subagents (independent, no coordination needed)
• "Build a feature spanning API + UI + tests with shared state" → Teams (cross-layer, needs coordination)
• "Run 10 file updates with same pattern" → Subagents (parallel, identical, independent)
• "Debug a complex issue with competing hypotheses" → Teams (need to share findings, adjust approach)

6. Parallel Task Dispatch

1. Create N Task() calls in a single message (parallel launch)
2. Each agent gets one unit of work
3. Results collected when all complete

Effort-Level Scaling

Two-Tier Delegation (Lightweight vs Full)

Lightweight Delegation

• Use model="haiku" for cost/speed efficiency
• Set max_turns=3 — if it can't finish in 3 turns, it needs full delegation
• Provide all input inline in the prompt (no tool use expected)
• Examples: "Classify this text as X/Y/Z", "Extract the 5 key points from this", "Summarize this in 2 sentences"

Full Delegation

• Default model (sonnet/opus inherited from parent)
• No max_turns restriction — agent iterates until done
• Agent uses tools autonomously (Read, Grep, Bash, etc.)
• Examples: "Research X and produce a report", "Refactor these 5 files", "Debug why test Y fails"

Decision Rule

Right-Sizing Pre-Gate (PLAN, all tiers)

• (a) Zero-agent check. Is the answer already in working memory, or reachable by Glob+Grep+Read in under 30s, or isolated to a single file? Then 0 agents — do it inline. A subagent isn't free; its setup, context load, and result handling cost more than a direct read.
• (b) Disk-effect probe on every writing agent. An agent that says it wrote or edited files isn't trusted until you confirm it: the file exists AND the diff is non-empty (Read / git diff / Grep the claimed change). A "completed" report is a claim, not evidence. Rule 1 Live-Probe binds delegates exactly as it binds the primary.
• (c) Budget reservation above ~8 agents. A fan-out past ~8 concurrent agents must reserve explicit verification budget — you can't spend it all generating and none confirming — and name a non-agent fallback branch in ## Decisions for when the wave comes back unusable. This bounds the 5-level nesting capability: nesting multiplies agent count, so the ceiling is on the whole tree, not just the top layer.

Anti-Patterns (Don't Do These)

• Don't delegate what Grep/Glob/Read can do in <2 seconds
• Don't spawn agents for single-file changes
• Don't create teams for fewer than 3 independent workstreams
• Don't send agents work without full context — they start fresh
• Don't use built-in agent names for custom agents
• Don't use built-in agent types when user asks for specialized or custom agents — always use ComposeAgent via the Agents skill
• Don't use full delegation for one-shot extraction/classification — use lightweight tier

Gotchas

• Delegation uses Claude Code's built-in TeamCreate — NOT the Agents skill's ComposeAgent. These are different systems.
• 3+ independent workstreams warrant delegation. For 1-2 tasks, direct work is faster than team coordination overhead.
• Agent teams share a task list. Use TaskCreate/TaskUpdate for coordination, not ad-hoc messages.
• Teams overkill for single-file tasks. (Mar 2026 reflection: "one agent that can both read code and write JSX is better than three specialists who can't coordinate")
• Forked subagents inherit the full main-thread conversation + share its prompt cache (Anthropic CC v2.1.133+, enabled via CLAUDE_CODE_FORK_SUBAGENT=1 env or agent frontmatter context: fork). Use forked subagents for nuance-dependent work: design variations, follow-on research, anything that depends on context the main thread already established. DO NOT FORK for code review — a forked reviewer defends its own code (R Amjad: "biased toward defending own code"). For convergence questions, run one fork + one non-fork in parallel and look at where they disagree.

Examples

User: "build the frontend and backend in parallel"
→ Creates team via TeamCreate
→ Spawns frontend and backend agents
→ Shared task list for coordination
→ Agents work independently, merge results

User: "launch an agent team to research these 5 topics"
→ Creates team with 5 research agents
→ Each agent handles one topic independently
→ Results synthesized by team lead

Execution Log

echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Delegation","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' >> ~/.claude/LIFEOS/MEMORY/SKILLS/execution.jsonl