Dispatch — Parallel Task Orchestration

Decomposition Output

Present the plan to the user as a numbered list before executing:

## Dispatch Plan

### Independent (parallel)
1. [AUTH] Implement authentication module — Worker 1
2. [API] Build API route handlers — Worker 2
3. [TEST] Set up test infrastructure — Worker 3

### Dependent (sequential, after above)
4. [DOCS] Write API documentation — blocked by #2

### Shared Context
- Project uses TypeScript + Express
- Auth strategy: JWT with refresh tokens
- Test framework: Vitest

Wait for user confirmation before dispatching. They may want to adjust priorities, split a task further, or add constraints.

Phase 2: Select the Worker Strategy

Choose the right execution mechanism based on the task characteristics. There are three strategies, and you can mix them within a single dispatch.

Strategy A: Agent Tool (Subagents)

Best for: Research, exploration, code review, analysis, reading/searching large codebases, tasks where the worker needs full tool access but you want results back in your context immediately.

Characteristics:

• Runs in your process — you get the result directly in your conversation
• Good for tasks that produce a summary or answer (not large file changes)
• Can run multiple agents in parallel by issuing multiple Agent calls in one message
• Use isolation: "worktree" when the agent will modify files and you want to avoid conflicts between parallel workers

When to use:

• Exploring code to inform a plan
• Reviewing or auditing existing code
• Research tasks (reading docs, searching for patterns)
• Tasks that produce information rather than artifacts
• When you need the result before deciding next steps

Example dispatch:

Agent(description="Build auth module", prompt="...", isolation="worktree")
Agent(description="Build API routes", prompt="...", isolation="worktree")
Agent(description="Set up test infra", prompt="...", isolation="worktree")

Strategy B: Task Tools (Background Tasks)

Best for: Long-running work where you don't need the result immediately, heavy code generation, builds, test suites — anything that takes minutes and shouldn't block the user or your orchestration.

Characteristics:

• Runs in the background — you're notified when each task completes
• Ideal when you want to keep the user's session responsive
• Results come back via TaskOutput once complete
• Better for "fire and forget" work units

Tools: TaskCreate to define, TaskUpdate to track status, TaskGet for details, TaskList for the overview, TaskOutput to read results.

When to use:

• Heavy code generation (full modules, large refactors)
• Running test suites or build processes
• Any task where waiting would block the user unnecessarily
• When you have 4+ parallel tasks (background is more efficient at scale)

Strategy C: Hybrid (Mixed)

Best for: Real-world projects where some tasks need immediate results and others can run in the background.

Pattern: Use Agent for quick research/analysis tasks whose results inform the plan, then use background Tasks for the heavy execution work.

Example:

1. Agent: "Explore the codebase and identify the auth patterns used" (need this before writing code)
2. Once you have the research results, dispatch background Tasks for the actual implementation work
3. Agent: "Review the combined outputs for consistency" (after tasks complete)

Decision Matrix

Phase 3: Kanban Status Tracking

Maintain a structured status board throughout the dispatch. This is your primary orchestration artifact — it tells you and the user what's happening at a glance.

Local Kanban Board

Always maintain a markdown status board in your conversation. Update it after every state change:

## Dispatch Status

| # | Task | Worker | Status | Notes |
|---|------|--------|--------|-------|
| 1 | Auth module | Agent-1 | DONE | JWT + refresh tokens implemented |
| 2 | API routes | Agent-2 | IN PROGRESS | 6/8 endpoints complete |
| 3 | Test infra | Task-3 | IN PROGRESS | Vitest configured, writing fixtures |
| 4 | API docs | — | BLOCKED (by #2) | Waiting for route definitions |

Status values: QUEUED | IN PROGRESS | DONE | FAILED | BLOCKED (by #N) | RETRY (#N)

GitHub Projects Integration (Optional — Stronger Contracts)

When the user's repo is connected to GitHub and they want persistent, shareable tracking, create a GitHub Project board using the gh CLI. This gives the team visibility and creates a durable record.

Setup:

# Create a GitHub Project (org or user level)
gh project create --title "Dispatch: <task-summary>" --owner <owner>

# Add columns matching Kanban statuses
# (GitHub Projects v2 uses "Status" as a built-in single-select field)

# Create issues for each subtask
gh issue create --title "[AUTH] Implement authentication module" \
  --body "Worker assignment for dispatch. See dispatch plan for details." \
  --label "dispatch"

# Add issues to the project
gh project item-add <project-number> --owner <owner> --url <issue-url>

# Update status as workers progress
gh project item-edit --id <item-id> --project-id <project-id> \
  --field-id <status-field-id> --single-select-option-id <option-id>

When to use GitHub Projects:

• The user explicitly asks for it
• The work is collaborative (multiple people need visibility)
• The dispatch will span multiple sessions
• The user wants a persistent audit trail

When to skip it:

• Quick, single-session dispatches
• Solo work where the local Kanban board is sufficient
• No GitHub repo connected

Always ask the user before creating GitHub issues/projects — these are visible to collaborators.

Phase 4: Dispatch and Monitor

Writing Good Worker Prompts

Each worker gets a self-contained prompt. Include:

1. The specific task — what to build/do, with acceptance criteria
2. Shared context — project conventions, file structure, relevant patterns
3. Boundaries — what NOT to touch (avoid conflicts with other workers)
4. Output expectations — what files to create, where to save them, what to report back

Example worker prompt:

You are Worker 2 in a parallel dispatch. Your task:

BUILD API ROUTE HANDLERS

Context:
- Project: TypeScript + Express, located at /src
- Auth: JWT middleware exists at /src/middleware/auth.ts (Worker 1 is building this
  in parallel — use the interface, don't modify the file)
- Database: Prisma ORM, schema at /prisma/schema.prisma

Task:
- Create REST endpoints for the User resource in /src/routes/users.ts
- Endpoints: GET /users, GET /users/:id, POST /users, PUT /users/:id, DELETE /users/:id
- Apply auth middleware to all routes except GET
- Include input validation using Zod
- Follow existing patterns in /src/routes/health.ts

Output:
- Save all files to /src/routes/
- Report back: list of files created, any decisions you made, any issues hit

Launching Workers

Launch all independent workers in a single message to maximize parallelism:

// All three in one message — they start simultaneously
Agent(description="Build auth module", prompt="<worker-1-prompt>", isolation="worktree")
Agent(description="Build API routes", prompt="<worker-2-prompt>", isolation="worktree")
Agent(description="Set up test infra", prompt="<worker-3-prompt>", isolation="worktree")

For background tasks, create them all at once and then monitor via TaskList.

Monitoring

While workers execute:

• Update the Kanban board as statuses change
• If using GitHub Projects, update issue statuses
• When a worker completes, capture its summary and check for issues
• When a blocked task's dependency completes, dispatch it

Phase 5: Failure Handling

Not everything will succeed. Handle failures methodically.

Failure Classification

When a worker reports a failure, classify it:

Retry Protocol

1. First retry: Re-dispatch the same worker prompt. Transient errors often resolve on their own.
2. Second retry: Add context from the failure ("Previous attempt failed because X. Avoid Y approach."). Adjust the prompt if the error suggests a correctable misunderstanding.
3. After 2 retries: Stop. Mark the task as FAILED and escalate to the user.

Failure Report

When any task fails (after retries or immediately for non-retryable errors), produce a structured failure report. This is critical — the user needs enough context to decide what to do next without digging through logs.

## Dispatch Failure Report

### Failed Tasks

#### #2 — API Route Handlers [FAILED after 2 retries]
- **Worker:** Agent-2 (worktree)
- **Error type:** Logic error (non-retryable)
- **Root cause:** Prisma schema missing the `User` model. Worker attempted
  to generate routes but had no model to reference.
- **Attempts:**
  1. Initial: Failed — `PrismaClientKnownRequestError: model User not found`
  2. Retry 1: Failed — same error (schema unchanged)
- **Impact:** Blocks Task #4 (API docs)
- **Suggested resolution:** Add `User` model to `/prisma/schema.prisma`,
  then re-dispatch Task #2

#### #3 — Test Infrastructure [FAILED, no retry]
- **Worker:** Task-3 (background)
- **Error type:** Input error (missing dependency)
- **Root cause:** `vitest` not in package.json. Worker could not install
  or configure the test runner.
- **Attempts:**
  1. Initial: Failed — `vitest: command not found`
- **Impact:** No downstream dependencies blocked
- **Suggested resolution:** Run `npm install -D vitest` then re-dispatch

### Healthy Tasks
| # | Task | Status |
|---|------|--------|
| 1 | Auth module | DONE |
| 4 | API docs | BLOCKED (by #2) |

### Summary
- 2 of 4 tasks failed
- 1 task completed successfully
- 1 task blocked by a failure
- User action required before re-dispatch

Always present this report and wait for user guidance. Do not silently retry non-retryable errors or skip failed tasks.

Phase 6: Synthesis and Completion

When all workers complete (or after the user resolves failures):

1. Collect results. Gather summaries from all workers.
2. Check for conflicts. If multiple workers modified files in the same area, review for merge conflicts or logical inconsistencies.
3. Integrate. If using worktrees, merge worker branches. If using background tasks, verify outputs are compatible.
4. Update the board. Mark all tasks as DONE and present the final status.
5. Summary to user. Provide a concise synthesis:
   • What was accomplished
   • Files created or modified (with paths)
   • Any decisions workers made that the user should review
   • Suggested next steps

## Dispatch Complete

All 4 tasks finished successfully.

### What was done
- **Auth:** JWT auth with refresh tokens at `/src/middleware/auth.ts`
- **API:** 5 CRUD endpoints for User at `/src/routes/users.ts`
- **Tests:** Vitest configured with fixtures at `/tests/`
- **Docs:** OpenAPI spec at `/docs/api.yaml`

### Decisions made (review recommended)
- Worker 2 chose Zod over Joi for validation (matched existing patterns)
- Worker 3 added a `test:watch` script to package.json

### Suggested next steps
1. Run the full test suite: `npm test`
2. Review the OpenAPI spec for accuracy
3. Test auth flow end-to-end

Quick Reference

Dispatch Checklist

1. Decompose the task into subtasks
2. Identify dependencies (what blocks what)
3. Present the plan — wait for user confirmation
4. Select worker strategy (Agent / Task / Hybrid)
5. Write self-contained worker prompts
6. Launch independent workers in parallel
7. Monitor and update the Kanban board
8. Handle failures (classify, retry if applicable, report)
9. Synthesize results and present to user
10. Clean up (close GitHub issues if used, summarize)

Status Flow

QUEUED → IN PROGRESS → DONE
                     → FAILED → RETRY (#1) → RETRY (#2) → FAILED (escalate)
BLOCKED (by #N) → (dependency resolves) → QUEUED