AC
Agent Ops & Meta4.8 KBMIT licensed

dispatching-parallel-agents

Rewritten from patterns in obra/superpowers (MIT)

Split independent problems across parallel subagents with focused, self-contained prompts, then integrate their results. Use when 2+ tasks share no state and no ordering, like unrelated test failures across different files or independent subsystem bugs. Not for related failures where one fix may cascade: investigate those in one thread. Not for adversarial review of a single decision: use doubt-driven-development. Not for trimming your own context: use context-budget.

  • dispatching
  • parallel
  • agents

SKILL.md

Dispatching Parallel Agents

One agent per independent problem domain, all dispatched at once. Subagents get a constructed context, not your session history, which keeps them focused and keeps your own context free for coordination.

The Independence Test

Parallelize only when every answer is yes:

  1. Can each problem be understood without the others?
  2. Is there no shared state (same files, same fixtures, same resources)?
  3. Could fixing one never fix or break another?
  4. Do you already know what is broken, roughly where?

Any no: do not parallelize. Related failures get one investigator. Exploratory debugging (you do not know what is broken yet) gets you, not a fleet.

Workflow

  1. Group by domain. Cluster the failures by what is actually broken: one test file, one subsystem, one bug class per group. Three test files failing for three unrelated reasons is three domains.
  2. Write one prompt per domain. Each prompt is self-contained: the agent inherits nothing from your session. Include the exact scope (file paths, test names), the pasted error output, the goal, hard constraints, and the required return format.
  3. Dispatch all at once. Issue every subagent call in the same message. Same message means parallel; one per message means sequential and you lose the entire point.
  4. Integrate. When they return: read each summary, diff-check for overlapping edits, run the full test suite yourself, and spot-check the reasoning. Subagents make confident systematic errors; the suite is the referee, not their summaries.

Prompt Anatomy

Every dispatch prompt carries five parts:

  • Scope: "Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts", never "fix the tests".
  • Evidence: paste the failing test names and error messages. The agent cannot see your terminal.
  • Goal: what done looks like, stated observably.
  • Constraints: what the agent must not touch. "Do not modify production code" or "fix the root cause, do not raise timeouts".
  • Return contract: "Return: root cause, files changed, and what you fixed."

Verification

After integration, run the full test suite and git diff --stat. Expect: all tests green, and no file appearing in more than one agent's changes. If two agents touched the same file, review that file line by line before trusting the merge; if the suite is red, re-dispatch a single agent scoped to the regression with the new failure output pasted in.

Good vs Bad

Judgment call: prompting a subagent on a flaky-looking test failure.

Bad: "Fix the race condition in the agent tests." No file, no errors, no constraints. The agent wanders, refactors production code, and returns "fixed" with timeouts doubled.

Good: "Fix the 3 failures in agent-tool-abort.test.ts (names and errors pasted below). Likely timing issues. Replace arbitrary timeouts with event-based waiting, or fix the abort implementation if it is actually buggy. Do NOT just increase timeouts. Return root cause and changes." Scoped, evidenced, constrained.

Footguns

  • Sequential dispatch by accident. Calls in separate messages run one after another. Fix: all dispatch calls in one message, every time.
  • Shared-file collisions. Two agents editing the same helper produce a silent bad merge. Fix: check domain boundaries for shared files before dispatch; if unavoidable, serialize those two.
  • Trusting summaries over the suite. "All tests pass" from a subagent means its slice passed in its view. Fix: you run the full suite after integration, always.
  • Parallelizing related failures. One root cause, three agents, three conflicting patches. Fix: apply the independence test first; when in doubt, one investigator does a quick triage pass.
  • Context dumping. Pasting your whole session into each prompt burns tokens and blurs focus. Fix: construct the minimal context each agent needs, nothing more.

Completion Checklist

  • [ ] Independence test passed for every domain
  • [ ] Each prompt has scope, evidence, goal, constraints, return contract
  • [ ] All dispatches issued in a single message
  • [ ] No overlapping file edits, or overlaps reviewed line by line
  • [ ] Full suite run by you after integration, green

Any box unchecked: not done. Fix or say so.

More in Agent Ops & Meta

agent-recipe-builderDesign a reusable multi-skill recipe, a documented loop blueprint that sits between a one-off skill and a scheduled auto...agent-self-evaluationSelf-rate completed work on five axes (accuracy, completeness, clarity, actionability, conciseness) with cited evidence ...ai-tool-directiveWrite structured directives for AI coding tools so fixes remove old code, respect scope, and verify. Use when delegating...
All skills