opencode-ensemble

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.

This repo vendors the upstream hueyexe/opencode-ensemble skill from tag v0.14.2 (b6bc7f706c13aa42d32e836ea647677d0b14c2f7) and tunes its model guidance for this OpenCode setup. Teammates should inherit the repo-managed OpenCode agent variants by default; pass an explicit team_spawn.model only when the task needs a deliberate model override.

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.

Dispatch Table

Route $ARGUMENTS by the user's request:

$ARGUMENTS pattern	Mode	Action
parallel, team, ensemble, delegate, teammate	Team planning	Decide whether Ensemble is justified, then create one lead-owned team if useful.
waves, parallel teams, subagents, fan out	Wave planning	Model work as one team with role groups, task dependencies, and lead-owned gates.
review teammate output, merge team, finish team	Integration	Read results, shut down teammates, merge with team_merge, inspect diffs, and verify.
models, model pool, which model	Model guidance	Inherit repo defaults unless a deliberate team_spawn.model override is justified.
Empty or ambiguous	Suitability check	Explain when Ensemble helps, and prefer one scout or inline work when scope is small.

Canonical Vocabulary

Term	Meaning
Lead	The session that called team_create and owns decomposition, spawning, merge, and verification.
Teammate	A lead-spawned OpenCode session created by team_spawn.
Wave	A staged group of tasks that can run after its dependencies are complete.
Role group	A set of related teammates inside one team, such as api-*, ui-*, qa-*, or review-*.
Gate	A lead-owned checkpoint before unblocking the next wave.
Teammate subagent	A child session created by a teammate; it cannot use team_* tools.

Parallel Waves

Model parallel teams as one lead-owned Ensemble team with role groups and staged waves. Use team_tasks_add.depends_on to encode the wave DAG, team_spawn.claim_task to bind teammates to real task IDs, and lead-owned gates between waves for synthesis, merge, and verification.

Supported shape:

1. Wave 0 scouts map boundaries and risks with agent: "explore" and worktree: false.
2. The lead summarizes scout results and only then spawns independent builders.
3. Builders work in parallel on non-overlapping slices in isolated worktrees.
4. The lead reads results, shuts down, merges, and inspects diffs before unblocking QA or reviewers.
5. QA and reviewers run after implementation branches are integrated.

One lead session can own only one active Ensemble team. If truly separate teams are needed, use separate lead sessions; otherwise keep role groups inside the same team and name waves clearly in task content.

Do not ask teammate-created subagents to coordinate through team_* tools. Ensemble intentionally blocks team tools for descendants of teammates, so the lead must spawn every teammate that needs to participate in team coordination.

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.
• Work can be represented as staged waves where each later wave depends on completed task IDs from earlier waves.

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.
• You need one lead session to run multiple active teams at once.
• You need teammate subagents to use team_* tools for coordination.

Lead Workflow

1. Decide whether parallelism is justified.
2. Create a team with team_create.
3. Add tasks with team_tasks_add; use depends_on for sequencing.
4. Spawn teammates one at a time with team_spawn; after spawning, they run asynchronously in parallel.
5. Use worktree: false for read-only explore teammates.
6. Use plan_approval: true for risky implementation work.
7. Hold a lead synthesis gate before starting a dependent wave.
8. Wait for teammate messages instead of polling status repeatedly.
9. Read full results with team_results when messages are truncated or consequential.
10. Shut down completed teammates with team_shutdown.
11. Merge branches with team_merge; inspect the diff before trusting it.
12. Run project verification before team_cleanup and before claiming done.

Role Defaults

Role	Agent	Worktree	Model guidance	Use for
Scout	explore	false	Inherit repo high default	Codebase mapping, risk discovery, file ownership plan
Builder	build	true	Inherit repo high default	Narrow implementation slice
QA	build	true	Inherit repo high default	Tests, fixtures, regression coverage
Reviewer	explore	false	Inherit repo high default	Diff review, risk review, missed-test review

Start with two or three teammates. On this machine, 5-8 teammates is a reasonable upper bound for substantial independent work when system resources and API quota permit it. Add more only when the work has more independent slices than active teammates, and prefer additional waves over one oversized first wave.

Reference File Index

File	Load when
references/coordination-patterns.md	Choosing team shape, wave topology, role groups, or separate lead sessions.
references/prompt-recipes.md	Writing scout, builder, QA, reviewer, or wave-specific teammate prompts.
references/lead-checklists.md	Running pre-spawn, wave, merge, cleanup, or verification gates.
references/anti-patterns.md	Checking whether the plan is over-parallelized, unsupported, or too chatty.
references/eval-scenarios.md	Creating or improving this skill's behavior checks.

Critical Rules

1. Record generated task IDs. team_tasks_add generates IDs; use the IDs returned by earlier calls when setting depends_on or claim_task.
2. Keep teammate prompts short. The plugin already injects team role, allowed tools, worktree context, and the required task-result format.
3. Avoid vague delegation. Prompts like "fix the bug" or "work on tests" create overlapping, unverifiable work.
4. Keep lead-only tools with the lead. Do not ask teammates to use team_spawn, team_shutdown, team_merge, team_cleanup, or team_view.
5. Keep teammate subagents out of team coordination. They are intentionally isolated from team_* access.
6. Gate dependent waves. Do not start a dependent wave until required task IDs are completed and integrated by the lead.
7. Require team_message results. Do not tell teammates to report only in plain text.
8. Review before merging. Do not merge a teammate branch without reading its result and inspecting the diff.
9. Verify before claiming completion. Run repository verification commands or clearly report the blocker.

Validation Contract

Before claiming an Ensemble workflow is successful:

• The lead can explain why the work was divisible.
• Every spawned teammate has one clear owner area and one assigned task ID when applicable.
• Dependent waves use real depends_on IDs.
• Read-only roles use agent: "explore" and worktree: false.
• Teammate results have been read with team_results when truncated or consequential.
• Merged branches have been inspected with project diffs.
• Repository-specific verification commands have passed or blockers are reported.

When changing this skill, run python scripts/check.py, uv run pytest tests/test_distribution_metadata.py tests/test_sync_agent_stack.py -q, before declaring the edit complete.

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,
  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",
  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.",
});