init

.opencode/skills/team/references/agent-teams-examples-and-best-practices.md

@@ -0,0 +1,220 @@
+# Agent Teams -- Examples, Best Practices & Troubleshooting
+
+> **Source:** https://code.claude.com/docs/en/agent-teams
+> **Version captured:** Claude Code v2.1.80 (March 2026)
+
+## Use Case Examples
+
+### Parallel Code Review
+
+```
+Create an agent team to review PR #142. Spawn three reviewers:
+- One focused on security implications
+- One checking performance impact
+- One validating test coverage
+Have them each review and report findings.
+```
+
+Each reviewer applies different filter to same PR. Lead synthesizes across all three.
+
+### Competing Hypotheses Investigation
+
+```
+Users report the app exits after one message instead of staying connected.
+Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
+each other to try to disprove each other's theories, like a scientific
+debate. Update the findings doc with whatever consensus emerges.
+```
+
+Adversarial debate structure fights anchoring bias -- surviving theory is most likely correct.
+
+### Parallel Feature Implementation (with Worktree Isolation)
+
+```
+Create a team to implement the new dashboard feature.
+Developer A owns src/api/* and src/models/*.
+Developer B owns src/components/* and src/pages/*.
+Tester writes tests after both devs finish.
+Require plan approval for developers.
+Use worktree isolation for each developer.
+```
+
+Each developer works in isolated worktree -- own branch, own working directory. No file conflicts even if ownership boundaries overlap accidentally. Tester blocked until both complete.
+
+## Best Practices
+
+### Give Enough Context
+
+Teammates don't inherit lead's conversation. Include details in spawn prompt:
+
+```
+Spawn a security reviewer with prompt: "Review src/auth/ for vulnerabilities.
+Focus on token handling, session management, input validation.
+App uses JWT in httpOnly cookies. Report with severity ratings."
+```
+
+### Size Tasks Right
+
+- **Too small**: coordination overhead exceeds benefit
+- **Too large**: teammates work too long without check-ins
+- **Right**: self-contained units with clear deliverable (function, test file, review)
+
+### Start with Research/Review
+
+If new to agent teams, start with read-only tasks (reviewing PRs, researching libraries, investigating bugs). Shows parallel value without coordination challenges of parallel implementation.
+
+### Use Worktree Isolation for Code Changes
+
+For any template where teammates edit code (cook, fix), always use `isolation: "worktree"`:
+
+```
+Agent(
+  subagent_type: "fullstack-developer",
+  model: "opus",
+  isolation: "worktree",
+  run_in_background: true,
+  prompt: "..."
+)
+```
+
+**Benefits:**
+- Each dev gets own git worktree + branch
+- No file conflicts -- devs can edit same files independently
+- `.git` dir shared (common config), everything else isolated
+- Lead merges branches after all devs complete
+
+**When NOT to use:** Research and review templates (read-only, no file edits).
+
+### Spawn with run_in_background
+
+Always use `run_in_background: true` when spawning multiple teammates:
+
+```
+# Spawn all 3 researchers concurrently (non-blocking)
+Agent(subagent_type: "researcher", run_in_background: true, ...)
+Agent(subagent_type: "researcher", run_in_background: true, ...)
+Agent(subagent_type: "researcher", run_in_background: true, ...)
+```
+
+Lead continues orchestration immediately. TaskCompleted events notify when each finishes.
+
+### Wait for Teammates
+
+If lead starts implementing instead of delegating:
+```
+Wait for your teammates to complete their tasks before proceeding
+```
+
+### Avoid File Conflicts
+
+Two teammates editing same file = overwrites. Mitigate with:
+1. **Worktree isolation** (recommended) -- each dev in own worktree
+2. **File ownership boundaries** -- define glob patterns per task
+3. **Lead handles shared files** -- restructure tasks if overlap unavoidable
+
+### Monitor & Steer
+
+Check progress regularly. Redirect bad approaches. Synthesize findings as they arrive. Letting a team run unattended too long increases wasted effort risk.
+
+### File Ownership Enforcement
+
+- Define explicit file boundaries in each task description
+- Include glob patterns: `File ownership: src/api/*, src/models/*`
+- If two tasks need same file: use worktree isolation OR escalate to lead
+- Tester owns test files only; reads implementation files but never edits them
+
+### Leverage Event-Driven Hooks
+
+With `TaskCompleted` and `TeammateIdle` hooks enabled:
+
+- Lead is automatically notified when tasks complete -- no manual polling needed
+- Progress is tracked via hook-injected context: "3/5 tasks done, 2 pending"
+- Idle teammates trigger suggestions: "worker-2 idle, 1 unblocked task available"
+- All tasks done triggers: "Consider shutting down teammates and synthesizing"
+
+**Cook workflow example:**
+```
+1. Lead spawns 3 devs (run_in_background: true, isolation: "worktree")
+2. TaskCompleted(dev-1, task #1) -> "1/4 done"
+3. TaskCompleted(dev-2, task #2) -> "2/4 done"
+4. TaskCompleted(dev-3, task #3) -> "3/4 done"
+5. TaskCompleted(dev-1, task #4) -> "4/4 done. All tasks completed."
+6. Lead merges worktree branches, then spawns tester
+```
+
+### Use Agent Memory for Long-Running Projects
+
+For projects with recurring team sessions:
+- Code reviewer learns project conventions, stops flagging known patterns
+- Debugger remembers past failures, faster root-cause identification
+- Tester tracks flaky tests, avoids re-investigating known issues
+- Researcher accumulates domain knowledge across projects (user scope)
+
+Memory persists after team cleanup -- it's in `.opencode/agent-memory/`, not `~/.opencode/teams/`.
+
+### Restrict Sub-Agent Spawning
+
+Use `Task(agent_type)` in agent definitions to prevent:
+- Recursive agent chains (agent spawns agent spawns agent)
+- Cost escalation (teammate spawning expensive sub-agents)
+- Scope creep (tester spawning developer to "fix" issues)
+
+Recommended: Most agents get `Task(Explore)` only. Planner gets `Task(Explore), Task(researcher)`.
+
+## Token Budget Guidance
+
+| Template | Estimated Tokens | Notes |
+|----------|-----------------|-------|
+| Research (3 teammates) | ~150K-300K | Read-only, all Opus |
+| Cook (4 teammates) | ~400K-800K | Highest -- code generation |
+| Review (3 teammates) | ~100K-200K | Read-only, all Opus |
+| Debug (3 teammates) | ~200K-400K | Mixed read/execute |
+
+Agent Teams use significantly more tokens than subagents (all teammates run Opus 4.6). Use only when parallel exploration + discussion adds clear value. For routine tasks, single session with subagents is more cost-effective.
+
+## Troubleshooting
+
+### Teammates Not Appearing
+
+- In-process: press `Shift+Down` to cycle through active teammates
+- Task may not be complex enough -- Claude decides based on task
+- Split panes: verify tmux installed and in PATH
+- iTerm2: verify `it2` CLI installed and Python API enabled
+
+### Too Many Permission Prompts
+
+Pre-approve common operations in permission settings before spawning.
+
+### Teammates Stopping on Errors
+
+Check output via `Shift+Up/Down` or clicking pane. Give additional instructions or spawn replacement.
+
+### Lead Shuts Down Early
+
+Tell lead to keep going or wait for teammates.
+
+### Orphaned tmux Sessions
+
+```
+tmux ls
+tmux kill-session -t <session-name>
+```
+
+### TeamCreate Fails
+
+- Verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set in settings.json env
+- Agent Teams requires CLI terminal -- NOT supported in VSCode extension
+- Only one team per session -- call TeamDelete before creating another
+
+## Limitations
+
+- **Model lock**: All teammates must run Opus 4.6 (no mixed-model teams)
+- **No session resumption**: `/resume` and `/rewind` don't restore in-process teammates
+- **Task status can lag**: teammates may not mark tasks completed; check manually
+- **Shutdown can be slow**: finishes current request first
+- **One team per session**: clean up before starting new one
+- **No nested teams**: only lead manages team
+- **Lead is fixed**: can't promote teammate or transfer leadership
+- **Permissions at spawn**: all inherit lead's mode; changeable after but not at spawn time
+- **Split panes**: require tmux or iTerm2 only
+- **VSCode unsupported**: Agent Teams requires CLI terminal