Dispatching Parallel Agents

Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.

When to Use

Use when:

• 3+ test files failing with different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from others
• No shared state between investigations

Don't use when:

• Failures are related (fix one might fix others)
• Need to understand full system state
• Agents would interfere with each other

The Pattern

1. Identify Independent Domains

Group failures by what's broken. Each domain is independent.

2. Create Focused Agent Tasks

Each agent gets:

• Specific scope: One test file or subsystem
• Clear goal: Make these tests pass
• Constraints: Don't change other code
• Expected output: Summary of what you found and fixed

3. Dispatch in Parallel

Run multiple agents concurrently on separate problem domains.

4. Review and Integrate

When agents return:

• Read each summary
• Verify fixes don't conflict
• Run full test suite
• Integrate all changes

Agent Type Selection (MANDATORY)

When spawning subagents, follow this hierarchy — general-purpose is last resort:

Step 1 — Check Agency catalog for a named specialist first:

• Research/analysis → Explore, Trend Researcher
• Frontend/UI → Frontend Developer, UI Designer
• Backend/API → Backend Architect, Data Engineer
• Full-stack feature → Senior Developer, domain-specific PD
• QA/testing → Testing Lead, Evidence Collector
• Security → Security Engineer
• DevOps/infra → DevOps Automator
• Legal/compliance → Legal Compliance Checker

Step 2 — Named skills. Check ~/.claude/skills/INDEX.md for a skill that covers this domain.

Step 3 — Fallback: general-purpose. Only use general-purpose when no catalog agent or skill fits.

Agent Prompt Structure

Good agent prompts are:

1. Focused — One clear problem domain
2. Self-contained — All context needed to understand the problem
3. Specific about output — What should the agent return?

Example:

"Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts: [specific test names and issues]. These are timing/race condition issues. Do NOT just increase timeouts — find the real issue. Return: Summary of what you found and what you fixed."

Common Mistakes

• Too broad: "Fix all the tests" — agent gets lost
• No context: "Fix the race condition" — agent doesn't know where
• No constraints: Agent might refactor everything
• Vague output: "Fix it" — you don't know what changed

Key Benefits

1. Parallelization — Multiple investigations happen simultaneously
2. Focus — Each agent has narrow scope, less context to track
3. Independence — Agents don't interfere with each other
4. Speed — 3 problems solved in time of 1