opencode-ensemble

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

将OpenCode Ensemble用作协调系统，而非规避判断的捷径。当负责人掌控任务分解、排序、评审、合并和验证工作时，并行Agent的协作效果最佳。

本仓库引入了上游

hueyexe/opencode-ensemble

技能的

v0.14.2

版本（提交哈希：

b6bc7f706c13aa42d32e836ea647677d0b14c2f7

），并针对当前OpenCode配置调整了模型指引。默认情况下，队友应继承仓库管理的OpenCode Agent变体；仅当任务需要刻意覆盖模型时，才传入明确的

team_spawn.model

参数。

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.

仅为独立、可验证的工作创建队友。一个优秀的Ensemble团队应具备明确的任务归属、清晰的依赖关系，以及由负责人主导的结果整合流程。

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.

根据用户请求路由

$ARGUMENTS

：

`$ARGUMENTS` 模式	模式类型	操作说明
`parallel` , `team` , `ensemble` , `delegate` , `teammate`	团队规划	判断是否适合使用Ensemble，若有用则创建一个由负责人管控的团队。
`waves` , `parallel teams` , `subagents` , `fan out`	任务流规划	将工作建模为包含角色组、任务依赖和负责人管控检查点的单个团队。
`review teammate output` , `merge team` , `finish team`	结果整合	读取结果、关闭队友、通过 `team_merge` 合并代码、检查差异并验证。
`models` , `model pool` , `which model`	模型指引	除非有充分理由刻意覆盖 `team_spawn.model` ，否则继承仓库默认配置。
空值或模糊请求	适用性检查	说明Ensemble的适用场景，当任务范围较小时优先选择单个探路Agent或内联工作。

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.

术语	含义
Lead（负责人）	调用 `team_create` 并掌控任务分解、创建队友、合并和验证工作的会话。
Teammate（队友）	由负责人通过 `team_spawn` 创建的OpenCode会话。
Wave（任务流）	一组需依赖前置任务完成后才能启动的阶段性任务。
Role group（角色组）	同一团队内的一组相关队友，例如 `api-` 、 `ui-` 、 `qa-` 或 `review-` 。
Gate（检查点）	负责人管控的关卡，需完成后才能启动下一阶段任务流。
Teammate subagent（队友子Agent）	由队友创建的子会话；无法使用 `team_*` 工具。

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:

Wave 0 scouts map boundaries and risks with
```
agent: "explore"
```
and
```
worktree: false
```
.
The lead summarizes scout results and only then spawns independent builders.
Builders work in parallel on non-overlapping slices in isolated worktrees.
The lead reads results, shuts down, merges, and inspects diffs before unblocking QA or reviewers.
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.

将并行团队建模为一个由负责人管控的Ensemble团队，包含角色组和阶段性任务流。使用

team_tasks_add.depends_on

定义任务流的依赖关系图，使用

team_spawn.claim_task

将队友绑定到真实任务ID，并在任务流之间设置由负责人管控的检查点，用于结果合成、合并和验证。

支持的流程形态：

第0阶段探路Agent使用
```
agent: "explore"
```
和
```
worktree: false
```
，梳理边界和风险。
负责人汇总探路结果后，再创建独立的开发队友。
开发队友在隔离工作区中并行处理互不重叠的任务片段。
负责人读取结果、关闭队友、合并代码并检查差异，之后再启动QA或评审工作。
QA和评审在实现分支整合后开展。

一个负责人会话只能管控一个活跃的Ensemble团队。若确实需要独立团队，请使用单独的负责人会话；否则将角色组保留在同一团队中，并在任务内容中明确命名任务流。

请勿让队友创建的子Agent通过

team_*

工具进行协调。Ensemble刻意阻止队友的子级会话访问团队工具，因此所有需要参与团队协调的队友必须由负责人创建。

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.

工作可拆分为独立的调研、实现、测试或评审片段。
在开始编辑前，可通过只读探路Agent梳理陌生代码。
可在不重叠任务归属的前提下修改多个文件或子系统。
高风险变更可在编辑前启用
```
plan_approval: true
```
。
最终评审可直接检查合并后的变更，无需创建新分支。
工作可表示为阶段性任务流，后续任务流依赖前期任务流的已完成任务ID。

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.

任务范围过小，单个Agent可快速完成。
工作耦合度高，所有队友都需要操作相同文件。
负责人无法明确描述每个队友的输出和成功标准。
用户需要统一的设计决策，而非并行探索。
因任务难度大但无法拆分而想要创建Agent。
需要一个负责人会话同时管控多个活跃团队。
需要让队友子Agent使用
```
team_*
```
工具进行协调。

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
```
; after spawning, they run asynchronously in parallel.
Use
```
worktree: false
```
for read-only
```
explore
```
teammates.
Use
```
plan_approval: true
```
for risky implementation work.
Hold a lead synthesis gate before starting a dependent wave.
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.

判断是否适合采用并行协作。
使用
```
team_create
```
创建团队。
使用
```
team_tasks_add
```
添加任务；通过
```
depends_on
```
定义任务顺序。
使用
```
team_spawn
```
逐个创建队友；创建完成后，他们将异步并行运行。
为只读探路队友设置
```
worktree: false
```
。
为高风险实现工作启用
```
plan_approval: true
```
。
在启动依赖任务流前，由负责人完成结果合成检查点。
等待队友消息，而非反复轮询状态。
当消息被截断或内容重要时，使用
```
team_results
```
读取完整结果。
使用
```
team_shutdown
```
关闭已完成任务的队友。
使用
```
team_merge
```
合并分支；合并前需检查差异。
在执行
```
team_cleanup
```
和宣告任务完成前，运行项目验证。

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.

角色	Agent类型	Worktree	模型指引	适用场景
Scout（探路者）	`explore`	`false`	继承仓库高优先级默认配置	代码库梳理、风险发现、文件归属规划
Builder（开发者）	`build`	`true`	继承仓库高优先级默认配置	窄范围实现任务片段
QA（测试）	`build`	`true`	继承仓库高优先级默认配置	测试用例、测试夹具、回归覆盖
Reviewer（评审）	`explore`	`false`	继承仓库高优先级默认配置	差异评审、风险评审、遗漏测试检查

初始可设置2-3个队友。在当前机器上，若系统资源和API配额允许，5-8个队友是处理大量独立工作的合理上限。仅当独立任务片段数量超过当前活跃队友数量时，才添加更多队友；优先采用多阶段任务流，而非一次性创建过大的初始团队。

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.

文件路径	加载时机
`references/coordination-patterns.md`	选择团队形态、任务流拓扑、角色组或独立负责人会话时。
`references/prompt-recipes.md`	编写探路者、开发者、QA、评审或特定任务流的队友提示词时。
`references/lead-checklists.md`	运行创建前、任务流、合并、清理或验证检查点时。
`references/anti-patterns.md`	检查计划是否过度并行、不被支持或过于繁琐时。
`references/eval-scenarios.md`	创建或改进本技能的行为检查规则时。

Critical Rules

关键规则

Record generated 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.
Avoid vague delegation. Prompts like "fix the bug" or "work on tests" create overlapping, unverifiable work.
Keep lead-only tools with the lead. Do not ask teammates to use
```
team_spawn
```
,
```
team_shutdown
```
,
```
team_merge
```
,
```
team_cleanup
```
, or
```
team_view
```
.
Keep teammate subagents out of team coordination. They are intentionally isolated from
```
team_*
```
access.
Gate dependent waves. Do not start a dependent wave until required task IDs are completed and integrated by the lead.
Require
```
team_message
```
results. Do not tell teammates to report only in plain text.
Review before merging. Do not merge a teammate branch without reading its result and inspecting the diff.
Verify before claiming completion. Run repository verification commands or clearly report the blocker.

记录生成的任务ID。
```
team_tasks_add
```
会生成ID；设置
```
depends_on
```
或
```
claim_task
```
时，需使用之前调用返回的ID。
队友提示词要简洁。插件已自动注入团队角色、允许使用的工具、工作区上下文和要求的任务结果格式。
避免模糊分配任务。类似“修复bug”或“处理测试”的提示词会导致任务重叠、无法验证。
负责人专属工具由负责人掌控。请勿让队友使用
```
team_spawn
```
、
```
team_shutdown
```
、
```
team_merge
```
、
```
team_cleanup
```
或
```
team_view
```
。
禁止队友子Agent参与团队协调。它们被刻意限制访问
```
team_*
```
工具。
管控依赖任务流。在负责人整合完成前置任务ID的工作前，请勿启动依赖任务流。
要求使用
```
team_message
```
返回结果。请勿让队友仅用纯文本报告结果。
评审后再合并。未读取结果和检查差异前，请勿合并队友分支。
验证后再宣告完成。运行仓库验证命令或明确报告阻塞问题。

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.

宣告Ensemble工作流成功前，需满足：

负责人能解释工作可拆分的原因。
每个创建的队友都有明确的负责范围，适用时需分配任务ID。
依赖任务流使用真实的
```
depends_on
```
ID。
只读角色使用
```
agent: "explore"
```
和
```
worktree: false
```
。
当结果被截断或内容重要时，已通过
```
team_results
```
读取完整结果。
已通过项目差异检查合并后的分支。
仓库专属验证命令已通过，或已报告阻塞问题。

修改本技能时，需先运行

python scripts/check.py

、

uv run pytest tests/test_distribution_metadata.py tests/test_sync_agent_stack.py -q

，再宣告编辑完成。

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

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