create-beads-orchestration

创建 Beads 编排

为 Claude Code 设置轻量级多 Agent 编排，并使用原生 Git 的任务跟踪。

此技能的作用

此技能会初始化一套完整的多 Agent 工作流，其中：

• 编排器（你）调查问题、管理任务并委派实现工作
• 监督者（专用 Agent）在隔离的工作树中执行修复
• Beads CLI 使用原生 Git 的任务管理跟踪所有工作
• 钩子自动强制执行工作流规范

每项任务都会在 .worktrees/bd-{BEAD_ID}/ 下拥有自己的工作树，使主目录保持整洁，并支持并行工作。

Beads 看板 UI

设置过程会自动检测 Beads Kanban UI，并据此进行配置。如果未找到，将询问你是否要安装。

---

步骤 0：检测设置状态（始终首先运行）

**在执行任何其他操作之前，检测这是全新设置还是重启后的恢复设置。**

检查引导初始化文件：

ls .claude/agents/scout.md 2>/dev/null && echo "BOOTSTRAP_COMPLETE" || echo "FRESH_SETUP"

如果是 BOOTSTRAP_COMPLETE：

• 引导初始化已在之前的会话中运行
• 直接跳到步骤 4：运行发现
• 不要询问项目信息，也不要再次运行引导初始化

如果是 FRESH_SETUP：

• 这是全新安装
• 继续执行步骤 1：获取项目信息

---

工作流概览

| 步骤 | 操作 | 运行时机 | |------|------|----------| | 0 | 检测设置状态 | **始终**（用于确定流程） | | 1 | 向用户获取项目信息 | 仅限全新设置 | | 2 | 运行引导初始化 | 仅限全新设置 | | 3 | **停止** - 指示用户重启 | 仅限全新设置 | | 4 | 运行发现 Agent | 重启后，或引导初始化已完成时 |

只有运行完步骤 4（发现）后，设置才算完成。

---

步骤 1：获取项目信息（仅限全新设置）

**继续执行步骤 2 之前，必须获取项目信息，并检测/询问是否使用看板 UI。**

1. 项目目录：安装位置（默认：当前工作目录）
2. 项目名称：用于 Agent 模板（如未提供，将从 package.json/pyproject.toml 自动推断）
3. 看板 UI：自动检测，或询问用户是否要安装

1.1 获取项目目录和名称

询问用户，或从 package.json/pyproject.toml 自动检测。

1.2 检测或安装看板 UI

which bead-kanban 2>/dev/null && echo "KANBAN_FOUND" || echo "KANBAN_NOT_FOUND"

如果是 KANBAN_FOUND → 使用 --with-kanban-ui 标志。告知用户：

检测到 Beads Kanban UI。将通过 API 配置工作树管理。

如果是 KANBAN_NOT_FOUND → 询问：

AskUserQuestion(
  questions=[
    {
      "question": "Beads Kanban UI not detected. It adds a visual kanban board with dependency graphs and API-driven worktree management. Install it?",
      "header": "Kanban UI",
      "options": [
        {"label": "Yes, install it (Recommended)", "description": "Runs: npm install -g beads-kanban-ui"},
        {"label": "Skip", "description": "Use git worktrees directly. You can install later."}
      ],
      "multiSelect": false
    }
  ]
)

• 如果选择“Yes” → 运行 npm install -g beads-kanban-ui，然后使用 --with-kanban-ui 标志
• 如果选择“Skip” → 不要使用 --with-kanban-ui 标志

---

步骤 2：运行引导初始化

# With Kanban UI:
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --with-kanban-ui

# Without Kanban UI (git worktrees only):
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}"

引导初始化脚本将：

1. 安装 beads CLI（通过 brew、npm 或 go）
2. 初始化 .beads/ 目录
3. 将 Agent 模板复制到 .claude/agents/
4. 将钩子复制到 .claude/hooks/
5. 配置 .claude/settings.json
6. 创建包含编排器指令的 CLAUDE.md
7. 更新 .gitignore

继续之前，请确认引导初始化已成功完成。

---

步骤 3：停止 - 用户必须重启

**必须在此处停止，并指示用户重启 Claude Code。**

告知用户：

设置阶段已完成。现在必须重启 Claude Code。

新的钩子和 MCP 配置只有在重启后才会加载。

重启后：

1. 打开同一个项目目录
2. 告诉我“Continue orchestration setup”，或再次运行 /create-beads-orchestration
3. 我将运行发现 Agent 以完成设置

不要跳过重启，否则编排将无法运行。

不要在本次会话中继续执行步骤 4。必须重启。

---

第 4 步：运行发现（重启后或检测到后）

**在以下情况下运行此步骤：** - 第 0 步检测到 `BOOTSTRAP_COMPLETE`，或 - 用户重启后返回并表示“继续设置”，或再次运行了 `/create-beads-orchestration`

1. 验证引导流程已完成（检查 .claude/agents/scout.md）——已在第 0 步完成
2. 运行发现 Agent：

Task(
    subagent_type="discovery",
    prompt="Detect tech stack and create supervisors for this project"
)

发现流程将：

• 扫描 package.json、requirements.txt、Dockerfile 等文件
• 从外部目录获取专业 Agent
• 将 beads 工作流注入各个主管 Agent
• 将主管 Agent 写入 .claude/agents/

3. 发现流程完成后，告知用户：

编排设置已完成！

已创建的主管 Agent：[列出发现流程创建的内容]

现在可以使用编排工作流：

• 使用 bd create "Task name" -d "Description" 创建任务
• 编排器会将任务委派给合适的主管 Agent
• 所有工作都必须经过代码审查才能完成

---

创建的内容

• Beads CLI，用于基于 Git 的原生任务跟踪（一个 bead = 一个 worktree = 一个任务）
• 核心 Agent：scout、detective、architect、scribe、code-reviewer（均通过 Claude Task 运行）
• 发现 Agent：自动检测技术栈并创建专用主管 Agent
• Hooks：强制执行编排器规范、代码审查关卡和简洁回复
• 每个任务使用独立 worktree 的工作流：在 .worktrees/bd-{BEAD_ID}/ 中隔离开发

使用 --with-kanban-ui 时：

• 通过 API（localhost:3008）创建 worktree；API 不可用时回退到 Git
• 需要运行 Beads Kanban UI

不使用 --with-kanban-ui 时：

• 通过原始 Git 命令创建 worktree

Epic 工作流（跨领域功能）

对于需要多个主管 Agent 的功能（例如 DB + API + 前端），请使用 epic 工作流：

何时使用 Epic

任务类型	工作流
单一领域（一个主管 Agent）	独立 bead
跨领域（多个主管 Agent）	带子任务的 Epic

Epic 工作流步骤

1. 创建 Epic：bd create "Feature name" -d "Description" --type epic
2. 创建设计文档（如有需要）：派遣 architect 创建 .designs/{EPIC_ID}.md
3. 关联设计文档：bd update {EPIC_ID} --design ".designs/{EPIC_ID}.md"
4. 创建带依赖关系的子任务：

   bd create "DB schema" -d "..." --parent {EPIC_ID}              # BD-001.1
   bd create "API endpoints" -d "..." --parent {EPIC_ID} --deps BD-001.1  # BD-001.2
   bd create "Frontend" -d "..." --parent {EPIC_ID} --deps BD-001.2       # BD-001.3
   

5. 按顺序派遣：使用 bd ready 查找未被阻塞的任务（每个子任务都有自己的 worktree）
6. 由用户合并每个 PR：等待子任务的 PR 合并后，再派遣下一个任务
7. 关闭 Epic：所有子任务合并后运行 bd close {EPIC_ID}

设计文档

设计文档可确保 Epic 子任务之间保持一致：

• Schema 定义（精确的列名和类型）
• API 契约（端点、请求/响应结构）
• 共享常量/枚举
• 各层之间的数据流

关键规则：编排器会派遣 architect 创建设计文档。编排器绝不会直接编写设计文档。

Hooks 强制执行 Epic 工作流

• enforce-sequential-dispatch.sh：如果任务存在未解决的阻塞项，则阻止派遣
• enforce-bead-for-supervisor.sh：要求所有主管 Agent 都提供 BEAD_ID
• validate-completion.sh：主管 Agent 完成前，验证 worktree、推送状态和 bead 状态

要求

• beads CLI：由引导流程自动安装（通过 brew、npm 或 go）

更多信息

查看完整文档：https://github.com/AvivK5498/The-Claude-Protocol