Background Orchestration

Background orchestration is the default orchestration model for oh-my-opencode-slim. It assumes native OpenCode background subagents are available and changes the orchestrator from a primary worker into a scheduler.

The old model was:

orchestrator works directly → delegates when useful → waits for result

The default background-orchestration model is:

orchestrator plans → dispatches background specialists → monitors → reconciles → verifies

This is a clean rebuild, not a compatibility layer over the old blocking model.

Runtime Requirement

Background orchestration requires an OpenCode release that includes native background subagents, launched with background subagents enabled:

OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode

The required native/background-control tools are:

Tool	Purpose
`task(..., background: true)`	Start a specialist in the background and immediately return a task ID
hook-driven completion	OpenCode injects terminal background task results automatically
`cancel_task`	Plugin-provided tool to cancel a tracked background task by task ID or Background Job Board alias

If these are not available, the scheduler cannot use the default background workflow. Configure the environment variable through the installer or use the one-shot export above before starting OpenCode.

Use an OpenCode release that includes native background subagents and hook-driven completion; run opencode --version and update if background tasks are missing.

Core Principle

The orchestrator is not the default implementation worker.

Its job is to:

understand the user request,
break work into dependent and independent units,
choose the right specialist for each unit,
schedule background work,
track task IDs and states,
avoid conflicting writes,
integrate specialist results,
run or route final verification,
communicate concise progress and outcomes to the user.

Specialists do the work. The orchestrator manages the work.

Execution Loop

Every non-trivial request follows this loop:

Understand
  ↓
Plan dependency graph
  ↓
Dispatch independent specialists in background
  ↓
Track task IDs and ownership
  ↓
Continue only independent coordination work
  ↓
Wait for hook-driven completion
  ↓
Reconcile results and resolve conflicts
  ↓
Dispatch follow-up work if needed
  ↓
Verify
  ↓
Final response

The orchestrator should not act on assumptions from a still-running task. It can continue scheduling independent work, but dependent work waits for terminal task results.

Scheduler Responsibilities

1. Build a dependency graph

Before dispatching agents, the orchestrator identifies:

which questions must be answered before implementation,
which tasks can run in parallel,
which tasks must be sequential,
which files or subsystems each writer owns,
which outputs are needed for final verification.

This does not need to be a long plan. It should be just enough structure to avoid wasted work and conflicting edits.

2. Dispatch background specialists

Independent work should be launched with background tasks:

task(
  description="Search auth flow",
  subagent_type="explorer",
  background=true,
  prompt="Find the auth entry points, session storage, and login callback paths. Return file paths and a concise map. Do not edit files."
)

The orchestrator records the returned task ID and keeps working only on safe, independent coordination.

3. Track ownership

The scheduler must prevent write conflicts.

Rules:

Only one write-capable specialist owns a file at a time.
Do not run two fixer tasks against overlapping folders unless ownership is explicit.
UI work that touches shared components should not run beside implementation work that edits the same components.
Review tasks can run in parallel with read-only discovery, but not with edits they are supposed to review.

4. Wait, cancel, and reconcile

Background tasks are not complete until OpenCode injects their terminal result or hook-driven completion marks them terminal.

The orchestrator should use background completion events to:

wait for dependent results,
check long-running tasks,
collect outputs before final response,
surface failures or blocked tasks clearly.

The orchestrator should use cancel_task only when the user asks, or when a running lane is obsolete, wrong, or conflicts with a safer replacement plan. Cancellation is not rollback: if cancelling a writer, inspect and reconcile partial file changes before launching a replacement lane.

Note on reconciliation: Idle-based reconciliation is a heuristic. A job marked as reconciled means its terminal result was injected into an orchestrator turn that completed and the parent returned to idle; it is not proof the result was explicitly acknowledged or used. The orchestrator should still verify it consumed the relevant outputs before finalizing.

Specialist outputs are inputs, not final truth. The orchestrator reconciles them against each other and the original user goal.

5. Verify

Verification remains orchestrator-owned, but not necessarily orchestrator-run.

Examples:

route UI review to designer,
route code review to oracle,
route test writing or test updates to fixer,
run final shell checks directly only when appropriate.

The final response should only happen after relevant background work is terminal and reconciled.

Specialist Roles

Explorer

Read-only reconnaissance and codebase mapping. Usually the first background task for unfamiliar work.

Librarian

External docs, version-specific API behavior, and real-world examples. Runs in parallel with Explorer when implementation depends on current library behavior.

Fixer

Bounded implementation worker. Receives a clear objective, file ownership, constraints, and validation expectations.

Designer

User-facing UI/UX implementation and review. Owns visual polish, responsive layout, interaction quality, and design consistency.

Oracle

Architecture, code review, simplification, risk analysis, and high-stakes debugging. Often used after implementation or before risky refactors.

Council

Multi-model decision support for critical trade-offs. It is not a worker pool; it is for judgment where disagreement is useful.

Observer

Visual/media analysis isolated from the orchestrator context.

Direct Work Boundary

Background orchestration removes the orchestrator-as-worker default.

The orchestrator may directly:

ask clarifying questions,
read minimal context needed to route work,
create and update todos,
launch and monitor tasks,
synthesize results,
run final checks when that is cheaper than delegating.

The orchestrator should delegate:

broad code search,
unfamiliar library research,
implementation,
test creation or updates,
UI polish,
architecture review,
visual/media analysis.

This keeps the main context focused on coordination instead of filling it with worker detail.

Task Prompt Contract

Every delegated task should be self-contained.

Include:

objective,
constraints,
relevant files or search scope,
ownership boundaries,
expected output format,
whether edits are allowed,
validation to run or report,
what not to do.

Good background task prompt:

Investigate src/hooks/task-session-manager for assumptions that a task tool
result means the child task has finished. Do not edit files. Return:
1. exact files/functions involved,
2. which assumptions break with background tasks,
3. recommended code changes,
4. tests that should be added.

Bad background task prompt:

Look into background tasks.

State The Orchestrator Must Track

The prompt/runtime treats background tasks as a small job board:

Field	Meaning
task ID	Native OpenCode background task/session ID
specialist	Agent type assigned
objective	What the task is responsible for
state	running, completed, error, cancelled, timed out
ownership	Files/folders/subsystems the task may edit
dependencies	Tasks that must complete first
result	Final task output once terminal

The current todo list can represent user-visible work, but task IDs and file ownership need to be explicit in the orchestrator's working context.

Runtime Integration

The plugin is aware that a task return can mean "background job launched" rather than "work complete". It tracks running task IDs, exposes recent work in the background job board, updates aliases from task results, and keeps multiplexer panes attached while the parent orchestrator continues scheduling.

Startup Behavior

The installer and docs configure background subagents as a requirement for the default scheduler workflow. If background subagents are unavailable, treat it as an environment or OpenCode-version issue rather than an intentional V1 fallback:

Background orchestration requires OpenCode background subagents.
Start OpenCode with:

OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode

No automatic legacy fallback keeps the mental model clean.

Example Flow

User asks:

Make background subagents first-class in this plugin.

The orchestrator should do something like:

Create todos for discovery, design, implementation, docs, tests, review.
Launch Explorer in background to map task-session hooks and task lifecycle.
Launch Oracle in background to review architecture risks.
Continue by preparing the dependency graph and file ownership plan.
Wait for Explorer and Oracle via hook-driven completion.
Dispatch Fixer to implement prompt/config/hook changes with clear ownership.
Dispatch a second Fixer for tests if file ownership is separate.
Wait for implementation results.
Dispatch Oracle for final review.
Run final checks.
Report final state.

At no point does the orchestrator become the main implementer.

Success Criteria

Background orchestration is working when:

the orchestrator launches independent specialists in background by default,
task IDs are tracked until terminal state,
dependent work waits for real task results,
file ownership prevents concurrent write conflicts,
final responses only happen after reconciliation and verification,
users see faster progress on multi-step work,
the orchestrator context stays focused on decisions instead of worker detail.

Background orchestration is not just "parallel agents." It is a scheduler-centered operating model for OpenCode's native background subagents.

background-orchestration.md 11 KB Permalink History Raw