orchestrate

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:

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.

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