marcusrbrown/orchestrating-subagents

Orchestrating Subagents

Dispatch, coordinate, and synthesize results from OpenCode subagents using the task() primitive.

The Portable Primitive

Every subagent dispatch goes through task():

task({
  subagent_type: "systematic-implementer",
  description: "Implement auth module",
  prompt: "...",
})

Required parameters:

• subagent_type — the registered agent name (e.g., systematic-implementer, best-practices-researcher)
• description — 3–5 word label shown in the UI
• prompt — full instructions for the subagent

Optional:

• task_id — resume a prior subagent session instead of creating a new one
• command — the slash command that triggered this task

Foreground dispatch (no background parameter) blocks until the subagent returns its result. This is the default and works on all OpenCode versions.

Background Dispatch (Experimental)

Background dispatch is gated by a runtime flag. It is not available by default.

// Only use when the runtime exposes background support
task({
  subagent_type: "systematic-implementer",
  description: "Implement auth module",
  prompt: "...",
  background: true,   // experimental — see below
})

When background is available: OpenCode exposes task_status in the tool list and the task() tool description includes background mode instructions. This requires OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true or the umbrella OPENCODE_EXPERIMENTAL=true flag.

When background is unavailable: task_status is not registered. Passing background: true returns an error. Fall back to foreground dispatch — dispatch subagents serially or in small foreground batches instead.

Check before assuming: If you see task_status in your available tools, background dispatch is enabled. If you do not see it, use foreground dispatch only.

Serial vs Parallel Dispatch

Serial (default, always safe)

Dispatch one subagent, wait for its result, then dispatch the next. Use when:

• Units have dependencies (unit B needs unit A's output)
• Units touch overlapping files
• You need to verify each result before proceeding

const researchResult = task({
  subagent_type: "best-practices-researcher",
  description: "Research caching patterns",
  prompt: "Research Redis caching best practices for Rails APIs...",
})

// Use research output to guide implementation
task({
  subagent_type: "systematic-implementer",
  description: "Implement caching",
  prompt: `Implement caching based on this research:\n\n${researchResult}`,
})

Parallel (foreground batches)

Dispatch multiple foreground subagents in the same turn. OpenCode runs them concurrently when dispatched together. Use when:

• Units are fully independent (no shared files, no dependency on each other's output)
• You have passed the Parallel Safety Check (see below)

// Dispatch independent review subagents together
task({ subagent_type: "security-sentinel", description: "Security review", prompt: "..." })
task({ subagent_type: "performance-oracle", description: "Performance review", prompt: "..." })
task({ subagent_type: "correctness-reviewer", description: "Correctness review", prompt: "..." })
// All three run; orchestrator synthesizes results after all complete

Parallel Safety Check

Before dispatching units in parallel, verify:

1. No file overlap — build a file-to-unit map from each unit's declared files. Any file appearing in 2+ units means overlap → use serial dispatch instead.
2. No git index contention — parallel subagents must not stage files (git add), create commits, or run the full test suite. If the current workflow owns git operations, the orchestrator handles staging and committing after all parallel units complete; otherwise, synthesize results and file lists and leave staging/committing to the caller or user.
3. No test interference — concurrent test runs pick up each other's in-progress changes. Instruct parallel subagents not to run the project test suite.

If any check fails, downgrade to serial dispatch. Log the reason (e.g., "Units 2 and 4 share config/routes.rb — using serial dispatch").

Subagent Constraints for Parallel Work

When dispatching units in parallel, include these instructions in each subagent's prompt:

Do not stage files (git add), create commits, or run the project test suite. Leave staging and committing to the orchestrator or caller.

Result Synthesis

After subagents complete, the orchestrator synthesizes results:

1. Wait for all — in a parallel batch, wait for every subagent to finish before acting on any result.
2. Check for file collisions — compare actual files modified by all subagents in the batch (not just declared files). If 2+ subagents modified the same file, only the last writer's version survives. If the workflow owns git operations, resolve by staging non-colliding files first, then re-running the affected units serially; otherwise, report the collision list to the caller.
3. Review each diff — verify changes match the unit's declared scope.
4. Run targeted tests — run the narrowest test command relevant to the changed files.
5. Stage and commit per unit (if the workflow owns git operations) — in dependency order, stage only that unit's files and commit with a conventional message. If git operations belong to the caller or user, synthesize the result list and file inventory instead.

Failure and Retry

• If a subagent returns an error or its output is incomplete, diagnose before dispatching dependent units.
• Do not dispatch dependent units on a broken tree.
• Retry a failed unit by dispatching a new task() call with a corrected prompt, or resume the prior session with task_id.
• For background tasks (when available): use task_status to poll or wait for terminal state before retrying.

Quick Reference

| Scenario | Approach | |---|---| | Units have dependencies | Serial foreground dispatch | | Units share files | Serial foreground dispatch | | Units are independent, no file overlap | Parallel foreground dispatch | | Background available + long-running work | Parallel background dispatch with task_status | | Background unavailable | Foreground only — serial or batched | | Subagent fails | Diagnose, fix prompt, retry with new task() or resume with task_id | | File collision detected post-parallel | Stage non-colliding files (if workflow owns git ops), re-run colliding units serially |

Common Mistakes

| Mistake | Fix | |---|---| | Assuming task_status is always available | Check tool list first; fall back to foreground if absent | | Parallel subagents staging or committing | Instruct subagents not to stage/commit; the current workflow owner handles git ops when applicable, otherwise synthesize file inventory and results for the caller or user | | Dispatching dependent units without waiting | Always wait for prerequisites to complete and verify their output | | Ignoring file overlap in parallel batches | Run the Parallel Safety Check before every parallel dispatch | | Using background: true without checking the flag | Only use when task_status appears in available tools |