aromanarguello/parallel-subagents

Parallel Subagents

Orchestrate multiple subagents for ad-hoc parallel work: research, quick tasks, or test execution.

Core principle: One focused agent per topic, all dispatched in a single message, results synthesized after.

When to Use This Skill vs Others

Have a written plan? ──yes──> Use subagent-driven-development
       │
       no
       │
       ▼
2+ independent tasks? ──no──> Sequential execution
       │
       yes
       │
       ▼
Tasks share state? ──yes──> Sequential execution
       │
       no
       │
       ▼
   ┌─────────────────────┐
   │ parallel-subagents  │
   └─────────────────────┘

| Skill | Purpose | When to Use | |-------|---------|-------------| | parallel-subagents | Quick parallel dispatch for research, investigation, or running tests | Ad-hoc parallel tasks, no plan exists, gathering information | | subagent-driven-development | Sequential implementation with two-stage review gates | Executing a written plan, task-by-task with spec + quality review | | dispatching-parallel-agents | Debugging multiple independent failures | 3+ test failures in different files/subsystems |

Mode Selection

| Mode | Subagent Type | Model | Use When | |------|---------------|-------|----------| | Research | Explore | haiku | Investigating codebase, gathering info, understanding patterns | | Quick tasks | general-purpose | sonnet | Small independent tasks, no formal review needed | | Testing | general-purpose | haiku | Running test suites across packages |

The Pattern

1. Identify Independent Tasks

List what needs to happen. Verify independence:

• Can each complete without results from others? ✓
• No shared files being edited? ✓
• No sequential dependencies? ✓

2. Scope Each Task

Each agent gets:

• Specific focus: One topic/file/feature
• Clear deliverable: What to return
• Constraints: What NOT to explore/touch

Bad scope: "Investigate the codebase" (infinite) Good scope: "Find how authentication middleware validates JWTs" (bounded)

3. Dispatch in Parallel

Critical: Single message, multiple Task tool calls!

All Task tool invocations must be in the same response to achieve true parallelism. Sequential messages = sequential execution.

4. Synthesize Results

After all agents return:

• Read each summary
• Identify patterns across findings
• Note conflicts or inconsistencies
• Create unified understanding
• Identify gaps for follow-up

Research Mode Template

Use Explore agents (haiku, read-only) for investigation:

Task tool:
  subagent_type: Explore
  model: haiku
  description: "Research [topic]"
  prompt: |
    Investigate [specific topic] in this codebase.

    Focus on:
    - [Specific question 1]
    - [Specific question 2]

    Return:
    - Key findings (files, patterns, conventions)
    - Code examples with file:line references
    - Gaps or areas needing deeper investigation

Quick Tasks Mode Template

Use general-purpose agents for small independent work:

Task tool:
  subagent_type: general-purpose
  model: sonnet
  description: "Implement [task]"
  prompt: |
    [Task description]

    This is a quick standalone task. Implement, test, commit.

    Return: What you did, files changed, any issues.

Note: For tasks requiring spec compliance review and code quality review, use subagent-driven-development instead.

Testing Mode Template

Run tests across packages in parallel:

Task tool:
  subagent_type: general-purpose
  model: haiku
  description: "Run [package] tests"
  prompt: |
    Run tests for [package/area].

    Command: [test command]

    Return: Pass/fail count, any failures with error messages.

Quick Reference

| Scenario | Action | |----------|--------| | "Research auth, db, and api patterns" | 3 Explore agents in parallel | | "Run all test suites" | 1 agent per package in parallel | | "Implement these 3 independent functions" | 3 general-purpose agents in parallel | | "Execute this 5-step implementation plan" | Use subagent-driven-development | | "Fix 4 failing test files" | Use dispatching-parallel-agents |

Red Flags

| Mistake | Why It's Wrong | |---------|----------------| | Sequential dispatch | Using multiple messages instead of one defeats parallelism | | Vague scope | "Look into the codebase" has no bounds - agents will explore forever | | Dependent tasks | Task B needs Task A's result → must run sequentially | | Overlapping edits | Multiple agents editing same files → merge conflicts | | Skipping synthesis | Results come back but you move on without integrating findings | | Using for plan execution | You have a plan → use subagent-driven-development |

Example: Parallel Research

User asks: "Research how auth, database, and API work in this codebase"

Dispatch (single message with 3 Task calls):

Task 1:
  subagent_type: Explore
  model: haiku
  description: "Research auth patterns"
  prompt: |
    Investigate authentication in this codebase.
    Focus on: middleware, decorators, JWT handling, session management.
    Return: Key files, patterns used, code examples with file:line refs.

Task 2:
  subagent_type: Explore
  model: haiku
  description: "Research database layer"
  prompt: |
    Investigate the database layer in this codebase.
    Focus on: ORM used, schema location, query patterns, migrations.
    Return: Key files, patterns used, code examples with file:line refs.

Task 3:
  subagent_type: Explore
  model: haiku
  description: "Research API conventions"
  prompt: |
    Investigate API conventions in this codebase.
    Focus on: route structure, controllers/handlers, validation, error handling.
    Return: Key files, patterns used, code examples with file:line refs.

After agents return: Synthesize findings into unified architecture understanding.

Example: Parallel Tests

User asks: "Run all test suites"

Dispatch (single message):

Task 1:
  subagent_type: general-purpose
  model: haiku
  description: "Run API tests"
  prompt: Run `pnpm api:test` and report pass/fail counts with any failures.

Task 2:
  subagent_type: general-purpose
  model: haiku
  description: "Run web tests"
  prompt: Run `pnpm --filter web test` and report pass/fail counts with any failures.

Task 3:
  subagent_type: general-purpose
  model: haiku
  description: "Run clips tests"
  prompt: Run `pnpm clips:test` and report pass/fail counts with any failures.

After agents return: Aggregate results into test summary.