init

.opencode/skills/team/references/agent-teams-controls-and-modes.md

@@ -0,0 +1,129 @@
+# Agent Teams -- Controls, Display Modes & Task Management
+
+> **Source:** https://code.claude.com/docs/en/agent-teams
+> **Version captured:** Claude Code v2.1.80 (March 2026)
+
+## Display Modes
+
+- **In-process** (default fallback): all teammates in one terminal. `Shift+Up/Down` to navigate. Works in any terminal.
+- **Split panes**: each teammate gets own pane. Requires tmux or iTerm2.
+
+Default is `"auto"` -- uses split panes if already inside a tmux session, otherwise in-process. The `"tmux"` setting enables split-pane mode and auto-detects tmux vs iTerm2.
+
+```json
+{ "teammateMode": "in-process" }
+```
+
+Per-session override: `claude --teammate-mode in-process`
+
+Split panes NOT supported in: VS Code terminal, Windows Terminal, Ghostty.
+
+**tmux setup:** install via system package manager.
+**iTerm2 setup:** install `it2` CLI, enable Python API in iTerm2 > Settings > General > Magic.
+
+## Model Requirements
+
+All Agent Team teammates must run **Opus 4.6** -- this is a hard constraint. Mixed-model teams (e.g., Sonnet for devs, Haiku for testers) are NOT supported within Agent Teams.
+
+For mixed-model workflows, use **subagents** instead (the `Agent` tool supports `model: "haiku" | "sonnet" | "opus"` per spawn).
+
+## Plan Approval
+
+Require teammates to plan before implementing:
+
+```
+Spawn an architect teammate to refactor the auth module.
+Require plan approval before they make any changes.
+```
+
+**Flow:**
+1. Teammate works in read-only plan mode
+2. Teammate finishes planning -> sends `plan_approval_request` to lead
+3. Lead reviews -> approves via `SendMessage(type: "plan_approval_response", approve: true)`
+4. If rejected: teammate stays in plan mode, revises based on feedback, resubmits
+5. Once approved: teammate exits plan mode, begins implementation
+
+**Influence criteria:** "only approve plans that include test coverage" or "reject plans that modify the database schema"
+
+## Delegate Mode
+
+Restricts lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. No code editing.
+
+Useful when lead should focus entirely on orchestration -- breaking down work, assigning tasks, synthesizing results.
+
+**Enable:** Press `Shift+Tab` after team creation to cycle into delegate mode.
+
+## Direct Teammate Interaction
+
+- **In-process**: `Shift+Up/Down` select teammate, type to message. `Enter` view session. `Escape` interrupt current turn. `Ctrl+T` toggle task list.
+- **Split panes**: click into pane to interact directly. Each teammate has full terminal view.
+
+## Task Assignment & Claiming
+
+Three states: **pending** -> **in_progress** -> **completed**. Tasks can have dependencies -- blocked until dependencies resolve.
+
+- **Lead assigns**: tell lead which task -> which teammate
+- **Self-claim**: after finishing, teammate picks next unassigned, unblocked task automatically
+- **Auto-unblock**: completing a blocking task automatically unblocks dependents
+
+File locking prevents race conditions on simultaneous claiming.
+
+## Worktree Isolation for Implementation
+
+When spawning developer teammates, use `isolation: "worktree"` on the Agent tool:
+
+```
+Agent(
+  subagent_type: "fullstack-developer",
+  model: "opus",
+  isolation: "worktree",
+  run_in_background: true,
+  prompt: "Implement auth module..."
+)
+```
+
+Each dev gets own worktree + branch. No file conflicts during parallel work. Lead merges branches after all devs complete.
+
+**When to use:** Always for cook/implementation templates. Not needed for research/review (read-only).
+
+## Background Spawning
+
+Use `run_in_background: true` on the Agent tool to spawn teammates non-blocking:
+
+- Lead continues orchestration while teammates work
+- Automatic notification when teammate completes
+- No polling needed -- TaskCompleted hook fires on completion
+- Use TaskList as fallback if no events in 60s
+
+## Shutdown
+
+```
+Ask the researcher teammate to shut down
+```
+
+Teammate can approve (exit) or reject with explanation. Teammates finish current request/tool call before shutting down -- can be slow.
+
+## Cleanup
+
+After all teammates shut down, call `TeamDelete` (no parameters). Fails if active teammates still exist.
+
+Removes shared team resources (`~/.opencode/teams/` and `~/.opencode/tasks/` entries).
+
+## Hook-Based Orchestration
+
+### Event-Driven Monitoring
+
+Instead of polling TaskList, lead receives automatic context injection:
+
+- **TaskCompleted** -- fires when any teammate completes a task. Lead gets progress counts.
+- **TeammateIdle** -- fires when teammate turn ends. Lead gets available task info.
+
+### Recommended Pattern
+
+1. Lead creates tasks and spawns teammates (with `run_in_background: true`)
+2. TaskCompleted hook notifies lead as tasks finish (progress: N/M)
+3. TeammateIdle hook suggests reassignment or shutdown
+4. Lead acts on suggestions (spawn tester, shut down, reassign)
+5. Fallback: Check TaskList manually if no events received in 60s
+
+This replaces the "poll TaskList every 30s" pattern with reactive orchestration.