dispatching-parallel-agents

Dispatching Parallel Agents

When to Use

• Multiple subsystems broken independently
• No shared state between failures
• Each fix is self-contained
• Parallel work won't create conflicts

When NOT to Use

• Tasks with shared state or sequential dependencies where one fix affects another
• Single-file changes that don't benefit from parallelization overhead
• Sequential workflows where each step depends on the output of the previous step

---

Core Principle

"Dispatch one agent per independent problem domain. Let them work concurrently."

Why Parallel?

• Faster resolution (3 problems in time of 1)
• Focused context per agent
• No context pollution between fixes
• Easy to integrate results

Why Not Always Parallel?

• Related problems need shared context
• Exploration requires system-wide view
• Conflicting changes cause merge issues
• Some fixes depend on others

---

Identification Pattern

Step 1: Group Failures by Domain

Test failures:
- src/auth/login.test.ts (3 failures) → Auth domain
- src/cart/checkout.test.ts (2 failures) → Cart domain
- src/user/profile.test.ts (1 failure) → User domain

Each is independent - fixing one doesn't affect others.

Step 2: Verify Independence

Ask for each group:
- Does it share state with other groups? NO
- Does fixing it require changes to other groups? NO
- Could fixes conflict with each other? NO

If all NO → Parallel is safe
If any YES → Sequential or combined approach

---

Task Creation Pattern

Each agent receives:

1. Specific Scope

BAD: "Fix all the tests"
GOOD: "Fix auth/login.test.ts - 3 failing tests"

2. Clear Goal

BAD: "Make it work"
GOOD: "Make all tests in auth/login.test.ts pass"

3. Constraints

- Only modify files in src/auth/
- Don't change the test expectations
- Don't modify shared utilities

4. Expected Output

Return:
- Files modified
- Tests now passing
- Summary of changes
- Any concerns

---

Execution Pattern

Dispatch Agents Concurrently

Agent 1: Fix auth/login.test.ts
Agent 2: Fix cart/checkout.test.ts
Agent 3: Fix user/profile.test.ts

All three run simultaneously.

Monitor Progress

While agents working:
- Check for early failures
- Watch for scope violations
- Ready to pause if conflicts detected

---

Integration Pattern

Step 1: Collect Results

Agent 1 returned:
- Modified: src/auth/login-service.ts
- Tests: 3/3 passing
- Summary: Fixed token validation edge case

Agent 2 returned:
- Modified: src/cart/checkout-service.ts
- Tests: 2/2 passing
- Summary: Fixed price calculation rounding

Agent 3 returned:
- Modified: src/user/profile-service.ts
- Tests: 1/1 passing
- Summary: Fixed null handling in profile update

Step 2: Verify No Conflicts

Check:
- No overlapping file modifications
- No conflicting changes to shared types
- No incompatible API changes

Step 3: Run Full Test Suite

npm test
# All tests should pass including:
# - The 6 originally failing tests
# - All other tests (no regressions)

Step 4: Integrate Changes

# If all agents used branches
git merge agent-1-auth-fixes
git merge agent-2-cart-fixes
git merge agent-3-user-fixes

---

Example Prompts

Agent Task Prompt Template

## Task: Fix [specific test file]

**Scope**: Only modify files in [directory]

**Failing tests**:
1. [test name 1]
2. [test name 2]

**Constraints**:
- Do not modify test expectations
- Do not change shared utilities in src/utils/
- Do not modify types in src/types/

**Goal**: Make all tests in [file] pass

**Return**:
- List of files modified
- Summary of changes made
- Number of tests now passing
- Any concerns about the changes

Result Collection Prompt

## Parallel Agent Results

**Agent 1 (Auth)**:
[Paste agent 1 results]

**Agent 2 (Cart)**:
[Paste agent 2 results]

**Agent 3 (User)**:
[Paste agent 3 results]

## Integration Checklist
- [ ] No file conflicts
- [ ] Full test suite passes
- [ ] Changes are isolated to domains
- [ ] Ready to merge

---

Example: Full-Stack Feature Dispatch

A real-world example dispatching 3 agents for a new "orders" feature:

Independence check

	Agent 1 (Backend)	Agent 2 (Frontend)	Agent 3 (Database)
Files	src/api/orders.py, tests/test_orders.py	src/components/order-form.tsx, *.test.tsx	migrations/003_orders.sql, tests/test_migration.py
Test suite	pytest tests/test_orders.py	npm test -- order-form	pytest tests/test_migration.py
Shared state?	No	No	No

All three touch different files and different test suites — safe to parallelize.

Agent 1 — Backend (FastAPI)

## Task: Implement POST /api/orders with validation

**Context**: FastAPI + SQLAlchemy async + Pydantic v2
**Files**: src/api/orders.py, src/schemas/order.py, tests/test_orders.py
**Constraints**: Depends(get_db), return 201, RFC 9457 errors
**Verify**: pytest tests/test_orders.py -v

Agent 2 — Frontend (React/Next.js)

## Task: Build OrderForm component with validation

**Context**: Next.js App Router + react-hook-form + Zod + shadcn/ui
**Files**: src/components/order-form.tsx, src/components/order-form.test.tsx
**Constraints**: 'use client', Zod schema, accessible form fields
**Verify**: npx vitest run src/components/order-form.test.tsx

Agent 3 — Database (PostgreSQL)

## Task: Create orders table migration

**Context**: Alembic migrations, PostgreSQL
**Files**: migrations/003_create_orders.sql, tests/test_orders_migration.py
**Constraints**: Include indexes on user_id and created_at, add foreign key to users
**Verify**: pytest tests/test_orders_migration.py -v

Integration after all 3 complete

# 1. Run each agent's test suite to confirm
pytest tests/test_orders.py tests/test_orders_migration.py -v
npx vitest run src/components/order-form.test.tsx

# 2. Run full test suite for regressions
pytest -v && npm test

# 3. Verify no file conflicts
git diff --name-only  # should show no overlapping files between agents

---

Conflict Resolution

If conflicts detected:

1. STOP parallel execution
2. Identify conflicting changes
3. Decide which takes priority
4. Continue sequentially from conflict point
5. Learn: Update domain boundaries

---

Checklist

Before parallel dispatch:

• 3+ independent failures identified
• Failures grouped by domain
• Independence verified (no shared state)
• Scope boundaries clear
• Conflict potential assessed

After parallel completion:

• All agent results collected
• No file conflicts detected
• Full test suite passes
• Changes integrated successfully

---

Related Skills

• executing-plans - Use executing-plans when tasks are sequential; use dispatching-parallel-agents when tasks are independent and can run concurrently
• writing-plans - Write a plan first to identify which tasks are independent before dispatching parallel agents