multi-agent

name	multi-agent
description	Use this skill when a task would benefit from parallel execution across multiple AI agents, or when orchestrating leader/worker patterns in WrongStack. Triggers: user says "fan out", "parallel", "delegate", "subagent", "fleet", "coordinator".
version	1.1.0

Multi-Agent Coordination — WrongStack

Overview

Coordinates parallel AI agent execution for tasks that benefit from fanning out. Leader delegates narrow subtasks to workers, collects structured results, and synthesizes a unified output.

Rules

1. Subagents share nothing — no memory, no session state, no variable scope.
2. Leader must aggregate results — don't let worker output go unprocessed.
3. Narrow task scope per subagent — broad tasks cause budget_exhausted.
4. Role must match task — don't use bug-hunter to write docs.
5. Check stopReason on every result: end_turn (clean), budget_exhausted (retry), error (surface), aborted (don't retry).
6. Don't fan out single atomic tasks under 5 tool calls — overhead exceeds benefit.

Patterns

Do

// ✅ Good — narrow, focused task per subagent
batch_tool_use([
  { tool: "delegate", input: { task: "Audit auth/session.ts for null-deref bugs", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "Audit auth/token.ts for null-deref bugs", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "Audit auth/refresh.ts for null-deref bugs", role: "bug-hunter" }},
])

// ✅ Leader passes artifact explicitly
// Subagent B gets subagent A's output as part of the task description

Don't

// ❌ Bad — too broad, will exhaust budget
{ task: "Audit all packages for bugs" }

// ❌ Bad — no aggregation
// Subagents return results, leader pastes raw output without synthesis

// ❌ Bad — role mismatch
{ task: "Write documentation for the API", role: "bug-hunter" }

When to fan out

✅ Good fits:

• "Audit these 50 files for X" — one subagent per chunk of 5-10 files
• "Run tests in all 12 packages" — parallel pnpm test across packages
• "Refactor 3 independent modules" — separate agents for each
• "Review this PR + check the tests + check docs" — three parallel workers

❌ Avoid:

• Single atomic task under 5 tool calls — overhead exceeds benefit
• Tasks requiring shared state — subagents have isolated contexts
• Long sequential dependencies — chain within one agent, don't fan out

Roles

Role	Responsibility	Tools
Leader	Coordinates, delegates, synthesizes	delegate, plan, read
Worker	Executes a narrow subtask	Any needed tools
Reviewer	Validates worker output, approves/rejects	grep, test, read
Architect	Makes design decisions when workers hit ambiguity	read, glob, grep

Delegation patterns

One-shot fan-out (all workers in one turn)

batch_tool_use([
  { tool: "delegate", input: { task: "Audit auth/session.ts for null-deref bugs", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "Audit auth/token.ts for null-deref bugs", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "Audit auth/refresh.ts for null-deref bugs", role: "bug-hunter" }},
])

Fleet pattern (stateful, multiple turns)

delegate → spawn N subagents → assign_task per subagent → await_tasks

Use this when the task has dependencies — subagent 2 waits for subagent 1's artifact.

Communication

Workers return structured results. Read stopReason:

• end_turn — clean finish, check result
• budget_exhausted — task too broad, narrow and retry
• error — infrastructure issue, surface it to user
• aborted — user cancelled, don't retry silently

Result aggregation

Leader collects and synthesizes:

For each worker result:
  - Extract key findings (don't just paste raw output)
  - Deduplicate (multiple workers may find the same issue)
  - Prioritize: critical > high > medium > low
  - Present as unified report

Anti-patterns

• Over-delegation: Firing 50 subagents in one turn — model context explodes, nothing gets done
• Under-delegation: One agent doing everything — defeats the purpose, burns budget
• Role mismatch: Using bug-hunter to write documentation, or refactor-planner for security audits
• Result loss: Subagents return useful data but leader doesn't aggregate — always check result
• Silent failure: budget_exhausted subagent output ignored — partial results are still results

Context sharing

Subagents share nothing — no memory, no session state, no variable scope. If subagent B needs output from subagent A, the leader must pass it explicitly as part of the task description or pass it via a shared file the leader writes before delegating.

Skills in scope

• bug-hunter — parallel file audits
• security-scanner — parallel security scans
• refactor-planner — parallel module analysis
• audit-log — aggregating multiple session analyses

---

collab_debug — Three-Agent Parallel Code Review

collab_debug runs BugHunter + RefactorPlanner + Critic simultaneously on the same file snapshot. All three agents receive the full target context, so the number of files must be kept small.

Target size limit: dynamic, defaults to 30

The file limit is computed in this priority order:

1. maxTargetFiles — explicit override if provided
2. contextWindow — dynamic calculation: floor((contextWindow × 0.4) / 2000)
3. DEFAULT_MAX_TARGET_FILES = 30 — fallback when neither is set

Each of the three agents gets the entire file snapshot as context. With 3 agents × N files, large targets cause:

• Token overflow — context window exhausted
• Timeout failures — session times out before agents finish
• Budget exhaustion — each agent burns through iterations with no progress

contextWindow (tokens)	Calculated limit	Interpretation
200_000 (large model)	40 files	~20-30 recommended
100_000 (typical)	20 files	✅ Comfortable
32_768 (small)	6 files	⚠️ Very limited
not provided	30 files (default)	Safe baseline

The session throws a clear error if the resolved file count exceeds the effective limit.

Correct usage

// ✅ Good — single package, limited files
collab_debug(["packages/core/src/agents/**/*.ts"])

// ✅ Explicit — override limit directly
collab_debug({
  targetPaths: ["packages/core/src/**/*.ts"],
  maxTargetFiles: 15,
})

// ✅ Dynamic — limit computed from contextWindow
collab_debug({
  targetPaths: ["packages/core/src/**/*.ts"],
  contextWindow: 100_000,  // → limit = floor(100000 * 0.4 / 2000) = 20
})

// ❌ Bad — entire monorepo
collab_debug(["packages/**/src/**/*.ts"])

For large codebases

Run package-by-package or module-by-module sessions. Target only the area under review, not the whole repo.