GitHub Sync Coordinator 解析：基于 ruv-swarm 多智能体协调的跨包依赖同步与版本对齐工作流（RuView 仓库实践）

导读

GitHub Sync Coordinator 是 RuView 仓库在 .claude/commands/github/sync-coordinator.md 中沉淀的一份 Claude Code 命令定义，描述了一种"多包同步 + 版本对齐 + 跨仓库集成"的可执行工作流：通过 gh CLI 与 GitHub 内容/PR API 完成包依赖与文档的跨仓库同步，再以 ruv-swarm（mcp__claude-flow__*）多智能体工具对「依赖分析、集成开发、验证测试、质量评审」进行角色化编排，最终以原子化 PR 交付变更。读完本文，你将掌握：Sync Coordinator 的工具栈与角色分工、三种核心同步模式的完整命令序列、批量同步的端到端流程，以及版本对齐、文档单一真源（source of truth）与集成测试矩阵三类同步策略的设计要点，并能在自己拥有写权限的多包/多仓库项目中直接复用该模板。

提示：命令文档中的目标包为 claude-code-flow 与 ruv-swarm，目标路径（如 /workspaces/ruv-FANN/...）与 :owner/:repo 均为模板占位符，实际启用前需替换为你拥有写权限的真实仓库地址与名称。

一、定位：这份命令在本仓库中的角色

Sync Coordinator 文件位于仓库的 Claude 自定义命令目录 .claude/commands/github/ 下，与 github-modes.md、pr-manager.md、multi-repo-swarm.md、release-manager.md、workflow-automation.md 等共同构成一套面向 GitHub 日常协作的命令族。该目录的入口索引 .claude/commands/github/README.md 只列出了 github-swarm、repo-analyze、pr-enhance、issue-triage、code-review 五个命令，说明 sync-coordinator.md 属于随功能演进新增的扩展命令定义。

值得注意的是，同一主题在 .claude/agents/github/sync-coordinator.md 下还有一份带 YAML frontmatter 的 Agent 版定义（声明了 name、type: coordination、允许的 tools 以及 hooks.pre/post），正文与 commands 版基本一致，并额外补充了"Advanced Swarm Synchronization Features"（多智能体协调架构、冲突解决、同步指标）等高级用法。两份文件可以互为补充阅读，本文主体以 commands 版为准，高级部分会标注来源。

文档开篇给出的 Purpose 是：Multi-package synchronization and version alignment with ruv-swarm coordination for seamless integration between claude-code-flow and ruv-swarm packages，即——通过 ruv-swarm 的多智能体协调，完成 claude-code-flow 与 ruv-swarm 两个包之间的依赖同步、版本对齐与无缝集成。

二、能力清单：Sync Coordinator 覆盖哪些同步诉求

命令定义了五项核心能力：

能力	说明	落点
Package synchronization	带智能依赖解析的包同步	比对两个 package.json，解析依赖交集与冲突
Version alignment	跨多仓库的版本对齐	采用统一策略（如 highest_common）统一 Node/依赖版本区间
Cross-package integration	带自动化测试的跨包集成	单分支内同时落地两个包的代码/配置变更并跑测试
Documentation synchronization	文档同步以保证一致的用户体验	以单一真源同步 CLAUDE.md 等共享文档
Release coordination	配合自动化部署流水线的发布协调	以规格化的 PR body 输出发布/集成就绪信息

五项能力覆盖了"依赖→版本→代码→文档→发布"的完整同步链路，属于后续使用模式与策略章节的总纲。

三、工具栈：GitHub 文件操作 + ruv-swarm 协调 + 宿主工具

命令声明可用的工具分为三组：

1. GitHub MCP 工具（mcp__github__*）

   • mcp__github__push_files：向指定分支一次推送多个文件（批量写入，配合原子同步使用）
   • mcp__github__create_or_update_file：创建或更新单个文件
   • mcp__github__get_file_contents：读取远端文件内容（用于比对源文件与目标文件）
   • mcp__github__create_pull_request：创建工作流收尾的集成 PR
   • mcp__github__search_repositories：在仓库层面搜索定位目标

2. ruv-swarm / claude-flow 协调工具（mcp__claude-flow__*） commands 版概括为"all swarm coordination tools"。Agent 版 frontmatter（.claude/agents/github/sync-coordinator.md）给出了更完整的实例清单，可交叉印证：swarm_init、agent_spawn、task_orchestrate、memory_usage、coordination_sync、load_balance。它们分别负责初始化 swarm、孵化指定角色 Agent、并行/顺序编排任务、在 swarm 共享记忆中存取同步状态、跨 Agent 同步协调与任务负载均衡。

3. 宿主（Claude Code）内置工具 TodoWrite / TodoRead（任务看板跟踪）、Task、Bash（执行 gh CLI 与 npm 命令）、Read / Write / Edit / MultiEdit（本地文件读写与批量编辑）。

这套工具栈的分工逻辑是：GitHub MCP 管远端文件的"读与写"，gh CLI 通过 Bash 承担"建分支/取 sha/建 PR"等需要原生命令细节的操作，ruv-swarm 则负责把整件事拆成多 Agent 协同执行。

四、核心使用模式一：包依赖同步（Synchronize Package Dependencies）

模式一解决"两个包的 package.json 存在版本漂移"的场景。完整命令序列如下：

// Initialize sync coordination swarm
mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 5 }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "Sync Coordinator" }
mcp__claude-flow__agent_spawn { type: "analyst", name: "Dependency Analyzer" }
mcp__claude-flow__agent_spawn { type: "coder", name: "Integration Developer" }
mcp__claude-flow__agent_spawn { type: "tester", name: "Validation Engineer" }

// Analyze current package states
Read("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow/package.json")
Read("/workspaces/ruv-FANN/ruv-swarm/npm/package.json")

// Synchronize versions and dependencies using gh CLI
// First create branch
Bash("gh api repos/:owner/:repo/git/refs -f ref='refs/heads/sync/package-alignment' -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')")

// Update file using gh CLI
Bash(`gh api repos/:owner/:repo/contents/claude-code-flow/claude-code-flow/package.json \
  --method PUT \
  -f message="feat: Align Node.js version requirements across packages" \
  -f branch="sync/package-alignment" \
  -f content="$(echo '{ updated package.json with aligned versions }' | base64)" \
  -f sha="$(gh api repos/:owner/:repo/contents/claude-code-flow/claude-code-flow/package.json?ref=sync/package-alignment --jq '.sha')")`)

// Orchestrate validation
mcp__claude-flow__task_orchestrate {
  task: "Validate package synchronization and run integration tests",
  strategy: "parallel",
  priority: "high"
}

这段流程值得拆解为 5 个步骤：

1. 初始化协调 swarm：swarm_init 采用 hierarchical（层级式）拓扑，上限 maxAgents: 5，然后依次孵化四个角色——coordinator（同步总控）、analyst（Dependency Analyzer，负责依赖状态分析）、coder（Integration Developer，负责写对齐后的文件）、tester（Validation Engineer，负责集成验证）。
2. 读取当前包状态：用 Read 并行读取两个包的 package.json，作为差异比对输入。
3. 创建特性分支：通过 gh api 在远端仓库创建 refs/heads/sync/package-alignment 分支，起始点取自 main 分支当前 HEAD 的 sha。这是"所有同步变更先落分支、不直写主干"的关键一步。
4. 推送对齐后的文件：gh api 的 PUT /repos/:owner/:repo/contents/{path} 更新 package.json，写入消息为"Align Node.js version requirements across packages"，并基于 ?ref=sync/package-alignment 读取旧文件 sha 一并提交。这里有两个技术要点：--method PUT 是 contents API 的更新语义；sha 参数必须与目标分支当前文件版本一致，否则 GitHub 会拒绝写入，这实际上给了同步操作一道天然的并发保护。
5. 编排验证：task_orchestrate 以 strategy: "parallel"、priority: "high" 并行执行同步校验与集成测试。

五、核心使用模式二：文档同步（Documentation Synchronization）

模式二把共享概念文档（以 CLAUDE.md 为例）在不同包之间保持一致。完整命令序列：

// Synchronize CLAUDE.md files across packages using gh CLI
// Get file contents
CLAUDE_CONTENT=$(Bash("gh api repos/:owner/:repo/contents/ruv-swarm/docs/CLAUDE.md --jq '.content' | base64 -d"))

// Update claude-code-flow CLAUDE.md to match using gh CLI
// Create or update branch
Bash("gh api repos/:owner/:repo/git/refs -f ref='refs/heads/sync/documentation' -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha') 2>/dev/null || gh api repos/:owner/:repo/git/refs/heads/sync/documentation --method PATCH -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')")

// Update file
Bash(`gh api repos/:owner/:repo/contents/claude-code-flow/claude-code-flow/CLAUDE.md \
  --method PUT \
  -f message="docs: Synchronize CLAUDE.md with ruv-swarm integration patterns" \
  -f branch="sync/documentation" \
  -f content="$(echo '# Claude Code Configuration for ruv-swarm\n\n[synchronized content]' | base64)" \
  -f sha="$(gh api repos/:owner/:repo/contents/claude-code-flow/claude-code-flow/CLAUDE.md?ref=sync/documentation --jq '.sha' 2>/dev/null || echo '')")`)

// Store sync state in memory
mcp__claude-flow__memory_usage {
  action: "store",
  key: "sync/documentation/status",
  value: { timestamp: Date.now(), status: "synchronized", files: ["CLAUDE.md"] }
}

这段流程引入了几个文档同步特有的技巧：

• 拉取真源内容：先把 ruv-swarm/docs/CLAUDE.md 当作"源"，gh api ... --jq '.content' | base64 -d 解码得到真实内容并存入变量 CLAUDE_CONTENT（仓库 API 返回的 content 字段是 base64 编码，必须先解码再复用）。
• 分支"创建或更新"二选一：先用 git/refs 创建 sync/documentation 分支，若分支已存在（命令失败，2>/dev/null 吞掉错误），则回退为 --method PATCH 更新该分支引用指向最新 main。这是同步工作流中常见的"幂等化"写法。
• 宽容 sha 处理：取目标文件 sha 时同样做了容错——目标文件不存在时（sha 为空串）则不带 sha 直接创建，从而实现"文档从无到有"与"更新已有文档"两种场景的兼容。
• 落记忆：完成后调用 mcp__claude-flow__memory_usage 的 store 动作，把 timestamp / status: "synchronized" / files: ["CLAUDE.md"] 写入 swarm 共享记忆，键为 sync/documentation/status。这样后续 Agent（或后续轮次的协调器）可以查询记忆判断"哪个文件、何时、以何种状态完成同步"，是"以记忆为状态存储"的体现。

六、核心使用模式三：跨包功能集成与协调 PR（Cross-Package Feature Integration）

当同步不只是"对齐版本"而是要"引入一个新功能（feature）"时，Sync Coordinator 采用"一次推送多个包的文件 + 一个描述完整的 PR"的模式。以"GitHub workflow integration"功能为例：

// Coordinate feature implementation across packages
mcp__github__push_files {
  owner: "ruvnet",
  repo: "ruv-FANN",
  branch: "feature/github-commands",
  files: [
    {
      path: "claude-code-flow/claude-code-flow/.claude/commands/github/github-modes.md",
      content: "[GitHub modes documentation]"
    },
    {
      path: "claude-code-flow/claude-code-flow/.claude/commands/github/pr-manager.md",
      content: "[PR manager documentation]"
    },
    {
      path: "ruv-swarm/npm/src/github-coordinator/claude-hooks.js",
      content: "[GitHub coordination hooks]"
    }
  ],
  message: "feat: Add comprehensive GitHub workflow integration"
}

// Create coordinated pull request using gh CLI
Bash(`gh pr create \
  --repo :owner/:repo \
  --title "Feature: GitHub Workflow Integration with Swarm Coordination" \
  --head "feature/github-commands" \
  --base "main" \
  --body "## 🚀 GitHub Workflow Integration

### Features Added
- ✅ Comprehensive GitHub command modes
- ✅ Swarm-coordinated PR management
- ✅ Automated issue tracking
- ✅ Cross-package synchronization

### Integration Points
- Claude-code-flow: GitHub command modes in .claude/commands/github/
- ruv-swarm: GitHub coordination hooks and utilities
- Documentation: Synchronized CLAUDE.md instructions

### Testing
- [x] Package dependency verification
- [x] Integration test suite
- [x] Documentation validation
- [x] Cross-package compatibility

### Swarm Coordination
This integration uses ruv-swarm agents for:
- Multi-agent GitHub workflow management
- Automated testing and validation
- Progress tracking and coordination
- Memory-based state management

---
🤖 Generated with Claude Code using ruv-swarm coordination`}

这段流程的操作要点：

• mcp__github__push_files 一次提交多文件：注意此例直接给出了具体的 owner/repo（ruvnet/ruv-FANN）与 feature/github-commands 分支，一次调用同时写入"命令文档（github-modes.md、pr-manager.md）"与"协调钩子实现（claude-hooks.js）"，这正是"跨包集成 = 文档 + 实现同分支落地"的原子性体现。
• PR 承载"证据链"：gh pr create 生成标题、--head 特性分支、--base main 的集成 PR，其 PR body 不是随意文本，而是结构化区块：Features Added（新增了什么）、Integration Points（变更分别落在哪个包的哪个目录）、Testing（勾选了依赖验证、集成测试套件、文档校验、跨包兼容四类验证）、Swarm Coordination（说明该集成如何依赖多 Agent 完成 GitHub 工作流管理、自动化验证、进度跟踪与记忆化状态管理）。这样的 PR 本身即可作为评审与归档依据。
• 同步既有的命令文档作为交付物：body 中"Claude-code-flow: GitHub command modes in .claude/commands/github/"与 .claude/commands/github/ 目录的组织方式一致——说明这套工作流在实践中"先同步命令定义，再同步运行时钩子，最后统一评审"，与本仓库命令族的组织方式互相印证。

七、批量同步：单条消息内的完整包同步工作流

文档专门给出了"Single Message - Complete Synchronization"的端到端示例，它把前三种模式压缩进一个请求，覆盖从 swarm 初始化到记忆落库的全流程：

[Single Message - Complete Synchronization]:
  // Initialize comprehensive sync swarm
  mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 6 }
  mcp__claude-flow__agent_spawn { type: "coordinator", name: "Master Sync Coordinator" }
  mcp__claude-flow__agent_spawn { type: "analyst", name: "Package Analyzer" }
  mcp__claude-flow__agent_spawn { type: "coder", name: "Integration Coder" }
  mcp__claude-flow__agent_spawn { type: "tester", name: "Validation Tester" }
  mcp__claude-flow__agent_spawn { type: "reviewer", name: "Quality Reviewer" }

  // Read current state of both packages
  Read("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow/package.json")
  Read("/workspaces/ruv-FANN/ruv-swarm/npm/package.json")
  Read("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow/CLAUDE.md")
  Read("/workspaces/ruv-FANN/ruv-swarm/docs/CLAUDE.md")

  // Synchronize multiple files simultaneously
  mcp__github__push_files {
    branch: "sync/complete-integration",
    files: [
      { path: "claude-code-flow/claude-code-flow/package.json", content: "[aligned package.json]" },
      { path: "claude-code-flow/claude-code-flow/CLAUDE.md", content: "[synchronized CLAUDE.md]" },
      { path: "claude-code-flow/claude-code-flow/.claude/commands/github/github-modes.md", content: "[GitHub modes]" }
    ],
    message: "feat: Complete package synchronization with GitHub integration"
  }

  // Run validation tests
  Bash("cd /workspaces/ruv-FANN/claude-code-flow/claude-code-flow && npm install")
  Bash("cd /workspaces/ruv-FANN/claude-code-flow/claude-code-flow && npm test")
  Bash("cd /workspaces/ruv-FANN/ruv-swarm/npm && npm test")

  // Track synchronization progress
  TodoWrite { todos: [
    { id: "sync-deps", content: "Synchronize package dependencies", status: "completed", priority: "high" },
    { id: "sync-docs", content: "Align documentation", status: "completed", priority: "medium" },
    { id: "sync-github", content: "Add GitHub command integration", status: "completed", priority: "high" },
    { id: "sync-test", content: "Validate synchronization", status: "completed", priority: "medium" },
    { id: "sync-pr", content: "Create integration PR", status: "pending", priority: "high" }
  ]}

  // Store comprehensive sync state
  mcp__claude-flow__memory_usage {
    action: "store",
    key: "sync/complete/status",
    value: {
      timestamp: Date.now(),
      packages_synced: ["claude-code-flow", "ruv-swarm"],
      version_alignment: "completed",
      documentation_sync: "completed",
      github_integration: "completed",
      validation_status: "passed"
    }
  }

与模式一对比，批量版本有三处升级：

1. 拓扑与角色升级：swarm 改为 mesh（网状）拓扑、maxAgents: 6，在 coordinator/analyst/coder/tester 基础上新增 reviewer（Quality Reviewer），即"写→测"之后引入"审"。
2. 读入面扩大：同时读入两个包的 package.json 与两份 CLAUDE.md，形成完整的差异矩阵。
3. 一次推送三类交付物：push_files 把「对齐的 package.json」「同步的 CLAUDE.md」「GitHub 命令文档」放上 sync/complete-integration 分支，然后在两个包目录分别执行 npm install 与 npm test 做本地验证。

收尾的两个动作值得关注：TodoWrite 看板把五个子任务（依赖同步/文档对齐/GitHub 命令集成/同步验证/创建 PR）显式标记为 completed 或 pending，让整个同步过程可被外部追踪；memory_usage 则以 packages_synced、version_alignment、documentation_sync、github_integration、validation_status 五个字段落库最终状态，构成一次可被查询、可复盘、可恢复的同步"会话记录"。

八、三类同步策略设计

1. 版本对齐策略（Version Alignment Strategy）

// Intelligent version synchronization
const syncStrategy = {
  nodeVersion: ">=20.0.0",  // Align to highest requirement
  dependencies: {
    "better-sqlite3": "^12.2.0",  // Use latest stable
    "ws": "^8.14.2"  // Maintain compatibility
  },
  engines: {
    aligned: true,
    strategy: "highest_common"
  }
}

该策略把同步决策抽象成数据对象：nodeVersion 取各包要求中的最高下限（对齐到 >=20.0.0）；运行时依赖如 better-sqlite3 取最新稳定版、ws 则保持兼容（^8.14.2），体现了"对齐"并非机械统一，而是按依赖性质区别对待；engines.strategy 字段明确标出 highest_common（最高公共版本）作为全局对齐规则。文档中这些版本号属于示例值，落地时应替换为你实际包依赖的解析结果。

2. 文档同步模式（Documentation Sync Pattern）

// Keep documentation consistent across packages
const docSyncPattern = {
  sourceOfTruth: "ruv-swarm/docs/CLAUDE.md",
  targets: [
    "claude-code-flow/claude-code-flow/CLAUDE.md",
    "CLAUDE.md"  // Root level
  ],
  customSections: {
    "claude-code-flow": "GitHub Commands Integration",
    "ruv-swarm": "MCP Tools Reference"
  }
}

这是"单一真源"（single source of truth）的具体实现：先指定 sourceOfTruth（此处为 ruv-swarm/docs/CLAUDE.md），再列出所有需要同步的 targets（包括嵌套包内与仓库根层的 CLAUDE.md）。最有价值的设计是 customSections：完全一致的"公共概念"从真源同步，而每个包允许保留各自的定制章节（如 claude-code-flow 保留 "GitHub Commands Integration"、ruv-swarm 保留 "MCP Tools Reference"），避免"一刀切覆盖"把包间差异也抹掉。

3. 集成测试矩阵（Integration Testing Matrix）

// Comprehensive testing across synchronized packages
const testMatrix = {
  packages: ["claude-code-flow", "ruv-swarm"],
  tests: [
    "unit_tests",
    "integration_tests",
    "cross_package_tests",
    "mcp_integration_tests",
    "github_workflow_tests"
  ],
  validation: "parallel_execution"
}

测试矩阵把验证分成五个由浅入深的层级：单包 unit_tests → 包内 integration_tests → 跨包 cross_package_tests → MCP 工具集成 mcp_integration_tests → 与真实 GitHub 工作流联动的 github_workflow_tests，并以 parallel_execution 并行执行以缩短验证耗时。这五层对应了前文"Package dependency verification / Integration test suite / Documentation validation / Cross-package compatibility"的 PR 自检清单。

九、最佳实践：保证同步质量的四条纪律

文档在策略之后总结了四条工程纪律，恰好回应前文三个模式中的隐患：

1. 原子同步（Atomic Synchronization）：相关联的变更必须用批量操作一次性提交（对应 push_files 的多文件语义），保证所有同步操作整体一致，并为失败同步预置回滚机制（对应后文的错误恢复章节）。
2. 版本管理（Version Management）：坚持语义化版本（semver）对齐、依赖兼容性校验、并支持自动化的版本号 bump 协调——避免手改 package.json 造成漂移。
3. 文档一致性（Documentation Consistency）：共享概念保持单一真源 + 包级定制章节（即第八节 docSyncPattern.customSections 的思路），并配自动化文档校验，防止"真源改了、目标忘同步"。
4. 测试集成（Testing Integration）：跨包测试验证、集成测试自动化、性能回归检测三管齐下，让"同步即回归测试"成为默认动作。

十、监控与度量：如何判断一次同步是否健康

Sync Coordinator 定义了四个同步质量指标与四类自动报告：

• 同步质量指标（Sync Quality Metrics）：包版本对齐百分比（Package version alignment percentage）、文档一致性得分（Documentation consistency score）、集成测试成功率（Integration test success rate）、同步完成耗时（Synchronization completion time）。
• 自动化报告（Automated Reporting）：每周同步状态报告（Weekly sync status reports）、依赖漂移检测（Dependency drift detection）、文档分叉告警（Documentation divergence alerts）、集成健康监控（Integration health monitoring）。

这些指标所对应的"状态值"就是前文 memory_usage 落库字段（版本对齐、文档同步、验证状态等）的量化版本，说明"监控"依赖"记忆化状态存储"提供数据底座。

十一、错误处理与恢复

命令对失败场景给出的处理面如下：

• 自动处理的错误类型：版本冲突解决（Version conflict resolution）、合并冲突检测与解决（Merge conflict detection and resolution）、测试失败恢复策略（Test failure recovery strategies）、文档同步冲突（Documentation sync conflicts）。
• 恢复流程（Recovery procedures）：关键失败时的自动回滚、增量式同步重试机制、复杂冲突时的人工介入点、以及跨同步操作的状态保持（State preservation across sync operations）。

十二、延伸：Agent 版定义中的高级 swarm 同步能力

commands 版到"错误处理与恢复"即结束；同主题的 Agent 版 .claude/agents/github/sync-coordinator.md 则进一步提供了 frontmatter 元数据与更细粒度的高级用法，可作为读者深化时的补充阅读：

• frontmatter 声明：该文件在 YAML 头中声明 type: coordination，并给出完整的 tools 白名单（在 commands 版 GitHub MCP 工具之外，还显式列出 swarm_init、agent_spawn、task_orchestrate、memory_usage、coordination_sync、load_balance），以及 hooks.pre/post——pre 阶段初始化多仓库同步 swarm、分析依赖并预存冲突检测状态；post 阶段验证各仓库同步结果、更新文档并生成含建议的同步报告。
• 多智能体协调架构：演示了 maxAgents: 10 的 hierarchical swarm，并在 coordinator/analyst/coder/tester/reviewer 之外再孵化 monitor（Sync Monitor）；随后用 task_orchestrate（strategy: "adaptive"、priority: "critical"、带 dependencies）编排"版本分析→依赖解析→集成测试"链式任务，再用 load_balance 把 package_json_sync、documentation_alignment、version_compatibility_check、integration_test_execution 四个任务在多 Agent 间做负载均衡。
• 冲突解决与恢复流程的 Agent 化：syncConflictResolver 按冲突影响度排序并生成 resolution_strategy: "automated_with_validation"；错误恢复则独立孵化 Error Monitor、Failure Analyzer、Recovery Developer 三角色，通过 coordination_sync 同步、以 incremental_rollback 增量回滚策略恢复，并把 agent_assignments 写入记忆。

（本节内容均出自 Agent 版文件 .claude/agents/github/sync-coordinator.md，其中出现的指标数值如 version_alignment_score: 98.5、integration_test_success_rate: 96.8 为演示示例值，不代表任何真实运行结果。）

十三、落地复用指南

由于本仓库只读，这里说明的是如何查看与本仓库外复用这套工作流：

1. 在仓库内研读：以 .claude/commands/github/sync-coordinator.md 为主线，对照 .claude/agents/github/sync-coordinator.md 补齐 frontmatter 与高级能力，再浏览同目录命令族 github-modes.md、pr-manager.md、multi-repo-swarm.md、release-manager.md 理解各命令边界；若需了解 swarm 协调工具的更广语义，可参考仓库内的 claude-flow-swarm.md 与 claude-flow-help.md。
2. 把模板翻译到自己的多包项目：复制本命令后，将 :owner/:repo 与 /workspaces/ruv-FANN/... 全部替换为你实际拥有写权限的仓库与本地路径；将 claude-code-flow、ruv-swarm 两个包名替换为你的真实包；依据第八节策略，先产出 syncStrategy、docSyncPattern、testMatrix 三份配置，再按第四至七节的模式执行。
3. 前置条件：目标环境需具备（a）GitHub CLI（gh）并完成认证（用于建分支、读写 contents、创建 PR）；（b）GitHub MCP 服务器（提供 push_files 等工具）；（c）可用的 mcp__claude-flow__* swarm 协调命名空间（仓库 .claude 目录中 claude-flow-* 命令族即此类能力的本地宿主入口）。
4. 执行纪律：始终遵循第九节四条最佳实践——同步变更走独立 sync/* 分支、文件写入携带正确 sha、验证并行执行、最终状态与任务看板落库记忆。

结语

GitHub Sync Coordinator 的价值不在"复制文件"本身，而在于把"跨包版本对齐、文档同步、功能集成"这类高频却易错的操作固化成可编排、可验证、可恢复的流水线：GitHub API 负责远端文件语义，gh CLI 负责底层原子操作，ruv-swarm 以多 Agent 分工并行压缩同步周期，memory_usage 与 TodoWrite 让每步状态可追踪，最终以信息完整的 PR 交付评审。理解这份命令，等于拿到一套可直接迁移到任何多包/多仓库 Node 项目上的"同步工作流参考实现"。