vc:team

# Agent Teams - Parallel Orchestration Utility

Coordinate multiple independent Claude Code sessions. Each teammate has own context window, loads project context (CLAUDE.md, skills, agents), communicates via shared task list and messaging.

**Requires:** Agent Teams enabled. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json env.
**Requires:** CLI terminal — `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` and `TeamCreate`/`TeamDelete` are **disabled in VSCode extension** (`isTTY` check). Agent Teams CANNOT run in VSCode.
**Model requirement:** All teammates must run Opus 4.6 (Agent Teams constraint).

## Usage

```
/vc:team <template> <context> [flags]
```

**Templates:** `research`, `execute`, `review`, `debug`

**Flags:**
- `--devs N` | `--researchers N` | `--reviewers N` | `--debuggers N` -- team size
- `--plan-approval` / `--no-plan-approval` -- plan gate (default: on for execute)
- `--delegate` -- lead only coordinates, never touches code
- `--worktree` -- use git worktrees for implementation isolation (default: on for execute)

## Execution Protocol

**Pre-flight (MANDATORY -- merged into step 2 of every template):**
1. Step 2 of every template calls `TeamCreate(team_name: "...", ...)`. Do NOT check whether the tool exists first -- just call it.
2. If the call SUCCEEDS: continue with the template.
3. If the call returns an ERROR or is unrecognized: **STOP. Tell user:** "Agent Teams requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json. Team mode is not available."
4. Do NOT fall back to subagents. `/vc:team` MUST use Agent Teams or abort.
5. Ensure `TeamCreate` was called before spawning teammates -- team association happens via session context.

When activated, first confirm team creation if the user has not already explicitly approved using agent teams for this task.
Do not use this skill to bypass the repo's normal human approval gates.
Execute the tool calls in order only after team usage is approved. Report progress after each major step.

### --delegate Mode

When `--delegate` flag is passed:
- Lead enters delegate mode (`Shift+Tab` after TeamCreate)
- Lead ONLY: spawns teammates, manages tasks, sends messages, synthesizes reports
- Lead NEVER: edits files, runs tests, executes git commands directly
- For execute Step 7 MERGE: spawn a dedicated merge teammate instead of lead doing it
- For all templates: lead coordinates and reports, delegates ALL implementation work

---

## Tool Reference (Quick)

### Agent Tool (spawn teammates)

```
Agent(
  subagent_type: "research-agent" | "execute-agent" | "code-reviewer" | "debugger" | "tester" | ...,
  description: "short task summary",
  prompt: "full instructions + CK Context Block",
  model: "opus",                    # Required for Agent Teams teammates
  run_in_background: true,          # Non-blocking spawn
  isolation: "worktree"             # Git worktree isolation (execute devs)
)
```

**Note:** `Task` was renamed to `Agent` in v2.1.63. Both names work; prefer `Agent` for new code.

### Team Management Tools

| Tool | Purpose | Params |
|------|---------|--------|
| `TeamCreate` | Create team + task list | `team_name`, `description` |
| `TeamDelete` | Remove team resources | *none* -- just call it |
| `TaskCreate` | Create work item | `subject`, `description`, `priority`, `addBlockedBy`, `addBlocks` |
| `TaskUpdate` | Claim/complete task | `taskId`, `status`, `owner`, `metadata` |
| `TaskGet` | Full task details | `taskId` |
| `TaskList` | All tasks (minimal fields) | *none* |
| `SendMessage` | Inter-agent messaging | `type`, `to`/`recipient`, `message` |

### SendMessage Types

| Type | Purpose |
|------|---------|
| `message` | DM to one teammate (requires `recipient`) |
| `broadcast` | Send to ALL teammates (use sparingly) |
| `shutdown_request` | Ask teammate to gracefully exit |
| `shutdown_response` | Teammate approves/rejects shutdown (requires `request_id`) |
| `plan_approval_response` | Lead approves/rejects teammate plan (requires `request_id`) |

---

## CK Context Block

Every teammate spawn prompt MUST include this context at the end:

```
CK Context:
- Work dir: {CK_PROJECT_ROOT or CWD}
- Feature: {CK_FEATURE or "none"}
- Reports: {CK_REPORTS_PATH or "process/general-plans/reports/"}
- Plans: {CK_PLANS_PATH or "process/general-plans/active/"}
- Branch: {CK_GIT_BRANCH or current branch}
- Naming: {CK_NAME_PATTERN or "YYMMDD-HHMM"}
- Active plan: {CK_ACTIVE_PLAN or "none"}
- Commits: conventional (feat:, fix:, docs:, refactor:, test:, chore:)
- Refer to teammates by NAME, not agent ID
```

---

## ON `/vc:team research <topic>` [--researchers N]:

*Coordinates parallel `research-agent` teammates plus shared helper skills where useful.*

IMMEDIATELY execute in order:

1. **Derive N angles** from `<topic>` (default N=3):
   - Angle 1: Architecture, patterns, proven approaches
   - Angle 2: Alternatives, competing solutions, trade-offs
   - Angle 3: Risks, edge cases, failure modes, security
   - (If N>3, derive additional angles from topic context)

2. **CALL** `TeamCreate(team_name: "<topic-slug>")` after user approval to use agent teams

3. **CALL** `TaskCreate` x N -- one per angle:
   - Subject: `Research: <angle-title>`
   - Description: `Investigate <angle> for topic: <topic>. Save report to: {CK_REPORTS_PATH}/research-agent-{N}-{CK_NAME_PATTERN}-{topic-slug}.md. Format: Executive summary, key findings, evidence, contradictions, unresolved questions. Do not recommend implementations. Mark task completed when done. Send findings summary to lead.`

4. **SPAWN** teammates x N via `Agent` tool:
   - `subagent_type: "research-agent"`, `model: "opus"`
   - `run_in_background: true` (non-blocking -- spawn all N concurrently)
   - `name: "research-agent-{N}"`
   - Prompt: task description + CK Context Block

5. **MONITOR** via TaskCompleted hook events + TaskList fallback:
   - TaskCompleted events auto-notify when `research-agent` subagents finish
   - Fallback: Check TaskList if no event rec