subagent-teams

<quick_start> Research fan-out:

Launch 3 Explore agents in parallel:
- Agent 1: Search for authentication patterns
- Agent 2: Search for database schema
- Agent 3: Search for API endpoints

Implementation fan-out:

1. Plan agent designs architecture
2. 3 general-purpose agents build components in parallel
3. code-reviewer agent validates all changes

</quick_start>

<success_criteria>

• Subagents spawned with correct model tiers (Haiku for search/review, Sonnet for code, Opus for architecture)
• Parallel agents complete independently without conflicting file edits
• Fan-in synthesis captures key findings from all background agents
• Total parallel agents stays within 5-7 limit to avoid context overflow
• TaskCreate/TaskUpdate used for progress tracking with live UI spinners </success_criteria>

---

When to Use This vs agent-teams

Factor	subagent-teams (this)	agent-teams
Isolation	Shared codebase, shared context	Full worktree isolation
Overhead	Lightweight — just Task tool calls	Heavy — terminals, git branches, ports
Best for	Research, review, doc updates	Feature builds, conflicting file edits
Max agents	5-7 (context limit)	2-3 (M1 8GB RAM limit)
Duration	Minutes	Hours
Coordination	TeamCreate + TaskList/TaskUpdate	WORKTREE_TASK.md + git branches

Rule of thumb: If agents will edit the same files → use agent-teams (worktree isolation). If agents read-only or edit different files → use subagent-teams (faster, lighter).

---

Task Tool Parameters (Complete Reference)

Core Parameters

{
  subagent_type: "Explore" | "general-purpose" | "Plan" | ...,
  model: "haiku" | "sonnet" | "opus",
  prompt: "...",
  description: "3-5 word summary",        // Required
  run_in_background: true,                 // For parallel execution
  team_name: "my-team",                    // Scope to a team's task list
  name: "agent-1",                         // Name for team messaging
  mode: "default"                          // Permission mode (see below)
}

Agent Frontmatter Fields (for .md agent files)

Field	Type	Purpose
name	string	Agent identifier
description	string	What the agent does (shown in routing)
model	string	Default model: haiku, sonnet, opus
tools	list	Allowed tools (restrict agent capabilities)
disallowedTools	list	Explicitly blocked tools
permissionMode	string	default, acceptEdits, dontAsk, plan
mcpServers	list	MCP servers available to the agent
hooks	object	Event-driven automation (PostToolUse, etc.)
maxTurns	number	Max API round-trips before stopping
skills	list	Skills available to the agent
memory	object	Persistent state (see Memory Scopes below)

Memory Scopes

The memory field gives agents persistent state across sessions:

# User-scoped: shared across all projects for this user
memory:
  scope: user    # Stored in ~/.claude/agent-memory/

# Project-scoped: shared across sessions within one project
memory:
  scope: project # Stored in .claude/agent-memory/

# Local-scoped: private to this machine + project combo
memory:
  scope: local   # Stored in .claude/local/agent-memory/

When to use: user for personal preferences/patterns. project for shared team knowledge. local for machine-specific paths or credentials.

Background Execution

Use run_in_background: true for agents that don't block your next action:

// Launch in background — returns immediately with output_file path
Task({
  subagent_type: "Explore",
  prompt: "Search for all auth patterns",
  run_in_background: true  // Non-blocking
})

// Check results later
TaskOutput({ task_id: "agent-id", block: false })  // Non-blocking check
TaskOutput({ task_id: "agent-id", block: true })    // Wait for completion

Foreground vs background:

• Foreground (default): Use when you need results before proceeding — research that informs next steps
• Background: Use when you have independent work to do in parallel — observers, linters, long searches

Tip: Background agents are ideal for observer-lite/observer-full, security scans, and parallel research where you can synthesize results later.

Permission Modes

Mode	Behavior
default	Normal approval flow
acceptEdits	Auto-approve file edits, prompt for Bash
dontAsk	Auto-approve everything (use with trusted agents)
plan	Agent must get plan approved before implementing
delegate	Agent can only delegate to sub-agents

Spawning Restrictions

Restrict which subagents an agent can spawn using Task(agent_type) in the tools field:

tools:
  - Read
  - Glob
  - Task(Explore)        # Can only spawn Explore subagents
  - Task(code-reviewer)  # Can also spawn code reviewers

Built-in agent types and their tool access:

Agent Type	Tools	Best For
Explore	Glob, Grep, Read, LS, WebFetch, WebSearch	Fast codebase search (read-only)
Plan	Glob, Grep, Read, LS, WebFetch, WebSearch	Architecture design (read-only)
general-purpose	All tools	Implementation, full access
feature-dev:code-reviewer	Glob, Grep, Read, LS, WebFetch	Code review (read-only)
feature-dev:code-explorer	Glob, Grep, Read, LS, WebFetch	Deep feature analysis (read-only)
feature-dev:code-architect	Glob, Grep, Read, LS, WebFetch	Architecture blueprints (read-only)
observer-lite	Read, Glob, Grep, Bash, Write	Quick quality checks
observer-full	Read, Glob, Grep, Bash, Write	Full drift detection

Custom agents: Define in .claude/agents/*.md with frontmatter. Reference by filename (without .md).

Model Selection Guide

Task	Model	Why
File search, pattern matching	haiku	Fast, cheap, sufficient
Code review, bug finding	haiku	Pattern matching, not generation
Code generation, refactoring	sonnet	Quality matters for code
Architecture decisions	opus	Complex reasoning needed
Documentation writing	sonnet	Needs context understanding

---

Team Patterns

1. Research Team (3 Explore agents)

Fan-out 3 search strategies, fan-in to synthesize:

Task 1 (Explore, haiku): "Search for [pattern] in src/"
Task 2 (Explore, haiku): "Search for [pattern] in tests/"
Task 3 (Explore, haiku): "Search for [pattern] in docs/"
→ Fan-in: Synthesize findings into summary

When: Exploring unfamiliar codebase, understanding how a feature works across layers.

2. Implement Team (architect → builders → reviewer)

Sequential pipeline with parallel build phase:

Phase 1: Plan agent designs architecture (1 agent)
Phase 2: 2-3 general-purpose agents build components (parallel)
Phase 3: code-reviewer validates (1 agent)

When: Building a feature with multiple independent components.

3. Review Team (3 reviewers in parallel)

Task 1 (code-reviewer, haiku): "Review src/auth/ for security"
Task 2 (code-reviewer, haiku): "Review src/api/ for consistency"
Task 3 (code-reviewer, haiku): "Review src/db/ for performance"
→ Fan-in: Aggregate findings, deduplicate

When: Pre-PR review of large changesets.

4. Explore Team (3 search strategies)

Task 1 (Explore, haiku): Glob for file patterns
Task 2 (Explore, haiku): Grep for code patterns
Task 3 (Explore, haiku): Read key entry points
→ Fan-in: Build mental model of codebase area

When: First time working in a new area of the codebase.

5. Doc Team (N independent file updaters)

Task 1 (general-purpose, haiku): "Update README.md with new API"
Task 2 (general-purpose, haiku): "Update CHANGELOG.md"
Task 3 (general-purpose, haiku): "Update API docs"
→ No fan-in needed (independent files)

When: Updating multiple independent documentation files.

---

Progress Rendering

Native Progress (TaskCreate/TaskUpdate)

Use TaskCreate with activeForm for live UI spinners during execution:

// Create tasks for each agent's work
TaskCreate({ subject: "Search auth patterns", activeForm: "Searching auth patterns" })
TaskCreate({ subject: "Search DB schema", activeForm: "Searching DB schema" })
TaskCreate({ subject: "Search API endpoints", activeForm: "Searching API endpoints" })

// Track status transitions
TaskUpdate({ taskId: "1", status: "in_progress" })  // → shows spinner
TaskUpdate({ taskId: "1", status: "completed" })     // → shows checkmark

Task Dependencies (Sequential Phases)

Use addBlockedBy to sequence phases:

// Phase 1: Architecture (runs first)
TaskCreate({ subject: "Design architecture" })  // → task #1

// Phase 2: Implementation (blocked by Phase 1)
TaskCreate({ subject: "Build backend" })   // → task #2
TaskCreate({ subject: "Build frontend" })  // → task #3
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["1"] })

// Phase 3: Review (blocked by Phase 2)
TaskCreate({ subject: "Code review" })  // → task #4
TaskUpdate({ taskId: "4", addBlockedBy: ["2", "3"] })

Summary Rendering (Markdown)

After all agents complete, render a markdown summary:

## Research Complete: 3/3 agents finished

| Agent | Scope | Findings | Time |
|-------|-------|----------|------|
| Auth search | src/auth/ | 12 files, JWT + session | 8s |
| DB search | src/db/ | 8 tables, RLS policies | 5s |
| API search | src/api/ | 15 endpoints, REST | 6s |

### Key Insights
- [Synthesized finding 1]
- [Synthesized finding 2]

---

Team Coordination (Native Agent Teams API)

For complex multi-agent work, use the native Teams API:

// Create a team with shared task list
TeamCreate({ team_name: "research-sprint" })

// Spawn teammates into the team
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-1" })
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-2" })

// Teammates coordinate via shared TaskList
// Send messages between teammates
SendMessage({ type: "message", recipient: "searcher-1", content: "Focus on auth/" })

// Shutdown when done
SendMessage({ type: "shutdown_request", recipient: "searcher-1" })

---

Prompt Templates

Research Spawn

Search the codebase for [PATTERN]. Look in [SCOPE].
Report: file paths, line numbers, and a 2-sentence summary of each match.
Do NOT modify any files.

Build Spawn

Implement [COMPONENT] in [FILE_PATH].
Requirements: [SPEC]
Follow existing patterns in [EXAMPLE_FILE].
Write code only — do not run tests.

Review Spawn

Review [FILE_PATH] for [CONCERN: security|performance|consistency].
Report only HIGH confidence issues.
Format: file:line — issue — suggestion

---

Constraints

• Max 5-7 parallel agents — beyond this, context window fills up
• No conflicting file edits — if agents might edit the same file, use agent-teams instead
• Fan-in is manual — you (team lead) synthesize results from background agents
• Background agents can't see each other — design tasks to be independently completable

Deep dive: See reference/task-tool-guide.md, reference/team-patterns.md, reference/prompt-templates.md