When And How To Run Parallel Agents

When And How To Run Parallel Agents

Parallel agents are for independent problem domains, not for making one confused workflow noisier.

Use this skill to decide whether work can be split safely, then define focused agent tasks with clear contracts and integrate their results deliberately.

For coding-related work, load engineering-principles before this skill and tell coding subagents to load it before their focused task skills.

engineering-principles
  -> planning-implementation / clear task batch
  -> when-and-how-to-run-parallel-agents  (you are here)
       -> independent?
            ├── no  -> sequence work
            └── yes -> executing-plans-with-subagents
                         -> inspect reports and changed files
                         -> doing-code-review       (when warranted)
                         -> receiving-code-review   (if findings need handling)
                         -> integrated verification
                         -> verification-before-completion

Core Rule

Dispatch one agent per independent problem domain.

Do not parallelize tasks where one task depends on another task's output.

Parallelizable:
  Agent A investigates auth test failures
  Agent B investigates billing test failures
  Agent C checks docs for deployment config

Not parallelizable:
  Agent A researches a library API
  Agent B implements code using that library API
  -> B must wait for A's result

When To Use

Use parallel agents when at least two units of work are independent:

• multiple test failures in unrelated subsystems
• independent research questions
• separate verification passes such as accessibility, security, and behavior
• separate implementation slices that do not share files or state
• plan review and source research that can happen before implementation starts
• one agent can inspect docs while another inspects local code, then you merge both findings

Avoid parallel agents when work is sequential, tightly coupled, or needs one shared mental model.

Independence Test

Before dispatching, answer these questions.

Dependency examples:

Research -> implementation
  Agent 1: research library docs
  Agent 2: implement library usage
  Result: sequential. Implementation waits for research.

Foundation -> extension
  Agent 1: create user settings page
  Agent 2: add password change form inside settings
  Result: sequential. Form waits for page structure.

Contract -> parallel backend/frontend
  Agent 1: define API contract
  Agent 2: implement backend
  Agent 3: implement frontend
  Result: contract first, then backend/frontend can parallelize.

Dispatch Pattern

1. Group work into domains
        │
        ▼
2. Check independence and dependencies
        │
        ├── related / sequential -> do not parallelize
        │
        ▼
3. Write focused task contracts
        │
        ▼
4. Dispatch agents concurrently
        │
        ▼
5. Read results and check conflicts
        │
        ▼
6. Integrate, verify, and decide next step

The orchestrator owns the merge. Do not let subagents silently coordinate by editing overlapping state unless the task explicitly gives them that protocol.

Prompt Contract

Each agent prompt should be self-contained and narrow.

Agent task contract
├── Scope: exactly what to inspect or change
├── Goal: what outcome is expected
├── Inputs: files, errors, docs, plan sections, constraints
├── Boundaries: what not to touch
├── Verification: what to run or check, if applicable
└── Output: specific summary format expected by orchestrator

Example:

Investigate and fix failing tests in `tests/auth/session.test.ts` only.

Goal:
- Identify the root cause of the session timeout failures.
- Fix only this failure domain if the fix is local to auth/session code.

Constraints:
- Do not modify billing, settings, or unrelated test helpers.
- Do not increase arbitrary timeouts as the first fix.
- If the root cause appears shared outside auth/session, stop and report that.

Verification:
- Run the focused auth/session test if you change code.

Return:
- Root cause
- Files changed
- Verification output
- Any conflicts or follow-up risks

Integration Step

Parallel work is not complete when agents return. The orchestrator must merge their findings.

For each result:
  read summary
  inspect changed files or evidence
  check overlap with other agents
  classify conflicts / dependencies discovered late
  run appropriate integrated verification

When Not To Use

Do not dispatch parallel agents when:

• the failures likely share one root cause
• the tasks are a chain, not a set
• one task needs another task's output
• agents would edit the same files without a defined merge protocol
• the whole point is to understand one system-wide interaction
• exploratory debugging has not yet identified separable domains
• the setup cost of parallelization is larger than the task

Bad split:
  Agent A: refactor settings page layout
  Agent B: add password form inside settings page
  Agent C: update settings page tests

Why bad:
  This will cause edits race. The form and tests depend on the page structure. Define or implement the page
  structure first, then parallelize follow-up work if still useful.

Common Mistakes

Handoff

Use this skill to decide and dispatch. Then hand off based on outcome:

Independent findings integrated cleanly
  -> continue incremental-implementation or integrated verification

Shared root cause discovered
  -> systematic-debugging

Architecture dependency discovered
  -> architecting-changes or planning-implementation

Plan decomposition was wrong
  -> doubt-early or revise the plan

Final success claim needed
  -> verification-before-completion

When using executing-plans-with-subagents, this skill remains the lower-level decision rule for whether tasks are independent enough to fan out.