name: swarm-coordination description: | OpenCode群体工作流的多智能体协调模式。当工作受益于并行化或协调时使用。覆盖：分解、工作者生成、文件保留、进度跟踪和审查循环。

群体协调

这个技能指导OpenCode群体工作流的多智能体协调。

何时使用

涉及3个及以上文件的任务
可并行化的工作（前端/后端/测试）
需要专业代理的工作
完成时间很重要

避免对1-2个文件更改或紧密顺序的工作使用群体协调。

工具访问（通配符）

根据用户选择，此技能配置为tools: ["*"]。如果后续需要精选访问，请将通配符替换为显式工具列表。

前台 vs 后台 vs 代理团队

前台代理 可以访问MCP工具。
后台代理 不拥有MCP工具。
代理团队队友（当启用CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS时）具有独立的上下文和消息传递。
对swarmmail_*、swarm_*、hive_*和MCP调用使用前台工作者。
仅对文档编辑和静态工作使用后台工作者。

MCP生命周期

Claude Code从mcpServers配置自动启动MCP服务器。除调试外，不需要手动swarm mcp-serve。

代理团队生成独立实例，拥有自己的MCP连接。每个队友具有独立的工具访问权限。

协调器协议（双路径）

原生团队（当可用时）

初始化群体邮件（swarmmail_init）。
查询过去的学习（hivemind_find）。
分解（swarm_plan_prompt + swarm_validate_decomposition）。
通过TeammateTool生成以进行实时协调。
通过原生团队消息传递 + swarm_review进行审查以持久化。
记录结果（swarm_complete）。

回退（任务子代理）

初始化群体邮件（swarmmail_init）。
查询过去的学习（hivemind_find）。
分解（swarm_plan_prompt + swarm_validate_decomposition）。
通过Task(subagent_type="swarm-worker", prompt="...")生成工作者。
审查工作者输出（swarm_review + swarm_review_feedback）。
记录结果（swarm_complete）。

工作者协议（双路径）

使用代理团队

通过session-start钩子自动初始化。
保留文件（swarmmail_reserve）— 原生团队没有文件锁定。
使用TaskUpdate进行UI旋转器 + swarm_progress进行持久跟踪。
完成时使用swarm_complete（自动释放保留）。

不使用代理团队

初始化群体邮件（swarmmail_init）。
保留文件（swarmmail_reserve）。
在工作范围内工作并报告进度（swarm_progress）。
完成时使用swarm_complete。

文件保留

工作者在编辑前必须保留文件，并通过swarm_complete释放。协调器从不保留文件。

进度报告

使用TaskUpdate进行UI旋转器（在Claude Code中显示即时反馈），并在25%、50%和75%完成时使用swarm_progress进行持久跟踪和自动检查点。

生成工作者（关键 - 请阅读此部分）

步骤1：准备子任务

const spawnResult = await swarm_spawn_subtask({
  bead_id: "cell-abc123",           // 此子任务的蜂巢单元ID
  epic_id: "epic-xyz789",           // 父史诗ID
  subtask_title: "添加日志工具",
  subtask_description: "创建支持结构化日志的日志模块",
  files: ["src/utils/logger.ts", "src/utils/logger.test.ts"],  // 字符串数组，非JSON字符串
  shared_context: "此史诗正在添加可观察性。其他工作者正在添加指标和追踪。",
  project_path: "/absolute/path/to/project"  // 跟踪所需
});

步骤2：使用Task生成工作者

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

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

常见错误

错误 - files作为JSON字符串：

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

正确 - files作为数组：

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

错误 - 缺少project_path：

swarm_spawn_subtask({
  bead_id: "...",
  epic_id: "...",
  // 没有project_path - 工作者无法初始化跟踪！
})

正确 - 包含project_path：

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

并行 vs 顺序生成

并行（独立任务）

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

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

顺序（依赖任务）

在生成下一个之前等待每一个：

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

故事状态流程

状态转换应遵循：

协调器在生成工作者时将故事设置为in_progress
工作者完成工作并设置为ready_for_review
协调器审查并设置为passed或failed

工作者不设置最终状态 - 那是协调器审查后的工作。

技能加载指导

工作者应根据任务类型加载技能：

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