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

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)

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

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:

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

Model Selection Guide

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

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-subagent-teams.json:

{"ts":"[UTC ISO8601]","skill":"subagent-teams","version":"1.1.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"agents_spawned":[n],"tasks_completed":[n],"tasks_failed":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.