opencode-ensemble

opencode-ensemble1464 wordsMITRepo-owned

Use when coordinating OpenCode Ensemble teams, delegating independent coding work, reviewing teammate output, or running staged parallel waves.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill opencode-ensemble -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /opencode-ensemble

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

Repo skill (hand-maintained)

Composed compose-custom-wave-5 from skills/opencode-ensemble/SKILL.md with full SKILL disclosure. Do not run wagents docs generate on this file (HAND-MAINTAINED sentinel).

What It Does

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.

Modes

$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.

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.

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. Step — Decide whether parallelism is justified.

2. Step — Create a team with team_create.

3. Step — Add tasks with team_tasks_add; use depends_on for sequencing.

4. Step — Spawn teammates one at a time with team_spawn; after spawning, they run asynchronously in parallel.

5. Step — Use worktree: false for read-only explore teammates.

6. Step — Use plan_approval: true for risky implementation work.

7. Step — Hold a lead synthesis gate before starting a dependent wave.

8. Step — Wait for teammate messages instead of polling status repeatedly.

9. Step — Read full results with team_results when messages are truncated or consequential.

10. Step — Shut down completed teammates with team_shutdown.

11. Step — Merge branches with team_merge; inspect the diff before trusting it.

12. Step — 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.

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 skills/opencode-ensemble/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.",
});

Public Metadata

Field	Value
Source Type	repo-owned
Display Source	github:wyattowalsh/agents
Source Kind	repo
Installability	portable command
Review State	reviewed
Target Agents	antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode

General

Field	Value
Name	opencode-ensemble
License	MIT
Version	1.0.0
Author	hueyexe

Compatibility

Field	Value
Compatibility	OpenCode with the @hueyexe/opencode-ensemble plugin installed

View Full SKILL.md

SKILL.md

---
name: opencode-ensemble
description: "Use when coordinating OpenCode Ensemble teams, delegating independent coding work, reviewing teammate output, or running staged parallel waves. NOT for single-agent tasks, nested team-of-teams, or teammate subagents using team tools."
license: MIT
compatibility: "OpenCode with the @hueyexe/opencode-ensemble plugin installed"
metadata:
  author: hueyexe
  version: "1.0.0"
---

# 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.

<!-- deduped 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 skills/opencode-ensemble/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

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

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

---

View source on GitHub