swarm-coordination

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swarm Coordination

Swarm协调

This skill guides multi-agent coordination for OpenCode swarm workflows.

本技能指导OpenCode swarm工作流中的多Agent协调。

When to Use

适用场景

Tasks touching 3+ files
Parallelizable work (frontend/backend/tests)
Work requiring specialized agents
Time-to-completion matters

Avoid swarming for 1–2 file changes or tightly sequential work.

涉及3个及以上文件的任务
可并行处理的工作（前端/后端/测试）
需要专业Agent的工作
对完成时间有要求的工作

避免在仅需修改1-2个文件或严格顺序执行的工作中使用Swarm。

Tool Access (Wildcard)

工具权限（通配符）

This skill is configured with

tools: ["*"]

per user choice. If you need curated access later, replace the wildcard with explicit tool lists.

本技能根据用户选择配置为

tools: ["*"]

。如果后续需要限定权限，可将通配符替换为明确的工具列表。

Foreground vs Background vs Agent Teams

前台Agent vs 后台Agent vs Agent团队

Foreground agents can access MCP tools.
Background agents do not have MCP tools.
Agent Team Teammates (when
```
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
```
enabled) have independent context and messaging.
Use foreground workers for
```
swarmmail_*
```
,
```
swarm_*
```
,
```
hive_*
```
, and MCP calls.
Use background workers for doc edits and static work only.

前台Agent可访问MCP工具。
后台Agent不可访问MCP工具。
Agent团队成员（当
```
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
```
启用时）拥有独立的上下文和消息机制。
前台Worker用于
```
swarmmail_*
```
、
```
swarm_*
```
、
```
hive_*
```
及MCP调用。
后台Worker仅用于文档编辑和静态工作。

MCP Lifecycle

MCP生命周期

Claude Code auto-launches MCP servers from

mcpServers

configuration. Do not require manual

swarm mcp-serve

except for debugging.

Agent teams spawn separate instances with their own MCP connections. Each teammate has independent tool access.

Claude Code会从

mcpServers

配置中自动启动MCP服务器。除非用于调试，否则不要要求手动执行

swarm mcp-serve

。

Agent团队会生成独立实例，每个实例拥有自己的MCP连接。每个团队成员都有独立的工具权限。

Coordinator Protocol (Dual-Path)

协调器协议（双路径）

Native Teams (When Available)

原生团队（可用时）

Initialize Swarm Mail (
```
swarmmail_init
```
).
Query past learnings (
```
hivemind_find
```
).

Decompose (

swarm_plan_prompt

swarm_validate_decomposition

Spawn via
```
TeammateTool
```
for real-time coordination.
Review via native team messaging +
```
swarm_review
```
for persistence.
Record outcomes (
```
swarm_complete
```
).

初始化Swarm Mail（
```
swarmmail_init
```
）。
查询过往经验（
```
hivemind_find
```
）。

任务分解（

swarm_plan_prompt

swarm_validate_decomposition

）。

通过
```
TeammateTool
```
生成Agent以实现实时协调。
通过原生团队消息机制+
```
swarm_review
```
进行审核并持久化记录。
记录结果（
```
swarm_complete
```
）。

Fallback (Task Subagents)

备选方案（任务子Agent）

Initialize Swarm Mail (
```
swarmmail_init
```
).
Query past learnings (
```
hivemind_find
```
).

Decompose (

swarm_plan_prompt

swarm_validate_decomposition

Spawn workers via

Task(subagent_type="swarm-worker", prompt="...")

Review worker output (
```
swarm_review
```
+
```
swarm_review_feedback
```
).
Record outcomes (
```
swarm_complete
```
).

初始化Swarm Mail（
```
swarmmail_init
```
）。
查询过往经验（
```
hivemind_find
```
）。

任务分解（

swarm_plan_prompt

swarm_validate_decomposition

）。

通过

Task(subagent_type="swarm:worker", prompt="...")

生成Worker。

审核Worker输出（
```
swarm_review
```
+
```
swarm_review_feedback
```
）。
记录结果（
```
swarm_complete
```
）。

Worker Protocol (Dual-Path)

Worker协议（双路径）

With Agent Teams

基于Agent团队

Auto-initialize via
```
session-start
```
hook.
Reserve files (
```
swarmmail_reserve
```
) — native teams have NO file locking.
Use
```
TaskUpdate
```
for UI spinners +
```
swarm_progress
```
for persistent tracking.
Complete with
```
swarm_complete
```
(auto-releases reservations).

通过
```
session-start
```
钩子自动初始化。
预留文件（
```
swarmmail_reserve
```
）——原生团队无文件锁定机制。
使用
```
TaskUpdate
```
实现UI加载动画，使用
```
swarm_progress
```
进行持久化进度跟踪。
执行
```
swarm_complete
```
完成任务（自动释放预留文件）。

Without Agent Teams

不使用Agent团队

Initialize Swarm Mail (
```
swarmmail_init
```
).
Reserve files (
```
swarmmail_reserve
```
).
Work within scope and report progress (
```
swarm_progress
```
).
Complete with
```
swarm_complete
```
.

初始化Swarm Mail（
```
swarmmail_init
```
）。
预留文件（
```
swarmmail_reserve
```
）。
在任务范围内工作并报告进度（
```
swarm_progress
```
）。
执行
```
swarm_complete
```
完成任务。

File Reservations

文件预留

Workers must reserve files before editing and release via

swarm_complete

. Coordinators never reserve files.

Worker必须在编辑前预留文件，并通过

swarm_complete

释放。协调器永远不要预留文件。

Progress Reporting

进度报告

Use

TaskUpdate

for UI spinners (shows instant feedback in Claude Code) and

swarm_progress

at 25%, 50%, and 75% completion for persistent tracking and auto-checkpoints.

使用

TaskUpdate

实现UI加载动画（在Claude Code中显示即时反馈），并在完成25%、50%和75%时使用

swarm_progress

进行持久化跟踪和自动 checkpoint。

Spawning Workers (CRITICAL - Read This)

生成Worker（重要 - 仔细阅读）

Step 1: Prepare the subtask

步骤1：准备子任务

typescript

const spawnResult = await swarm_spawn_subtask({
  bead_id: "cell-abc123",           // The hive cell ID for this subtask
  epic_id: "epic-xyz789",           // Parent epic ID
  subtask_title: "Add logging utilities",
  subtask_description: "Create a logger module with structured logging support",
  files: ["src/utils/logger.ts", "src/utils/logger.test.ts"],  // Array of strings, NOT a JSON string
  shared_context: "This epic is adding observability. Other workers are adding metrics and tracing.",
  project_path: "/absolute/path/to/project"  // Required for tracking
});

typescript

const spawnResult = await swarm_spawn_subtask({
  bead_id: "cell-abc123",           // 此子任务的hive cell ID
  epic_id: "epic-xyz789",           // 父epic ID
  subtask_title: "Add logging utilities",
  subtask_description: "Create a logger module with structured logging support",
  files: ["src/utils/logger.ts", "src/utils/logger.test.ts"],  // 字符串数组，而非JSON字符串
  shared_context: "This epic is adding observability. Other workers are adding metrics and tracing.",
  project_path: "/absolute/path/to/project"  // 跟踪所需
});

Step 2: Spawn the worker with Task

步骤2：使用Task生成Worker

typescript

// Parse the result to get the prompt
const { prompt, recommended_model } = JSON.parse(spawnResult);

// Spawn the worker
await Task({
  subagent_type: "swarm:worker",
  prompt: prompt,
  model: recommended_model  // Optional: use the auto-selected model
});

typescript

// 解析结果获取prompt
const { prompt, recommended_model } = JSON.parse(spawnResult);

// 生成Worker
await Task({
  subagent_type: "swarm:worker",
  prompt: prompt,
  model: recommended_model  // 可选：使用自动选择的模型
});

Common Mistakes

常见错误

WRONG - files as JSON string:

typescript

files: '["src/auth.ts"]'  // DON'T do this

CORRECT - files as array:

typescript

files: ["src/auth.ts", "src/auth.test.ts"]  // Do this

WRONG - missing project_path:

typescript

swarm_spawn_subtask({
  bead_id: "...",
  epic_id: "...",
  // No project_path - worker can't initialize tracking!
})

CORRECT - include project_path:

typescript

swarm_spawn_subtask({
  bead_id: "...",
  epic_id: "...",
  project_path: "/Users/joel/myproject"  // Required!
})

错误示例 - 文件为JSON字符串：

typescript

files: '["src/auth.ts"]'  // 不要这样做

正确示例 - 文件为数组：

typescript

files: ["src/auth.ts", "src/auth.test.ts"]  // 这样做

错误示例 - 缺少project_path：

typescript

swarm_spawn_subtask({
  bead_id: "...",
  epic_id: "...",
  // 无project_path - Worker无法初始化跟踪！
})

正确示例 - 包含project_path：

typescript

swarm_spawn_subtask({
  bead_id: "...",
  epic_id: "...",
  project_path: "/Users/joel/myproject"  // 必填！
})

Parallel vs Sequential Spawning

并行生成vs顺序生成

Parallel (independent tasks)

并行（独立任务）

Send multiple Task calls in a single message:

typescript

// All in one message - runs in parallel
Task({ subagent_type: "swarm:worker", prompt: prompt1 })
Task({ subagent_type: "swarm:worker", prompt: prompt2 })
Task({ subagent_type: "swarm:worker", prompt: prompt3 })

在单条消息中发送多个Task调用：

typescript

// 全部在一条消息中 - 并行运行
Task({ subagent_type: "swarm:worker", prompt: prompt1 })
Task({ subagent_type: "swarm:worker", prompt: prompt2 })
Task({ subagent_type: "swarm:worker", prompt: prompt3 })

Sequential (dependent tasks)

顺序（依赖任务）

Await each before spawning next:

typescript

const result1 = await Task({ subagent_type: "swarm:worker", prompt: prompt1 });
// Review result1...
const result2 = await Task({ subagent_type: "swarm:worker", prompt: prompt2 });

在生成下一个前等待上一个完成：

typescript

const result1 = await Task({ subagent_type: "swarm:worker", prompt: prompt1 });
// 审核result1...
const result2 = await Task({ subagent_type: "swarm:worker", prompt: prompt2 });

Story Status Flow

任务状态流转

Status transitions should flow:

Coordinator sets story to
```
in_progress
```
when spawning worker
Worker completes work and sets to
```
ready_for_review
```
Coordinator reviews and sets to
```
passed
```
or
```
failed
```

Workers do NOT set final status - that's the coordinator's job after review.

状态应按以下顺序流转：

协调器在生成Worker时将任务状态设为
```
in_progress
```
Worker完成工作后将状态设为
```
ready_for_review
```
协调器审核后将状态设为
```
passed
```
或
```
failed
```

Worker不要设置最终状态 - 这是协调器审核后的职责。

Skill Loading Guidance

技能加载指南

Workers should load skills based on task type:

Tests or fixes →
```
testing-patterns
```
Architecture →
```
system-design
```
CLI work →
```
cli-builder
```
Coordination →
```
swarm-coordination
```

Worker应根据任务类型加载对应技能：

测试或修复 →
```
testing-patterns
```
架构设计 →
```
system-design
```
CLI工作 →
```
cli-builder
```
协调工作 →
```
swarm-coordination
```