RuView AI 蜂群看板同步实战：project-board-sync 协调 Agent 与 GitHub Projects 双向同步全解析

本文基于 RuView 仓库内的协调型 Agent 定义文件 .claude/agents/github/project-board-sync.md，完整解析 project-board-sync 这个 "AI 蜂群 ↔ GitHub Projects" 桥接协调器的设计：它如何用 gh CLI 定位与初始化项目看板、如何用 .github/board-sync.yml 声明任务状态/Agent 类型/优先级的映射规则、如何执行卡片自动流转、多看板与跨组织同步，以及如何产出分析、报告与 KPI 指标。读完后你能够按文档原样复制全部命令与配置，在 Claude Code + claude-flow/ruv-swarm 蜂群工作流中搭建一套可视化的任务看板管理体系。

一、角色定位：.claude Agent 生态中的看板协调器

project-board-sync 不是普通文档，而是一个 Claude Code Agent 的完整定义。它的 YAML frontmatter 声明了角色元数据，这也是阅读该文档的第一把钥匙：

• name: project-board-sync，description 一句话概括职责：Synchronize AI swarms with GitHub Projects for visual task management, progress tracking, and team coordination（将 AI 蜂群与 GitHub Projects 同步，实现可视化任务管理、进度跟踪与团队协调）；
• type: coordination——从源码结构看，它属于 .claude/agents 目录下的协调类 Agent，与 .claude/agents/github/sync-coordinator.md、.claude/agents/github/swarm-issue.md 等 GitHub 域 Agent 构成一个协作矩阵；
• color: "#A8E6CF"——蜂群可视化中标识该 Agent 的颜色；
• tools 字段列出它被授予的全部工具：基础工具（Bash、Read、Write、Edit、Glob、Grep、LS、TodoWrite）之外，重点是 9 个 mcp__claude-flow__* MCP 工具：

MCP 工具	用途（结合文档正文推断）
mcp__claude-flow__swarm_init	初始化蜂群，作为看板同步的驱动主体
mcp__claude-flow__agent_spawn	按需派生 coder/tester/architect 等子 Agent
mcp__claude-flow__task_orchestrate	编排任务，产生需要映射到看板卡片的工作项
mcp__claude-flow__swarm_status	获取蜂群状态，作为看板 "Swarm Status" 字段的数据源
mcp__claude-flow__memory_usage	查询蜂群记忆占用，评估运行成本
mcp__claude-flow__github_repo_analyze	分析仓库结构，辅助卡片自动归类
mcp__claude-flow__github_pr_manage / github_issue_track / github_metrics	Issue/PR 数据拉取与指标统计，支撑分析报表
mcp__claude-flow__workflow_create / workflow_execute	创建并执行自动化工作流（如智能卡片流转规则）

文档还定义了两组 shell hooks，这是 Agent 运行时自动执行的检查点，值得单独拆解：

pre hooks（执行前门禁）——四条命令保证环境就绪后再进入同步逻辑：

gh auth status || (echo 'GitHub CLI not authenticated' && exit 1)   # gh 必须已认证，否则直接失败
gh project list --owner @me --limit 1 >/dev/null || echo 'No projects accessible'  # 至少能看到一个项目
git status --porcelain || echo 'Not in git repository'              # 必须处于 git 仓库内
gh api user | jq -r '.login' || echo 'API access check'            # 验证 API 访问与当前登录身份

post hooks（执行后验证）——同步完成后自动回读结果，相当于自检清单：

gh project list --owner @me --limit 3 | head -5
gh issue list --limit 3 --json number,title,state
git branch --show-current || echo 'Not on a branch'
gh repo view --json name,description

这套 "先验证环境、后执行、再回读状态" 的模式，是整个文档所有命令都成立的前提：所有 gh 命令要求已认证的 GitHub CLI，所有 npx claude-flow@v3alpha / npx ruv-swarm 命令要求对应 npm 包可用。

二、核心功能 1：看板初始化（Board Initialization）

初始化分三步：定位项目 ID、把蜂群绑定到项目、在项目中创建蜂群追踪字段。文档给出的完整命令为：

# Connect swarm to GitHub Project using gh CLI
# Get project details
PROJECT_ID=$(gh project list --owner @me --format json | \
  jq -r '.projects[] | select(.title == "Development Board") | .id')

# Initialize swarm with project
npx claude-flow@v3alpha github board-init \
  --project-id "$PROJECT_ID" \
  --sync-mode "bidirectional" \
  --create-views "swarm-status,agent-workload,priority"

# Create project fields for swarm tracking
gh project field-create $PROJECT_ID --owner @me \
  --name "Swarm Status" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "pending,in_progress,completed"

各参数的实际作用：

• 第一步用 gh project list --owner @me --format json 拉取当前用户名下全部 Projects，再用 jq 按标题精确匹配 "Development Board" 提取 id。这里的 id 是 GitHub Project v2 的 node ID（GraphQL 标识），后续所有 gh project 子命令都依赖它；
• board-init --sync-mode "bidirectional" 声明双向同步语义：蜂群侧任务状态变化会移动看板卡片，看板侧人工改动也会回流到蜂群任务（这一语义在后文 "Data Integrity" 最佳实践中再次强调 "Bidirectional sync validation"）；--create-views 则一次性创建三个预设视图：swarm-status（按蜂群状态）、agent-workload（按 Agent 负载）、priority（按优先级），与后文 "View Configuration" 章节的 JSON 视图定义相互呼应；
• 最后用原生 gh project field-create 创建一个名为 Swarm Status 的单选字段，选项为 pending,in_progress,completed。这说明设计思路是：蜂群状态不复用 Issue 状态，而是写入项目自定义字段，从而让看板列与卡片字段解耦，支持更细的状态空间。

值得注意的是版本差异：Agent 定义文件中使用的入口是 npx claude-flow@v3alpha github board-init；而同仓库的命令文档 commands/github/project-board-sync.md 与技能文件 .claude/skills/github-project-management/SKILL.md（v2.0.0）中，完全相同的命令族写为 npx ruv-swarm github board-init。两份文件除包名/版本标签外逐字一致，可以推断这是同一命令在 claude-flow 与 ruv-swarm 两个发行名下的等价调用，实际使用时以你所安装的 npm 包为准。

三、核心功能 2：任务状态同步（Task Synchronization）

把蜂群任务与项目卡片对齐的核心命令是 board-sync：

# Sync swarm tasks with project cards
npx claude-flow@v3alpha github board-sync \
  --map-status '{
    "todo": "To Do",
    "in_progress": "In Progress",
    "review": "Review",
    "done": "Done"
  }' \
  --auto-move-cards \
  --update-metadata

• --map-status 接受一段内联 JSON，把蜂群任务状态（todo / in_progress / review / done）映射到看板列名（To Do / In Progress / Review / Done）。这是同步语义的最小闭环：蜂群侧是英文小写下划线状态机，看板侧是人类可读的列名；
• --auto-move-cards 授权同步器直接改写卡片所在列；
• --update-metadata 在移动卡片的同时刷新卡片上的元数据（对应第二章节创建的 "Swarm Status" 自定义字段及后文 fields 中声明的 Agent Count / Complexity / ETA）。

而持久化的映射规则不放在命令行里，而是放在仓库内的 YAML 配置文件中——这正是下一节的内容。

四、核心功能 3：实时看板更新（Real-time Updates）

# Enable real-time board updates
npx claude-flow@v3alpha github board-realtime \
  --webhook-endpoint "https://api.example.com/github-sync" \
  --update-frequency "immediate" \
  --batch-updates false

三个参数定义了实时通道的形态：

• --webhook-endpoint：一个你自己部署的 HTTP 回调端点（文档示例用 https://api.example.com/github-sync 占位，落地时需替换为真实地址），由它承接 GitHub 侧事件并触发蜂群刷新；
• --update-frequency "immediate"：事件到达即刻更新，不做定时轮询；
• --batch-updates false：不合并批量写入。文档将 "immediate + 非批量" 作为实时性优先的配置，与之对应的取舍是 API 写入频率更高（gh API 存在 rate limit，这也是后文 board-diagnose --check "permissions,webhooks,rate-limits" 会检查 rate-limits 的原因）。

五、配置文件详解：.github/board-sync.yml 映射体系

文档 "Configuration" 章节给出了一份完整的看板映射配置，约定位置为仓库内 .github/board-sync.yml：

# .github/board-sync.yml
version: 1
project:
  name: "AI Development Board"
  number: 1

mapping:
  # Map swarm task status to board columns
  status:
    pending: "Backlog"
    assigned: "Ready"
    in_progress: "In Progress"
    review: "Review"
    completed: "Done"
    blocked: "Blocked"

  # Map agent types to labels
  agents:
    coder: "🔧 Development"
    tester: "🧪 Testing"
    analyst: "📊 Analysis"
    designer: "🎨 Design"
    architect: "🏗️ Architecture"

  # Map priority to project fields
  priority:
    critical: "🔴 Critical"
    high: "🟡 High"
    medium: "🟢 Medium"
    low: "⚪ Low"

  # Custom fields
  fields:
    - name: "Agent Count"
      type: number
      source: task.agents.length
    - name: "Complexity"
      type: select
      source: task.complexity
    - name: "ETA"
      type: date
      source: task.estimatedCompletion

逐项说明这份配置为什么是 "同步契约"：

1. version: 1 + project：声明配置格式版本与目标项目（name + number），用于在 gh project list 结果中定位与校验，防止同步器写错项目；
2. mapping.status：六态状态机 pending → assigned → in_progress → review → completed，外加一个旁路态 blocked，分别落位到 Backlog / Ready / In Progress / Review / Done / Blocked 六列。注意它与 board-sync --map-status 的四态 JSON 是两套粒度不同的映射：命令行参数适合快速场景，YAML 才是完整的声明式配置；
3. mapping.agents：把蜂群 Agent 类型翻译成带 emoji 的卡片标签。这与仓库 .claude/agents 目录的实际结构直接对应——从源码结构看，.claude/agents/core/ 下定义了 coder.md、planner.md、researcher.md、reviewer.md、tester.md 等核心 Agent，coder → Development、tester → Testing、architect → Architecture 的映射正是给这些真实存在的 Agent 角色打上看板标签；
4. mapping.priority：critical/high/medium/low 四档映射为带色点前缀的项目字段值，保证看板上的优先级视觉一致性；
5. mapping.fields：声明三个自定义字段及其 source 表达式——task.agents.length（任务关联 Agent 数量，number 型）、task.complexity（复杂度假定，select 型）、task.estimatedCompletion（预计完成时间，date 型）。source 以 task. 前缀引用蜂群任务对象属性，说明同步器内部维护着一个结构化任务对象，YAML 配置本质上是"从任务对象到项目字段"的投影规则。

视图配置（View Configuration）

与映射配置配套的是视图定义（JSON 形态），控制看板如何被"看"：

// Custom board views
{
  "views": [
    {
      "name": "Swarm Overview",
      "type": "board",
      "groupBy": "status",
      "filters": ["is:open"],
      "sort": "priority:desc"
    },
    {
      "name": "Agent Workload",
      "type": "table",
      "groupBy": "assignedAgent",
      "columns": ["title", "status", "priority", "eta"],
      "sort": "eta:asc"
    },
    {
      "name": "Sprint Progress",
      "type": "roadmap",
      "dateField": "eta",
      "groupBy": "milestone"
    }
  ]
}

• Swarm Overview：board 类型，按 status 分列、过滤 is:open、按 priority:desc 排序——这是 board-init --create-views "swarm-status,..." 创建的主视图；
• Agent Workload：table 类型，按 assignedAgent 分组，展示 title/status/priority/eta 四列并按 eta:asc 排序，本质是 "谁在做什么、何时交付" 的负载表；
• Sprint Progress：roadmap 类型，以 eta 日期字段为时间轴、按 milestone 分组，与后文 milestone-track 命令形成呼应。

六、自动化能力：自动分派、进度跟踪与智能卡片流转

1. Auto-Assignment（卡片自动分派）

# Automatically assign cards to agents
npx claude-flow@v3alpha github board-auto-assign \
  --strategy "load-balanced" \
  --consider "expertise,workload,availability" \
  --update-cards

--strategy "load-balanced" 指定负载均衡策略；--consider "expertise,workload,availability" 声明分派决策的三个维度——专长、当前负载、可用性；--update-cards 表示分派结果直接写回卡片。这与 mapping.agents 的 Agent 类型标签共同构成 "角色 → 标签 → 负载" 的闭环。

2. Progress Tracking（进度跟踪）

# Track and visualize progress
npx claude-flow@v3alpha github board-progress \
  --show "burndown,velocity,cycle-time" \
  --time-period "sprint" \
  --export-metrics

一次生成三类进度视图：燃尽（burndown）、速度（velocity）、周期时间（cycle-time），统计窗口锁定为 sprint，--export-metrics 将结果导出为指标数据供报表使用。

3. Smart Card Movement（智能卡片流转）

# Intelligent card state transitions
npx claude-flow@v3alpha github board-smart-move \
  --rules '{
    "auto-progress": "when:all-subtasks-done",
    "auto-review": "when:tests-pass",
    "auto-done": "when:pr-merged"
  }'

规则表把三件客观事实绑定到三个卡片状态迁移上：

• 全部子任务完成 → 卡片自动前进（auto-progress）；
• 测试通过 → 卡片进入评审列（auto-review）；
• PR 合并 → 卡片直接落位 Done（auto-done）。

这意味着看板进度不再依赖人工拖拽，而是由 "子任务勾选 / 测试结果 / PR 事件" 这类可验证信号驱动，正好与 frontmatter 中授予的 github_pr_manage、github_issue_track 工具能力对得上。

七、看板命令集：从 Issue 导入、批量操作到卡片模板

从 Issues 创建卡片

这是把 "Issue 池" 灌入 "项目看板" 的完整流水线，前半段是纯 gh CLI，后半段交给蜂群：

# Convert issues to project cards using gh CLI
# List issues with label
ISSUES=$(gh issue list --label "enhancement" --json number,title,body)

# Add issues to project
echo "$ISSUES" | jq -r '.[].number' | while read -r issue; do
  gh project item-add $PROJECT_ID --owner @me --url "https://github.com/$GITHUB_REPOSITORY/issues/$issue"
done

# Process with swarm
npx claude-flow@v3alpha github board-import-issues \
  --issues "$ISSUES" \
  --add-to-column "Backlog" \
  --parse-checklist \
  --assign-agents

要点：gh project item-add 按 issue 号逐个把 Issue 挂到项目（URL 由 $GITHUB_REPOSITORY 环境变量拼出）；随后 board-import-issues 接管，--add-to-column "Backlog" 对应 YAML 中 pending → Backlog 的映射，--parse-checklist 会解析 Issue 正文里的 Markdown 复选框作为子任务，--assign-agents 触发自动分派。

批量操作（Bulk Operations）

# Bulk card operations
npx claude-flow@v3alpha github board-bulk \
  --filter "status:blocked" \
  --action "add-label:needs-attention" \
  --notify-assignees

按 status:blocked 过滤出所有阻塞卡片，统一打上 needs-attention 标签并通知相关人——对应 YAML 状态机中的 blocked → Blocked 列，是阻塞项治理的入口。

卡片模板（Card Templates）

# Create cards from templates
npx claude-flow@v3alpha github board-template \
  --template "feature-development" \
  --variables '{
    "feature": "User Authentication",
    "priority": "high",
    "agents": ["architect", "coder", "tester"]
  }' \
  --create-subtasks

以 feature-development 模板 + 变量（特性名、优先级、Agent 名单）生成卡片，--create-subtasks 同时展开子任务。模板中的 agents 取值 architect/coder/tester 与 mapping.agents 的键名严格一致，说明模板变量与映射配置共享同一套 Agent 类型命名。

八、高级同步：多看板、跨组织、外部工具

1. Multi-Board Sync（多板同步）

# Sync across multiple boards
npx claude-flow@v3alpha github multi-board-sync \
  --boards "Development,QA,Release" \
  --sync-rules '{
    "Development->QA": "when:ready-for-test",
    "QA->Release": "when:tests-pass"
  }'

在 Development / QA / Release 三块板之间建立有向流转规则：卡片在 Development 板达到 ready-for-test 状态时流入 QA 板，QA 板 tests-pass 时流入 Release 板——本质上是用状态触发器把三块单项目板拼成一条流水线。

2. Cross-Organization Sync（跨组织同步）

# Sync boards across organizations
npx claude-flow@v3alpha github cross-org-sync \
  --source "org1/Project-A" \
  --target "org2/Project-B" \
  --field-mapping "custom" \
  --conflict-resolution "source-wins"

--source/--target 以 org/Project 形式指定两端项目；--field-mapping "custom" 指向自定义字段映射（即第五章 mapping.fields 的跨组织变体）；--conflict-resolution "source-wins" 声明冲突裁决策略——源端优先。冲突策略与 "Data Integrity" 最佳实践中的 "Conflict resolution strategies" 条目互为表里。

3. External Tool Integration（外部工具集成）

# Sync with external tools
npx claude-flow@v3alpha github board-integrate \
  --tool "jira" \
  --mapping "bidirectional" \
  --sync-frequency "5m" \
  --transform-rules "custom"

支持把看板与 Jira 等外部系统做 bidirectional 双向映射，同步频率 5m（对比 board-realtime 的 immediate，这里明确采用 5 分钟级轮询节奏），转换规则为 custom。

九、可视化与报表：Board Analytics、自定义仪表盘、报告分发

Board Analytics（基于 gh 数据的项目分析）

文档给出了一条 "先取数、后分析" 的完整链路：

# Generate board analytics using gh CLI data
# Fetch project data
PROJECT_DATA=$(gh project item-list $PROJECT_ID --owner @me --format json)

# Get issue metrics
ISSUE_METRICS=$(echo "$PROJECT_DATA" | jq -r '.items[] | select(.content.type == "Issue")' | \
  while read -r item; do
    ISSUE_NUM=$(echo "$item" | jq -r '.content.number')
    gh issue view $ISSUE_NUM --json createdAt,closedAt,labels,assignees
  done)

# Generate analytics with swarm
npx claude-flow@v3alpha github board-analytics \
  --project-data "$PROJECT_DATA" \
  --issue-metrics "$ISSUE_METRICS" \
  --metrics "throughput,cycle-time,wip" \
  --group-by "agent,priority,type" \
  --time-range "30d" \
  --export "dashboard"

数据流为：gh project item-list 拉取项目全部条目 → jq 筛选 content.type == "Issue" 的项 → 逐项 gh issue view 补齐 createdAt/closedAt/labels/assignees 元数据 → 交给 board-analytics 计算 throughput/cycle-time/wip 三类指标，按 agent,priority,type 三维分组，时间窗 30d，输出为 dashboard。

Custom Dashboards（仪表盘配置）

// Dashboard configuration
{
  "dashboard": {
    "widgets": [
      {
        "type": "chart",
        "title": "Task Completion Rate",
        "data": "completed-per-day",
        "visualization": "line"
      },
      {
        "type": "gauge",
        "title": "Sprint Progress",
        "data": "sprint-completion",
        "target": 100
      },
      {
        "type": "heatmap",
        "title": "Agent Activity",
        "data": "agent-tasks-per-day"
      }
    ]
  }
}

三种 widget 的组合覆盖了时间序列（每日完成任务折线图）、目标达成度（Sprint 完成度仪表、目标 100）与活跃度分布（Agent 每日任务热力图），其数据源正是 board-analytics/board-progress 导出的指标。

Reports（报告生成与分发）

# Generate reports
npx claude-flow@v3alpha github board-report \
  --type "sprint-summary" \
  --format "markdown" \
  --include "velocity,burndown,blockers" \
  --distribute "slack,email"

生成 sprint-summary 类型的 Markdown 报告，内容包含 velocity、burndown、blockers 三个板块，可分发到 Slack 与邮件。

十、工作流集成：Sprint、里程碑与发布规划

Sprint Management

# Manage sprints with swarms
npx claude-flow@v3alpha github sprint-manage \
  --sprint "Sprint 23" \
  --auto-populate \
  --capacity-planning \
  --track-velocity

--auto-populate 从看板自动填充 Sprint 内容，--capacity-planning 做容量规划，--track-velocity 持续跟踪速度——与第五章 "Sprint Progress" 视图、第六章 board-progress 的 velocity 指标构成同一数据面。

Milestone Tracking

# Track milestone progress
npx claude-flow@v3alpha github milestone-track \
  --milestone "v2.0 Release" \
  --update-board \
  --show-dependencies \
  --predict-completion

对 "v2.0 Release" 里程碑做进度跟踪：回写看板、展示依赖关系、预测完成时间。

Release Planning

# Plan releases using board data
npx claude-flow@v3alpha github release-plan-board \
  --analyze-velocity \
  --estimate-completion \
  --identify-risks \
  --optimize-scope

基于看板数据做四件事：分析速度、估算完成时间、识别风险、优化范围——即 "用历史吞吐反推可承诺的发布范围"。

十一、团队协作：工作量分配、站会与评审协调

Work Distribution

# Distribute work among team
npx claude-flow@v3alpha github board-distribute \
  --strategy "skills-based" \
  --balance-workload \
  --respect-preferences \
  --notify-assignments

与第六章 board-auto-assign --strategy "load-balanced" 相对，这里采用 skills-based（基于技能）策略，同时保留负载均衡约束、尊重个人偏好并在分派后发送通知。

Standup Automation

# Generate standup reports
npx claude-flow@v3alpha github standup-report \
  --team "frontend" \
  --include "yesterday,today,blockers" \
  --format "slack" \
  --schedule "daily-9am"

按团队（示例为 frontend）生成每日站会报告，覆盖 "昨天/今天/阻塞" 三段内容，输出到 Slack，排程 daily-9am。

Review Coordination

# Coordinate reviews via board
npx claude-flow@v3alpha github review-coordinate \
  --board "Code Review" \
  --assign-reviewers \
  --track-feedback \
  --ensure-coverage

把 "Code Review" 板当作评审工作台：自动指派评审人、跟踪反馈、确保覆盖度（每张待评审卡片都有人负责）。

十二、最佳实践（Best Practices）

文档给出三组共 12 条实践，是落地该同步体系时的验收清单：

1. Board Organization（看板组织）：清晰的列定义（Clear column definitions）；一致的标签体系（Consistent labeling system，对应 mapping.agents/mapping.priority 的枚举约束）；定期看板梳理（Regular board grooming）；自动化规则（Automation rules，对应 board-smart-move）；
2. Data Integrity（数据完整性）：双向同步校验（Bidirectional sync validation）；冲突解决策略（Conflict resolution strategies，对应 cross-org-sync --conflict-resolution）；审计轨迹（Audit trails）；定期备份（Regular backups，对应 board-recover --backup-id 的存在前提）；
3. Team Adoption（团队采纳）：培训材料；清晰的流程；定期回顾；反馈闭环。

十三、故障排查：诊断、性能与数据恢复

Sync Issues（同步问题诊断）

# Diagnose sync problems
npx claude-flow@v3alpha github board-diagnose \
  --check "permissions,webhooks,rate-limits" \
  --test-sync \
  --show-conflicts

一次检查三个最常见根因：permissions（gh token 权限是否覆盖 Projects API）、webhooks（第三章实时通道是否可达）、rate-limits（GitHub API 配额是否耗尽），随后 --test-sync 做试同步、--show-conflicts 列出状态冲突。

Performance（性能优化）

# Optimize board performance
npx claude-flow@v3alpha github board-optimize \
  --analyze-size \
  --archive-completed \
  --index-fields \
  --cache-views

四个优化动作：分析看板规模、归档已完成卡片、为字段建索引、缓存视图。

Data Recovery（数据恢复）

# Recover board data
npx claude-flow@v3alpha github board-recover \
  --backup-id "2024-01-15" \
  --restore-cards \
  --preserve-current \
  --merge-conflicts

从指定备份（--backup-id）恢复卡片；--preserve-current 保留当前卡片不直接覆盖，--merge-conflicts 对恢复冲突做合并处理——与 "Data Integrity" 中 "Regular backups" 实践形成完整的备份-恢复闭环。

十四、三种预设看板与 KPI 体系

文档 "Examples" 章节提供三种开箱即用的看板形态：

Agile Development Board（Scrum 敏捷板）

# Setup agile board
npx claude-flow@v3alpha github agile-board \
  --methodology "scrum" \
  --sprint-length "2w" \
  --ceremonies "planning,review,retro" \
  --metrics "velocity,burndown"

Kanban Flow Board（看板流）

# Setup kanban board
npx claude-flow@v3alpha github kanban-board \
  --wip-limits '{
    "In Progress": 5,
    "Review": 3
  }' \
  --cycle-time-tracking \
  --continuous-flow

--wip-limits 用 JSON 设定在制品上限（In Progress 最多 5 张、Review 最多 3 张），配合周期时间跟踪与持续流模式。

Research Project Board（研究项目板）

# Setup research board
npx claude-flow@v3alpha github research-board \
  --phases "ideation,research,experiment,analysis,publish" \
  --track-citations \
  --collaborate-external

按研究五阶段（ideation→research→experiment→analysis→publish）建列，支持引用追踪与外部协作。对 RuView 这类研究型仓库（大量 ADR 与研究文档，见 docs/adr），这种 "阶段列 = 研究阶段" 的板型尤其贴合日常节奏。

Metrics & KPIs

# Track board performance
npx claude-flow@v3alpha github board-kpis \
  --metrics '[
    "average-cycle-time",
    "throughput-per-sprint",
    "blocked-time-percentage",
    "first-time-pass-rate"
  ]' \
  --dashboard-url

四个核心 KPI：平均周期时间、每 Sprint 吞吐、阻塞时间占比、一次通过率；--dashboard-url 输出可直接挂接的仪表盘地址。

# Track team performance
npx claude-flow@v3alpha github team-metrics \
  --board "Development" \
  --per-member \
  --include "velocity,quality,collaboration" \
  --anonymous-option

团队侧指标按成员统计 velocity/quality/collaboration 三个维度，--anonymous-option 提供匿名选项以保护个体数据敏感性。

十五、在 RuView 仓库中的落点与延伸阅读

project-board-sync 是 RuView 仓库 .claude 智能体工作层中 "GitHub 域" 的一个组成部分，文档末尾给出的两条 "See also" 相对链接，换算到仓库根目录后分别是：

• swarm-issue.md——Issue 维度的蜂群管理 Agent；
• multi-repo-swarm.md——跨仓库蜂群 Agent。

与之配套的仓库内文件还有：

• commands/github/project-board-sync.md：同名命令文档，命令族与本文一致，但入口写为 npx ruv-swarm github ...，可作为包名差异时的对照参考；
• .claude/skills/github-project-management/SKILL.md：v2.0.0 的 GitHub 项目管理技能，前置条件（gh 已认证、ruv-swarm 或 claude-flow MCP 已配置、具备仓库权限）与本文的 hooks 检查项一一对应，并额外覆盖 Issue 分诊、Sprint 规划与 GitHub Actions 集成（ruvnet/swarm-action@v1）等内容；
• .claude/agents/github/sync-coordinator.md：多仓库同步协调器，与本文的 "多板/跨组织同步" 属于不同抽象层（代码/包级同步 vs 看板级同步），可结合阅读。

适用前提与限制：本文全部命令的生效前提与源文档 hooks 一致——gh 已认证且具备 Projects API 权限、处于 git 仓库内、claude-flow/ruv-swarm npm 包可用；--webhook-endpoint、--backup-id、--sprint 等参数值在文档中均为示例占位，实际使用时需替换为真实环境值；仓库内未包含 board-sync.yml 的已落盘实例，第五、九章的 YAML/JSON 应按原文模板创建到自己的仓库 .github/ 目录下使用。

小结：project-board-sync 的价值在于把 "AI 蜂群任务状态" 与 "GitHub Projects 看板" 之间原本靠人肉维护的关系，收敛为一份可声明（board-sync.yml 映射 + 视图 JSON）、可自动执行（smart-move 规则、auto-assign、realtime 通道）、可审计（diagnose/recover/audit trail）的同步契约。对任何用 Claude Code + 蜂群工作流驱动研发过程的团队，这套命令与配置都可以直接照抄起步：先跑通第二章的 board-init 三步，再按自己的状态机裁剪第五章的 mapping，最后用 board-smart-move 的三条规则让看板进度由事实信号自动驱动。