team-work

name	team-work
description	Dynamically compose and run a multi-agent team based on the problem. Analyzes the task, selects appropriate agents, creates a team with task board, and coordinates execution.

Team Work

Compose and run a multi-agent team to solve a problem. Follow this workflow strictly.

Step 1: Analyze the Problem

Before creating any team, classify the work:

Work Type	Agents Needed	Why
Research / exploration	1-3 explore agents	Parallel codebase exploration, fast read-only
Code review / audit	1-2 reviewers + 1 explore	Reviewer finds issues, explore gathers context
Implementation (small)	1 coder	Single agent, no coordination overhead
Implementation (medium)	1 explore + 1 planner + 1 coder	Research → plan → implement pipeline
Implementation (large)	1-2 explore + 1 planner + 1 reviewer + 1-2 coders	Full pipeline with review
Implementation + verification	explore + planner + coder + verification	Full pipeline with adversarial verification at the end
Multi-step reasoning	1 general-purpose	Web research, complex analysis
Mixed (research + implement)	explore + planner + coder	Pipeline: parallel research, then sequential plan → code

Rules:

• Do NOT spawn more than 5 agents — coordination overhead exceeds benefit
• Do NOT spawn a coder until the plan is ready — coders act on plans, not vague instructions
• Prefer fewer agents with clear tasks over many agents with overlapping work
• Use explore agents for ANY read-only parallel work (they're fast and safe)
• Use planner for ANY task that needs a design before implementation
• Use verification after non-trivial implementations (3+ file changes, API/backend work)
• Skip the planner for trivial changes (typo fixes, config tweaks)

Step 2: Choose Your Workflow

MANDATORY GATE — answer before proceeding:

Does any agent need another agent's output to start its work?

• NO → use team_dispatch. STOP reading and go to the team_dispatch section.
• YES → use team_create + team_spawn for the sequential pipeline.

If unsure, the answer is NO. Research, review, and audit tasks are almost always independent.

Simple Workflow: team_dispatch — USE THIS BY DEFAULT

team_dispatch is the preferred tool for parallel batch work. It spawns multiple agents, waits for all of them to finish, and returns all results atomically in a single response. No polling, no message handling, no cleanup needed.

Use team_dispatch when:

• All agents can work independently in parallel (no dependencies between them)
• You want to fan out research, review, or implementation across multiple agents
• You don't need to pass one agent's output to another agent mid-flight

How it works:

1. Analyze the problem (Step 1 above)
2. Call team_dispatch with an array of agents
3. All results arrive together in the tool response
4. Synthesize and act on the results

Example:

team_dispatch({
    agents: [
        { name: "r1", agent: "explore", prompt: "Find all usages of X in src/ ..." },
        { name: "r2", agent: "explore", prompt: "Research the Y pattern in lib/ ..." },
    ],
    timeout: 300
})

Key: Give each agent a SPECIFIC, DETAILED prompt. Don't say "look at the codebase" — say "find all usages of X in src/utils/ and report the file paths, line numbers, and how each usage works."

Advanced Workflow: team_create + team_spawn — for sequential pipelines

Use the manual team workflow when you need sequential pipelines where one agent's output feeds into the next agent's prompt. This gives you full control over ordering, coordination, and inter-agent communication.

Use this when:

• Work has sequential dependencies (research → plan → implement → review)
• You need to synthesize intermediate results before passing them to the next agent
• You want interactive control over the team (interrupting, redirecting agents)

Follow the steps below for the advanced workflow.

Create Team and Task Board

1. Call team_create with a descriptive name
2. Create tasks with task_create BEFORE spawning agents — this is the work backlog
3. Structure tasks with dependencies using addBlockedBy when tasks must run in sequence

Example task structure for a medium implementation:

Task 1: [explore] Research current implementation and gather context
Task 2: [planner] Design implementation plan (blocked by Task 1)  
Task 3: [coder] Implement the plan (blocked by Task 2)
Task 4: [reviewer] Review the implementation (blocked by Task 3)

Spawn Agents in the Right Order

Spawn agents that can start immediately first. Agents auto-claim unblocked tasks from the board.

Pipeline pattern (most common):

1. Spawn explore agents first — they start working immediately on unblocked research tasks
2. Wait for research to complete (their results arrive as follow-up messages)
3. Spawn planner with the research context — give it the explore agents' findings in its prompt
4. Wait for plan
5. Spawn coder with the plan in its prompt
6. Optionally spawn reviewer after coder finishes

Parallel pattern (for independent work):

1. Create independent tasks (no blockedBy dependencies)
2. Spawn all agents at once — each auto-claims a task
3. Wait for all to complete

Key: Give each agent a SPECIFIC, DETAILED prompt. Don't say "look at the codebase" — say "find all usages of X in src/utils/ and report the file paths, line numbers, and how each usage works."

Monitor and Coordinate

• Agent messages arrive as follow-up messages — end your turn and wait for them
• Do NOT use sleep or poll manually — the leader inbox poller delivers messages automatically
• Use /team to check interactive status
• Use agent_output to inspect an agent's recent work
• Use agent_interrupt if an agent is stuck or going in the wrong direction
• When an explore/planner reports back, synthesize their findings and pass them to the next agent in the pipeline

Cleanup

• Call team_delete when all work is complete
• Or let agents auto-stop when no more tasks are available

Available Agents

Agent	Capabilities	Best For
explore	Read-only (disallowed: edit, write)	Fast codebase exploration, finding files by pattern, searching code for keywords. Specify thoroughness: quick/medium/very thorough
reviewer	Read-only (disallowed: edit, write)	Code review with structured output (Critical/Warnings/Suggestions with file:line references)
planner	Read-only (disallowed: edit, write)	Architecture design, step-by-step implementation plans, identifying critical files
coder	Full: all tools	Implementation, refactoring, writing tests, fixing bugs
general-purpose	Full: all tools	Research, multi-step reasoning, complex multi-file tasks
verification	Read-only (disallowed: edit, write)	Adversarial testing — tries to break implementations. Produces PASS/FAIL/PARTIAL verdict with evidence

Anti-Patterns

• Don't use team_create + team_spawn for simple parallel work — use team_dispatch instead; it's simpler and handles all the coordination for you
• Don't poll agent_output when using team_dispatch — results arrive atomically in the tool response; there's nothing to poll
• Don't spawn a coder without a plan — it will explore randomly instead of implementing
• Don't give vague prompts — "implement the feature" fails; "edit src/foo.ts to add function bar() that does X, following the pattern in src/baz.ts" works
• Don't spawn 5 explore agents — 2 is plenty; they step on each other with more
• Don't re-send the initial prompt via send_message after spawning — it's already delivered