swarm-migrate

swarm-migrate — 跨仓库迁移集群

一条命令，N 个仓库，一个协调器，一个台账。

适用场景

当需要在 3 个或更多 仓库中落地形态相同的转换（工作流升级、依赖升级、codemod、引入 lint 规则、密钥轮换、运行手册标题）时使用。不要用于单仓库工作——那是 implement。不要用于探索新方案——那是 brainstorm。

这项技能的由来是：275 场会话的经验表明，有 25 场会话耗费在手动协调 PR 级联上（M164 deploy-migration、M17 yg-mcp-core 提取、在 14 个仓库中推出 @v1 可复用工作流）。流程总是：选一个仓库、创建分支、应用变更、推送、查看 CI，然后重复。此工具将重复步骤自动化。

与 CC /workflows（2.1.154）的区别：CC 的动态工作流会在后台协调数十到数百个 Agent，并通过 /workflows 报告结果。swarm-migrate 则有意采用不同方式：它是一个由协调器主导、在前台运行的 DAG，带有 CI 门禁、自动解决冲突并变基，以及遇到新型失败时停止——你可以观察它的运行，并且它会在首次遇到意外失败时停止。需要大规模、即发即忘的后台扇出时，选择 CC /workflows；需要每个步骤都经过 CI 门禁，并且有人工可见的台账时，选择 swarm-migrate。CC 2.1.202 在 /config 中新增了动态工作流规模设置（小／中／大 Agent 数量），用于建议 /workflows 启动多少个 Agent——这是提示，而非强制上限，因此在手动限制扇出规模前请先检查此设置。

输入

YAML 规范文件，路径为 swarm-specs/<name>.yaml：

name: bump-actions-checkout-v4
description: "Pin @actions/checkout to v4 across all repos"

# Topology — repos in dependency order. Coordinator only proceeds
# to a downstream repo after every upstream parent has merged green.
repos:
  - path: ~/coding/yonatan-hq/platform
    upstream: []
  - path: ~/coding/yonatan-hq/ventures/jobscraper
    upstream: [platform]   # waits for platform to merge first

# Transformation — applied identically per repo. The agent runs this
# inside the isolated worktree, then verifies with the next field.
transform:
  type: codemod              # codemod | regex | command
  command: |
    grep -rl 'actions/checkout@v3' .github/workflows | \
      xargs sed -i '' 's|actions/checkout@v3|actions/checkout@v4|g'

# Verification — must pass before PR opens. Coordinator skips the repo
# if it fails locally (records skip-reason in ledger).
verify:
  - command: "git diff --quiet"
    expect: nonzero            # must have changes
  - command: "grep -r 'actions/checkout@v3' .github/workflows"
    expect: nonzero            # zero matches = clean

# PR shape — title, body, base branch
pr:
  branch_prefix: chore/bump-checkout-v4
  title: "chore(ci): pin @actions/checkout to v4"
  body_file: swarm-specs/bump-actions-checkout-v4.pr.md
  base: main
  labels: [chore, ci]

# CI gate — coordinator waits for required checks to pass before
# moving downstream. Set to false for dry-run, or in repos without CI.
ci_gate:
  required_checks: ["build", "test"]
  timeout_minutes: 20
  on_failure: pause            # pause | skip | abort

# Limits
max_parallel: 4
abort_on_novel_failure: true

工作原理

┌────────────────────────────────┐
│ COORDINATOR (you)              │
│ reads spec → builds DAG →       │
│ writes .swarm-state.json       │
└─────────────────┬──────────────┘
     ┌────────────┼────────────┐
┌──────────┐ ┌──────────┐ ┌──────────┐
│ WORKER A │ │ WORKER B │ │ WORKER C │
│ (repo 1) │ │ (repo 2) │ │ (repo 3) │
└────┬─────┘ └────┬─────┘ └────┬─────┘
     └─────────── isolated worktrees ─────┘
                  │ each: clone branch, transform,
                  │ verify, push, open PR, wait for CI, report
                  ▼
┌────────────────────────────────┐
│ .swarm-state.json              │
│ rolling ledger of {repo,       │
│ status, pr_url, ci_state,      │
│ last_action_at}                │
└────────────────────────────────┘

每个工作者都是一次 Agent 工具调用（用于处理管道工作的子 Agent 类型为 git-operations-engineer，用于处理带有架构特征的迁移时则为 backend-system-architect）。协调器（你，也就是这项技能）会在各轮之间读取台账，并决定是否启动下游轮次或暂停。

推送，不要轮询（CC 2.1.224+）

工作者通过向协调器发送消息来报告状态变更（CI 通过、CI 失败、新型失败、已跳过），而不是由协调器在各轮之间重新读取台账：

**跨会话回复会发送到父会话（CC 2.1.248）：**当子 Agent 向另一个会话发送 SendMessage 时，回复会送达父会话的对话，而不会送达子 Agent；子 Agent 发送消息后会继续执行，父会话读取回复。跨会话 SendMessage / ListAgents 也适用于 Bedrock、Vertex 和 Foundry，并且在禁用遥测时也可用（CC 2.1.248）。

• 作为 Agent 工具子 Agent 启动的工作者使用会话内的 SendMessage（自 CC 2.1.77 起可用）。
• 作为独立会话或 claude -p 进程运行的工作者使用跨会话消息（CC 2.1.224，参见 chain-patterns Pattern 10）。-p 工作者必须在 --settings 中设置 crossSessionInbound: "accept" 才能接收回复。

重要：跨会话消息无法保证送达——入站控制可能会拦截或拒绝消息。.swarm-state.json 仍然是权威的持久化记录，每次状态变更仍会写入其中。消息是低延迟信号；台账才是真实记录。

阶段 1 — 规范验证

加载 <spec-file.yaml>。验证：

• 每个 repos[].path 都存在且是 git 仓库（使用 git -C <path> rev-parse 进行检查）。
• transform.command 在试运行模式下返回 0（或者 transform.type: codemod 解析为已在 swarm-specs/codemods/ 中注册的已知 codemod）。
• 每个 upstream 引用都指向已声明的仓库（不存在悬空依赖）。
• pr.body_file 存在且非空。

如果任何检查失败，则中止并打印失败项表格。不要继续。

阶段 2 — 拓扑排序

根据 upstream 边构建 DAG。检测到循环依赖时，中止。按拓扑轮次对节点分组（第 0 轮 = 无依赖，第 1 轮 = 仅依赖第 0 轮，……）。协调器每次启动一轮。

在运行此技能的仓库根目录下写入 .swarm-state.json：

{
  "spec": "swarm-specs/bump-actions-checkout-v4.yaml",
  "started_at": "2026-05-16T17:00:00Z",
  "waves": [
    { "id": 0, "repos": ["platform"] },
    { "id": 1, "repos": ["jobscraper"] }
  ],
  "repos": {
    "platform": { "status": "pending", "pr_url": null, "ci_state": null, "last_action_at": null },
    "jobscraper": { "status": "blocked", "blocked_on": ["platform"], "pr_url": null }
  }
}

阶段 3 — 分派工作波次

对于当前波次中的每个仓库，并行执行（受 max_parallel 限制）：

1. 工作树 — 在 origin/<base> 上创建隔离的工作树，路径为 <repo>/../<repo>-swarm-<spec-name>。绝不修改当前工作树。
2. 分支 — git checkout -b <branch_prefix>-<short-sha>。
3. 转换 — 运行 transform.command（或应用 codemod）。将标准输出捕获到 .swarm-logs/<repo>-transform.log。
4. 验证 — 运行每个 verify[].command，断言退出状态与 expect 匹配。如果不匹配，在账本中将仓库标记为 skipped 并注明原因，不要推送。
5. 推送 + PR — 推送分支，通过 gh pr create 创建 PR。在账本中更新 PR URL。
6. 监视 CI — 每隔 45 秒轮询一次 gh pr checks <n>，最长不超过 ci_gate.timeout_minutes。每次状态转换时都在账本中更新 ci_state。

步骤 1–5 使用 Agent 工具，并设置 subagent_type: ork:git-operations-engineer，以精简主上下文。协调器只读取账本。

阶段 4 — 波次门控

每个波次结束后，检查账本：

• 全部为 green → 放行下一个波次。
• 有任何 pending CI → 继续轮询。
• 有任何 red CI → 根据 ci_gate.on_failure 处理：
  • pause → 暂停整个工作群，在 .swarm-state.json 中写入摘要，展示失败日志，并询问用户。
  • skip → 将仓库标记为 failed-ci，继续处理其他仓库（但除非下游仓库明确不依赖此仓库，否则阻止下游仓库继续）。
  • abort → 终止整个工作群，保持未关闭的 PR 原样，绝不合并。

阶段 5 — 冲突时自动变基

如果下游仓库的工作器在变基时遇到合并冲突（因为上游已合并），工作器将：

1. 重新获取上游的合并提交 SHA。
2. 尝试 git rebase origin/<base>。如果没有冲突 → 推送并更新账本。
3. 如果有冲突 → 在账本中标记冲突文件，不要自动解决，并将情况上报给协调器。冲突是自动修复工具最容易提交错误代码的地方。

阶段 6 — 最终报告

所有波次完成后（或工作群暂停／中止时），在 .swarm-logs/<spec-name>-report.md 下生成一份 Markdown 报告：

# Swarm report: bump-actions-checkout-v4

Completed: 12/14 repos · paused: 2 · duration: 47 min

| repo            | status  | PR    | CI     | duration |
|-----------------|---------|-------|--------|----------|
| platform        | merged  | #3456 | green  | 8 min    |
| jobscraper      | merged  | #281  | green  | 6 min    |
| ...                                                       |
| dormant-repo-1  | skipped | —     | —      | (no CI runner configured) |
| trading-ai      | paused  | #99   | red    | (novel failure — see logs) |

## Novel failures (escalated)
- trading-ai #99: pyproject lockfile mismatch — see .swarm-logs/trading-ai-ci.log

完成标准。 完成意味着：规范中的每个仓库都有一个已打开且 CI 通过的 PR（绝不由工作群合并），或已说明原因并跳过，或已暂停且记录了新的失败情况，并且最终报告已写入。遵循 Read("../../shared/rules/long-run-protocol.md")：无需用户输入即可执行的步骤要继续推进；只有在无法继续或执行任何破坏性操作之前才停止并询问；接受子 Agent 的结果前，先检查其证据；对于任何无法确认的事项，注明检查位置。

硬性规则

• 绝不合并 PR。工作群负责创建 PR；由人类合并。用户如有需要，可在工作群执行完毕后通过 gh pr merge --auto 启用自动合并。
• 绝不强制推送。如果工作器无法快进，则暂停。
• 绝不离开规范声明的 repos[] 范围。即使某项转换似乎也能帮助其他仓库。
• 始终隔离凭据。工作器使用用户的 gh 身份验证；协调器绝不记录令牌，只记录 URL。
• 始终遵守现有分支保护规则。如果 gh pr create 因需要指定审阅者或其他规则而失败，这是预期行为，不是需要绕过的问题。

实际会遇到的故障模式

模式	表现	缓解措施
锁文件过期	依赖升级后，CI 在 npm ci 时失败	规范中包含 post_transform.command: npm install 步骤
分支保护阻止创建 PR	gh pr create 以非零状态退出	协调器将仓库标记为 blocked-by-protection，并向用户说明
拓扑循环	阶段 2 中止	重新指定上游依赖关系
协调器在执行过程中崩溃	.swarm-state.json 写入不完整	此技能支持恢复：使用相同规范重新运行，它会读取账本并跳过 merged／green 仓库
工作器子 Agent 挂起	超过 5 分钟没有账本更新	协调器使该 Agent 超时，将仓库标记为 worker-timeout，并展示日志

相关技能

• 上游 — 使用 brainstorm 设计规范，使用 visualize-plan 在派发前以 ASCII 预览 DAG。
• 下游 — 合并后在每个仓库执行 verify，使用 /status 扫查整个组织，若某个工作进程遇到 CI 失败，则使用 /ci-debug。
• 可组合使用 — create-pr（每个工作进程都会调用它）、github-operations（集群执行后批量更新标签和里程碑）。

此技能不会做什么

• 不会编造规范。规范由你编写；此技能负责执行。
• 不会跨多个数据库执行架构迁移（请使用单仓库技能和 database-patterns）。
• 不会编排生产部署——只会创建 PR；部署是独立的关卡（平台的 deploy-operator）。
• 不会绕过 create-pr 的 playground-gate 规则——如果仓库强制要求，每个 PR 正文都必须包含 playground 引用。

调用示例

# Dry-run: build the DAG, verify spec, do NOT push or open PRs
swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml --dry-run

# Live: dispatch up to 4 workers in parallel
swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml --max-parallel=4

# Resume after pause: same command, the ledger remembers
swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml

为什么需要此技能（一段话）

你在一个月内进行了 25 次会话，手动协调跨仓库 PR。包括 14 个仓库的 @v1 工作流推出、M17 yg-mcp-core 抽取，以及 M164 部署迁移。每次会话的模式都相同：协调者（你）在脑中记着 DAG，依次派发工作进程（还是你）到不同的终端标签页，并在笔记里手动整理状态表。此技能将协调者变成 YAML 文件，并让工作进程成为并行子 Agent。DAG、台账、自动变基、波次关卡——你一直手动处理的所有事务——现在都能一次性编码。你编写规范，然后离开；回来时，就能看到报告。