subagent-teams

What this skill does

<objective>
Orchestrate teams of Task tool subagents within a single Claude Code session. Unlike agent-teams-skill (which uses worktrees + terminals for full parallel sessions), this skill uses the Task tool for lightweight, in-session parallelism with shared codebase access.
</objective>

<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>

<triggers>
- "set up subagent team", "fan out", "parallel tasks", "Task tool team"
- "research in parallel", "explore in parallel", "review in parallel"
- "spawn subagents", "in-session agents"
</triggers>

---

## 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

```javascript
{
  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:

```yaml
# 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:

```javascript
// 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:
```yaml
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 (Explor