OpenCode Ensemble

Use OpenCode Ensemble as a coordination system, not a shortcut for avoiding judgment. Parallel agents work best when the lead owns decomposition, sequencing, review, merge, and verification.

Core Principle

Spawn teammates only for independent, verifiable work. A good Ensemble team has narrow task ownership, clear dependencies, and a lead that integrates results deliberately.

Use Ensemble When

Work can be split into independent research, implementation, test, or review slices.
A read-only scout can map unfamiliar code before edits begin.
Multiple files or subsystems can be changed without overlapping ownership.
A risky change benefits from
```
plan_approval: true
```
before edits.
A final reviewer can inspect merged changes without creating another branch.

Do Not Use Ensemble When

The task is small enough for one agent to finish quickly.
The work is tightly coupled and every teammate would need the same files.
The lead cannot describe each teammate's output and success criteria.
The user needs one coherent design decision rather than parallel exploration.
You are tempted to spawn agents because the task feels hard but not divisible.

Lead Workflow

Decide whether parallelism is justified.
Create a team with
```
team_create
```
.
Add tasks with
```
team_tasks_add
```
; use
```
depends_on
```
for sequencing.
Spawn teammates one at a time with
```
team_spawn
```
.
Use
```
worktree: false
```
for read-only
```
explore
```
teammates.
Use
```
plan_approval: true
```
for risky implementation work.
Wait for teammate messages instead of polling status repeatedly.
Read full results with
```
team_results
```
when messages are truncated or consequential.
Shut down completed teammates with
```
team_shutdown
```
.
Merge branches with
```
team_merge
```
; inspect the diff before trusting it.
Run project verification before
```
team_cleanup
```
and before claiming done.

Role Defaults

Role	Agent	Worktree	Model guidance	Use for
Scout	`explore`	`false`	`openai/gpt-5.3-codex-spark`	Codebase mapping, risk discovery, file ownership plan
Builder	`build`	`true`	`anthropic/claude-opus-4-7`	Narrow implementation slice
QA	`build`	`true`	strong balanced model	Tests, fixtures, regression coverage
Reviewer	`explore`	`false`	`openai/gpt-5.3-codex-spark`	Diff review, risk review, missed-test review

Start with two or three teammates. Add more only when the work has more independent slices than active teammates.

Load References As Needed

Need a team shape? Read
```
references/coordination-patterns.md
```
.
Need prompts? Read
```
references/prompt-recipes.md
```
.
Need a pre-spawn, merge, cleanup, or verification gate? Read
```
references/lead-checklists.md
```
.
Something feels off or too chatty? Read
```
references/anti-patterns.md
```
.
Creating or improving this skill? Read
```
references/eval-scenarios.md
```
.

Hard Rules

Do not invent task IDs.
```
team_tasks_add
```
generates IDs; use the IDs returned by earlier calls when setting
```
depends_on
```
or
```
claim_task
```
.
Keep teammate prompts short. The plugin already injects team role, allowed tools, worktree context, and the required task-result format.
Do not give teammates vague prompts like "fix the bug" or "work on tests".
Do not ask teammates to use lead-only tools such as
```
team_spawn
```
,
```
team_shutdown
```
,
```
team_merge
```
,
```
team_cleanup
```
, or
```
team_view
```
.
Do not tell teammates to report only in plain text. They must use
```
team_message
```
.
Do not merge a teammate branch without reading its result and inspecting the diff.
Do not call the work complete until the repository's verification commands pass or you have clearly reported the blocker.

Minimal Example

team_create({ name: "checkout-idempotency" })

team_tasks_add({
  tasks: [
    { content: "Map checkout webhook flow and risky files", priority: "high" },
    { content: "Implement duplicate-webhook idempotency guard", priority: "high" },
  ],
})
// Record returned IDs, for example: task_abc123 for scout and task_def456 for builder.

team_tasks_add({
  tasks: [
    { content: "Add duplicate-webhook regression tests", priority: "high", depends_on: ["task_def456"] },
  ],
})
// Record returned QA task ID, for example: task_ghi789.

team_tasks_add({
  tasks: [
    { content: "Review merged diff for correctness and missed tests", priority: "medium", depends_on: ["task_def456", "task_ghi789"] },
  ],
})

team_spawn({
  name: "scout",
  agent: "explore",
  worktree: false,
  model: "openai/gpt-5.3-codex-spark",
  claim_task: "task_abc123",
  prompt: "Trace the checkout webhook flow. Report files, data model, existing tests, risks, and a smallest-safe-change plan. Do not edit files.",
})

team_spawn({
  name: "api-dev",
  agent: "build",
  model: "anthropic/claude-opus-4-7",
  plan_approval: true,
  claim_task: "task_def456",
  prompt: "Use scout's findings to implement only the idempotency guard. Commit your work and send a task-result message with files changed and tests run.",
})

opencode-ensemble

NPX Install

Tags

SKILL.md Content