orchestrate

What this skill does

# Agent Team Skill

Orchestrate teams of Claude Code sessions for parallel work. Parse user input to determine
the pattern and target, then execute the appropriate team workflow.

## Input Parsing

Parse `$ARGUMENTS` to determine:
1. **Pattern**: first word (review, debate, plan, build, research, custom, cleanup)
2. **Target**: remaining text (file path, description, or quoted string)

If no pattern is recognized, ask the user which pattern to use.

## Prerequisites Check

Before creating any team, verify the environment:
```bash
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
```
If not `1`, tell the user to enable it and stop.

## Pattern Workflows

Each pattern follows the same lifecycle:
1. Create team with `Teammate(spawnTeam)`
2. Create tasks with `TaskCreate`
3. Spawn teammates with `Task` tool (team_name + name params)
4. Monitor progress via `TaskList` and incoming messages
5. Synthesize results when all teammates report back
6. Shutdown and cleanup

For pattern-specific teammate prompts, task structures, and configurations,
see [reference/patterns.md](reference/patterns.md).

## Teammate Prompt Template

Every teammate prompt MUST include these steps (learned from testing):

```
You are "{name}", a {role} on the {team-name} team.

Your task: {specific task description with file paths}

Steps:
1. Check TaskList and claim task #{n} (set owner to your name, mark in_progress)
2. {Pattern-specific work steps}
3. Mark task #{n} as completed
4. Send a message to the team lead with a brief summary of your findings
```

For debate/plan patterns, add:
```
5. Send messages to {other teammates by name} to {challenge/review/discuss} their findings
```

## Model Selection

Default to `sonnet` for teammates to manage token costs. Use `opus` only when the user
explicitly requests it or the task requires deep reasoning (architecture, complex debugging).

Pass the model parameter when spawning: `model: "sonnet"` in the Task tool call.

## Shutdown Sequence

Reliable shutdown (handles the known flaky behavior):

1. Send `shutdown_request` to each teammate via SendMessage
2. Wait for `shutdown_approved` messages (up to 30 seconds)
3. If a teammate doesn't respond:
   - Send a direct message nudging them to shut down
   - Send another `shutdown_request`
4. Run `Teammate(cleanup)`
5. If cleanup fails with "active members":
   - Run `rm -rf ~/.claude/teams/{team-name} ~/.claude/tasks/{team-name}`
   - Inform the user that manual cleanup was needed

## Cleanup Command

When `$ARGUMENTS` is "cleanup":
1. Run the shutdown sequence above for all active teammates
2. Report what was cleaned up

## Error Handling

- If `spawnTeam` fails with "already leading team": run `Teammate(cleanup)` first, retry
- If a teammate gets stuck: send Escape hint to user, offer to spawn replacement
- If tasks appear stuck: check if work is done, manually update task status

## Cost Warning

Before spawning teams with 4+ teammates, warn the user:
"This will spawn {N} teammates, each using its own context window. Token usage scales
linearly with team size. Proceed?"