swarm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swarm Skill

Spawn isolated agents to execute tasks in parallel. Fresh context per agent (Ralph Wiggum pattern).

Execution Modes:

Local (default) - Runtime-native spawning (Codex sub-agents when available, otherwise Claude teams/task agents)
Distributed (
```
--mode=distributed
```
) - tmux sessions + Agent Mail for robust coordination

Integration modes:

Direct - Create TaskList tasks, invoke
```
/swarm
```
Via Crank -
```
/crank
```
creates tasks from beads, invokes
```
/swarm
```
for each wave

生成独立Agent以并行执行任务。每个Agent拥有全新上下文（Ralph Wiggum模式）。

执行模式：

本地模式（默认）- 运行时原生生成（可用时使用Codex子Agent，否则使用Claude团队/任务Agent）
分布式模式（
```
--mode=distributed
```
）- 借助tmux会话 + Agent Mail实现可靠协调

集成模式：

直接集成 - 创建TaskList任务，调用
```
/swarm
```
通过Crank集成 -
```
/crank
```
根据beads创建任务，为每个任务波次调用
```
/swarm
```

Architecture (Mayor-First)

架构（Mayor优先）

Mayor (this session)
    |
    +-> Plan: TaskCreate with dependencies
    |
    +-> Identify wave: tasks with no blockers
    |
    +-> Select spawn backend (Codex sub-agents | Claude teams | fallback tasks)
    |
    +-> Assign: TaskUpdate(taskId, owner="worker-<id>", status="in_progress")
    |
    +-> Spawn workers via selected backend
    |       Workers receive pre-assigned task, execute atomically
    |
    +-> Wait for completion (wait() | SendMessage | TaskOutput)
    |
    +-> Validate: Review changes when complete
    |
    +-> Cleanup backend resources (close_agent | TeamDelete | none)
    |
    +-> Repeat: New team + new plan if more work needed

Mayor（当前会话）
    |
    +-> 规划：创建带依赖的TaskCreate
    |
    +-> 识别任务波次：无阻塞的任务
    |
    +-> 选择生成后端（Codex子Agent | Claude团队 | 备用任务）
    |
    +-> 分配任务：TaskUpdate(taskId, owner="worker-<id>", status="in_progress")
    |
    +-> 通过选定后端生成工作Agent
    |       工作Agent接收预分配任务，原子化执行
    |
    +-> 等待完成（wait() | SendMessage | TaskOutput）
    |
    +-> 验证：完成后审核变更
    |
    +-> 清理后端资源（close_agent | TeamDelete | 无操作）
    |
    +-> 重复：若有更多工作，创建新团队并制定新规划

Execution

执行流程

Given

/swarm

调用

/swarm

后：

Step 0: Select Local Spawn Backend (MANDATORY)

步骤0：选择本地生成后端（必填）

Use runtime capability detection, not hardcoded assumptions:

If
```
spawn_agent
```
is available, use Codex experimental sub-agents
Else if
```
TeamCreate
```
is available, use Claude native teams
Else use background task fallback (
```
Task(run_in_background=true)
```
)

See

skills/shared/SKILL.md

("Runtime-Native Spawn Backend Selection") for the shared contract used by all orchestration skills.

基于运行时能力检测选择，而非硬编码假设：

若
```
spawn_agent
```
可用，使用Codex实验性子Agent
否则若
```
TeamCreate
```
可用，使用Claude原生团队
否则使用后台任务备用方案（
```
Task(run_in_background=true)
```
）

所有编排技能遵循的通用协议，请参阅

skills/shared/SKILL.md

中的“Runtime-Native Spawn Backend Selection”章节。

Step 1: Ensure Tasks Exist

步骤1：确保任务存在

Use TaskList to see current tasks. If none, create them:

TaskCreate(subject="Implement feature X", description="Full details...")
TaskUpdate(taskId="2", addBlockedBy=["1"])  # Add dependencies after creation

通过TaskList查看当前任务。若无任务则创建：

TaskCreate(subject="Implement feature X", description="Full details...")
TaskUpdate(taskId="2", addBlockedBy=["1"])  # 创建后添加依赖

Step 2: Identify Wave

步骤2：识别任务波次

Find tasks that are:

Status:
```
pending
```
No blockedBy (or all blockers completed)

These can run in parallel.

筛选符合以下条件的任务：

状态：
```
pending
```
无blockedBy依赖（或所有依赖已完成）

这些任务可并行执行。

Steps 3-6: Spawn Workers, Validate, Finalize

步骤3-6：生成工作Agent、验证、收尾

For detailed local mode execution (team creation, worker spawning, race condition prevention, git commit policy, validation contract, cleanup, and repeat logic), read
skills/swarm/references/local-mode.md
.

本地模式执行的详细说明（团队创建、工作Agent生成、竞争条件预防、Git提交策略、验证协议、清理及重复逻辑），请阅读
skills/swarm/references/local-mode.md
。

Example Flow

示例流程

Mayor: "Let's build a user auth system"

1. /plan -> Creates tasks:
   #1 [pending] Create User model
   #2 [pending] Add password hashing (blockedBy: #1)
   #3 [pending] Create login endpoint (blockedBy: #1)
   #4 [pending] Add JWT tokens (blockedBy: #3)
   #5 [pending] Write tests (blockedBy: #2, #3, #4)

2. /swarm -> Spawns agent for #1 (only unblocked task)

3. Agent #1 completes -> #1 now completed
   -> #2 and #3 become unblocked

4. /swarm -> Spawns agents for #2 and #3 in parallel

5. Continue until #5 completes

6. /vibe -> Validate everything

Mayor: "Let's build a user auth system"

1. /plan -> 创建任务：
   #1 [pending] 创建用户模型
   #2 [pending] 添加密码哈希（依赖：#1）
   #3 [pending] 创建登录端点（依赖：#1）
   #4 [pending] 添加JWT令牌（依赖：#3）
   #5 [pending] 编写测试用例（依赖：#2、#3、#4）

2. /swarm -> 为#1（唯一无阻塞任务）生成Agent

3. Agent #1完成 -> #1状态变为已完成
   -> #2和#3变为无阻塞状态

4. /swarm -> 为#2和#3并行生成Agent

5. 持续执行直至#5完成

6. /vibe -> 验证所有内容

Key Points

核心要点

Runtime-native local mode - Auto-selects Codex sub-agents or Claude teams
Universal orchestration contract - Same swarm behavior across Claude and Codex sessions
Pre-assigned tasks - Mayor assigns tasks before spawning; workers never race-claim
Fresh worker contexts - New sub-agents/teammates per wave preserve Ralph isolation
Wave execution - Only unblocked tasks spawn
Mayor orchestrates - You control the flow, workers report via backend channel
Retry via message/input - Use
```
send_input
```
(Codex) or
```
SendMessage
```
(Claude)
Atomic execution - Each worker works until task done
Graceful fallback - If richer APIs unavailable, fall back to
```
Task(run_in_background=true)
```

运行时原生本地模式 - 自动选择Codex子Agent或Claude团队
通用编排协议 - 在Claude和Codex会话中实现一致的Swarm行为
预分配任务 - Mayor在生成Agent前分配任务；工作Agent不会争抢任务
全新工作Agent上下文 - 每个波次生成新的子Agent/团队成员，保持Ralph隔离特性
波次执行 - 仅为无阻塞任务生成Agent
Mayor编排控制 - 由你控制流程，工作Agent通过后端渠道汇报
通过消息/输入重试 - 使用
```
send_input
```
（Codex）或
```
SendMessage
```
（Claude）
原子化执行 - 每个工作Agent持续执行直至任务完成
优雅降级 - 若无法使用更丰富的API，降级为
```
Task(run_in_background=true)
```

Integration with AgentOps

与AgentOps的集成

This ties into the full workflow:

/research -> Understand the problem
/plan -> Decompose into beads issues
/crank -> Autonomous epic loop
    +-- /swarm -> Execute each wave in parallel
/vibe -> Validate results
/post-mortem -> Extract learnings

Direct use (no beads):

TaskCreate -> Define tasks
/swarm -> Execute in parallel

The knowledge flywheel captures learnings from each agent.

该技能可融入完整工作流：

/research -> 理解问题
/plan -> 分解为beads任务
/crank -> 自主史诗级循环
    +-- /swarm -> 并行执行每个任务波次
/vibe -> 验证结果
/post-mortem -> 提取经验教训

直接使用（无需beads）：

TaskCreate -> 定义任务
/swarm -> 并行执行

知识飞轮会捕获每个Agent的经验教训。

Task Management Commands

任务管理命令

undefined

undefined

List all tasks

列出所有任务

TaskList()

Mark task complete after notification

收到通知后标记任务完成

TaskUpdate(taskId="1", status="completed")

Add dependency between tasks

添加任务间依赖

TaskUpdate(taskId="2", addBlockedBy=["1"])

undefined

TaskUpdate(taskId="2", addBlockedBy=["1"])

undefined

Parameters

参数说明

Parameter	Description	Default
`--mode=local\|distributed`	Execution mode	`local`
`--max-workers=N`	Max concurrent workers	5
`--from-wave <json-file>`	Load wave from OL hero hunt output (see OL Wave Integration)	-
`--bead-ids`	Specific beads to work (comma-separated, distributed mode)	Auto from `bd ready`
`--wait`	Wait for all workers to complete (distributed mode)	false
`--timeout`	Max time to wait if `--wait` (distributed mode)	30m

参数	描述	默认值
`--mode=local\|distributed`	执行模式	`local`
`--max-workers=N`	最大并发工作Agent数	5
`--from-wave <json-file>`	从OL hero hunt输出加载任务波次（参阅OL Wave集成）	-
`--bead-ids`	要处理的特定bead（逗号分隔，仅分布式模式）	自动从 `bd ready` 获取
`--wait`	等待所有工作Agent完成（仅分布式模式）	false
`--timeout`	若启用 `--wait` ，最大等待时长（仅分布式模式）	30m

When to Use Swarm

Swarm适用场景

Scenario	Use
Multiple independent tasks	`/swarm` (parallel)
Sequential dependencies	`/swarm` with blockedBy
Mix of both	`/swarm` spawns waves, each wave parallel

场景	是否使用
多个独立任务	`/swarm` （并行执行）
存在顺序依赖	带blockedBy参数的 `/swarm`
混合场景	`/swarm` 按波次生成Agent，每个波次并行执行

Why This Works: Ralph Wiggum Pattern

技术原理：Ralph Wiggum模式

Follows the Ralph Wiggum Pattern: fresh context per execution unit.

Wave-scoped worker set = spawn workers -> execute -> cleanup -> repeat (fresh context each wave)
Mayor IS the loop - Orchestration layer, manages state across waves
Workers are atomic - One task, one spawn, one result
TaskList as memory - State persists in task status, not agent context
Filesystem for artifacts - Files written by workers, committed by team lead
Backend messaging for coordination - Workers report to team lead, never to each other

遵循Ralph Wiggum Pattern：每个执行单元拥有全新上下文。

波次范围的工作Agent集合 = 生成Agent -> 执行任务 -> 清理资源 -> 重复（每个波次均为全新上下文）
Mayor作为循环核心 - 编排层，管理跨波次的状态
工作Agent原子化 - 一个任务、一次生成、一个结果
TaskList作为记忆体 - 状态存储在任务状态中，而非Agent上下文
文件系统存储工件 - 工作Agent写入文件，由团队负责人提交
后端消息用于协调 - 工作Agent仅向团队负责人汇报，彼此间无通信

Integration with Crank

与Crank的集成

When

/crank

invokes

/swarm

: Crank bridges beads to TaskList, swarm executes with fresh-context agents, crank syncs results back.

You Want	Use	Why
Fresh-context parallel execution	`/swarm`	Each spawned agent is a clean slate
Autonomous epic loop	`/crank`	Loops waves via swarm until epic closes
Just swarm, no beads	`/swarm` directly	TaskList only, skip beads
RPI progress gates	`/ratchet`	Tracks progress; does not execute work

当

/crank

调用

/swarm

时：Crank将beads转换为TaskList任务，Swarm使用全新上下文的Agent执行任务，Crank同步结果回传。

需求	使用方式	原因
全新上下文并行执行	`/swarm`	每个生成的Agent均为干净环境
自主史诗级循环	`/crank`	通过Swarm循环执行波次直至史诗任务完成
仅使用Swarm，无需beads	直接调用 `/swarm`	仅依赖TaskList，跳过beads
RPI进度门控	`/ratchet`	跟踪进度；不执行实际工作

Distributed Mode

分布式模式

For the full distributed mode specification (tmux + Agent Mail, experimental), read
skills/swarm/references/distributed-mode.md
.

分布式模式完整规范（tmux + Agent Mail，实验性），请阅读
skills/swarm/references/distributed-mode.md
。

OL Wave Integration

OL Wave集成

When

/swarm --from-wave <json-file>

is invoked, the swarm reads wave data from an OL hero hunt output file and executes it with completion backflow to OL.

调用

/swarm --from-wave <json-file>

时，Swarm会从OL hero hunt输出文件读取任务波次数据并执行，完成后将结果回传至OL。

Pre-flight

前置检查

bash

undefined

bash

undefined

--from-wave requires ol CLI on PATH

--from-wave要求PATH中存在ol CLI

which ol >/dev/null 2>&1 || { echo "Error: ol CLI required for --from-wave. Install ol or use swarm without wave integration." exit 1 }


If `ol` is not on PATH, exit immediately with the error above. Do not fall back to normal swarm mode.

which ol >/dev/null 2>&1 || { echo "Error: ol CLI required for --from-wave. Install ol or use swarm without wave integration." exit 1 }


若`ol`不在PATH中，立即退出并输出上述错误信息，不降级为普通Swarm模式。

Input Format

输入格式

The

--from-wave

JSON file contains

ol hero hunt

output:

json

{
  "wave": [
    {"id": "ol-527.1", "title": "Add auth middleware", "spec_path": "quests/ol-527/specs/ol-527.1.md", "priority": 1},
    {"id": "ol-527.2", "title": "Fix rate limiting", "spec_path": "quests/ol-527/specs/ol-527.2.md", "priority": 2}
  ],
  "blocked": [
    {"id": "ol-527.3", "title": "Integration tests", "blocked_by": ["ol-527.1", "ol-527.2"]}
  ],
  "completed": [
    {"id": "ol-527.0", "title": "Project setup"}
  ]
}

--from-wave

指定的JSON文件包含

ol hero hunt

输出：

json

{
  "wave": [
    {"id": "ol-527.1", "title": "Add auth middleware", "spec_path": "quests/ol-527/specs/ol-527.1.md", "priority": 1},
    {"id": "ol-527.2", "title": "Fix rate limiting", "spec_path": "quests/ol-527/specs/ol-527.2.md", "priority": 2}
  ],
  "blocked": [
    {"id": "ol-527.3", "title": "Integration tests", "blocked_by": ["ol-527.1", "ol-527.2"]}
  ],
  "completed": [
    {"id": "ol-527.0", "title": "Project setup"}
  ]
}

Execution

执行流程

Parse the JSON file and extract the
```
wave
```
array.
Create TaskList tasks from wave entries (one
```
TaskCreate
```
per entry):

for each entry in wave:
    TaskCreate(
        subject="[{entry.id}] {entry.title}",
        description="OL bead {entry.id}\nSpec: {entry.spec_path}\nPriority: {entry.priority}\n\nRead the spec file at {entry.spec_path} for full requirements.",
        metadata={
            "ol_bead_id": entry.id,
            "ol_spec_path": entry.spec_path,
            "ol_priority": entry.priority
        }
    )

Execute swarm normally on those tasks (Step 2 onward from main execution flow). Tasks are ordered by priority (lower number = higher priority).
Completion backflow: After each worker completes a bead task AND passes validation, the team lead runs the OL ratchet command to report completion back to OL:

bash

undefined

解析JSON文件并提取
```
wave
```
数组。
从波次条目创建TaskList任务（每个条目对应一个
```
TaskCreate
```
）：

for each entry in wave:
    TaskCreate(
        subject="[{entry.id}] {entry.title}",
        description="OL bead {entry.id}\nSpec: {entry.spec_path}\nPriority: {entry.priority}\n\nRead the spec file at {entry.spec_path} for full requirements.",
        metadata={
            "ol_bead_id": entry.id,
            "ol_spec_path": entry.spec_path,
            "ol_priority": entry.priority
        }
    )

正常执行Swarm处理这些任务（从主执行流程的步骤2开始）。任务按优先级排序（数值越小优先级越高）。
完成结果回传：每个工作Agent完成bead任务并通过验证后，团队负责人运行OL ratchet命令将完成状态回传至OL：

bash

undefined

Extract quest ID from bead ID (e.g., ol-527.1 -> ol-527)

从bead ID中提取任务ID（例如：ol-527.1 -> ol-527）

QUEST_ID=$(echo "$BEAD_ID" | sed 's/.[^.]*$//')

ol hero ratchet "$BEAD_ID" --quest "$QUEST_ID"


**Ratchet result handling:**

| Exit Code | Meaning | Action |
|-----------|---------|--------|
| 0 | Bead complete in OL | Mark task completed, log success |
| 1 | Ratchet validation failed | Mark task as failed, log the validation error from stderr |

5. **After all wave tasks complete**, report a summary that includes both swarm results and OL ratchet status for each bead.

QUEST_ID=$(echo "$BEAD_ID" | sed 's/.[^.]*$//')

ol hero ratchet "$BEAD_ID" --quest "$QUEST_ID"


**Ratchet结果处理：**

| 退出码 | 含义 | 操作 |
|-----------|---------|--------|
| 0 | OL中bead已完成 | 标记任务为已完成，记录成功日志 |
| 1 | Ratchet验证失败 | 标记任务为失败，记录stderr中的验证错误 |

5. **所有波次任务完成后**，生成包含Swarm结果和每个bead的OL ratchet状态的汇总报告。

Example

示例

/swarm --from-wave /tmp/wave-ol-527.json

/swarm --from-wave /tmp/wave-ol-527.json

Reads wave JSON -> creates 2 tasks from wave entries

读取波次JSON -> 从波次条目创建2个任务

Spawns workers for ol-527.1 and ol-527.2

为ol-527.1和ol-527.2生成工作Agent

On completion of ol-527.1:

完成ol-527.1后：

ol hero ratchet ol-527.1 --quest ol-527 -> exit 0 -> bead complete

ol hero ratchet ol-527.1 --quest ol-527 -> 退出码0 -> bead完成

On completion of ol-527.2:

完成ol-527.2后：

ol hero ratchet ol-527.2 --quest ol-527 -> exit 0 -> bead complete

ol hero ratchet ol-527.2 --quest ol-527 -> 退出码0 -> bead完成

Wave done: 2/2 beads ratcheted in OL

波次完成：2/2个bead已在OL中标记完成

---

---

References

参考文档

Local Mode Details:
```
skills/swarm/references/local-mode.md
```

Distributed Mode:

skills/swarm/references/distributed-mode.md

Validation Contract:

skills/swarm/references/validation-contract.md

Agent Mail Protocol: See
```
skills/shared/agent-mail-protocol.md
```
for message format specifications
Parser (Go):
```
cli/internal/agentmail/
```
- shared parser for all message types

本地模式详情：
```
skills/swarm/references/local-mode.md
```

分布式模式：

skills/swarm/references/distributed-mode.md

验证协议：

skills/swarm/references/validation-contract.md

Agent Mail协议： 消息格式规范请参阅
```
skills/shared/agent-mail-protocol.md
```
解析器（Go）：
```
cli/internal/agentmail/
```
- 所有消息类型的通用解析器