create-beads-orchestration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Beads Orchestration

搭建Beads编排系统

Set up lightweight multi-agent orchestration with git-native task tracking for Claude Code.

为Claude Code搭建基于git原生任务跟踪的轻量型多Agent编排系统。

What This Skill Does

该技能的功能

This skill bootstraps a complete multi-agent workflow where:

Orchestrator (you) investigates issues, manages tasks, delegates implementation
Supervisors (specialized agents) execute fixes in isolated worktrees
Beads CLI tracks all work with git-native task management
Hooks enforce workflow discipline automatically

Each task gets its own worktree at

.worktrees/bd-{BEAD_ID}/

, keeping main clean and enabling parallel work.

本技能可快速搭建一套完整的多Agent工作流，其中：

编排器（即你）负责排查问题、管理任务、委派实现工作
主管Agent（专业化Agent）在独立工作树中执行修复任务
Beads CLI 借助git原生任务管理功能跟踪所有工作
钩子自动强制执行工作流规范

每个任务都会在

.worktrees/bd-{BEAD_ID}/

目录下拥有独立的工作树，保持主分支整洁并支持并行工作。

Beads Kanban UI

Beads看板UI

The setup will auto-detect Beads Kanban UI and configure accordingly. If not found, you'll be offered to install it.

搭建过程会自动检测Beads Kanban UI并进行相应配置。如果未检测到，将提示你安装该工具。

Step 0: Detect Setup State (ALWAYS RUN FIRST)

步骤0：检测搭建状态（务必首先执行）

<detection-phase> **Before doing anything else, detect if this is a fresh setup or a resume after restart.**

Check for bootstrap artifacts:

bash

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

If
BOOTSTRAP_COMPLETE
:

Bootstrap already ran in a previous session
Skip directly to Step 4: Run Discovery
Do NOT ask for project info or run bootstrap again

If
FRESH_SETUP
:

This is a new installation
Proceed to Step 1: Get Project Info </detection-phase>

<detection-phase> **在执行任何操作之前，请先检测当前是全新搭建还是重启后继续操作。**

检查搭建产物：

bash

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

如果返回
BOOTSTRAP_COMPLETE
：

搭建流程已在之前的会话中完成
直接跳至步骤4：运行发现Agent
请勿再次询问项目信息或重新执行搭建流程

如果返回
FRESH_SETUP
：

这是全新安装
继续执行步骤1：获取项目信息 </detection-phase>

Workflow Overview

工作流概述

<mandatory-workflow> | Step | Action | When to Run | |------|--------|-------------| | 0 | Detect setup state | **ALWAYS** (determines path) | | 1 | Get project info from user | Fresh setup only | | 2 | Run bootstrap | Fresh setup only | | 3 | **STOP** - Instruct user to restart | Fresh setup only | | 4 | Run discovery agent | After restart OR if bootstrap already complete |

The setup is NOT complete until Step 4 (discovery) has run. </mandatory-workflow>

<mandatory-workflow> | 步骤 | 操作 | 执行时机 | |------|--------|-------------| | 0 | 检测搭建状态 | **必须**执行（决定后续流程） | | 1 | 向用户获取项目信息 | 仅全新搭建时执行 | | 2 | 运行搭建脚本 | 仅全新搭建时执行 | | 3 | **停止** - 指导用户重启 | 仅全新搭建时执行 | | 4 | 运行发现Agent | 重启后或搭建已完成时执行 |

只有完成步骤4（发现流程），搭建才真正完成。 </mandatory-workflow>

Step 1: Get Project Info (Fresh Setup Only)

步骤1：获取项目信息（仅全新搭建时执行）

<critical-step1> **YOU MUST GET PROJECT INFO AND DETECT/ASK ABOUT KANBAN UI BEFORE PROCEEDING TO STEP 2.**

Project directory: Where to install (default: current working directory)
Project name: For agent templates (will auto-infer from package.json/pyproject.toml if not provided)
Kanban UI: Auto-detect, or ask the user to install

</critical-step1>

<critical-step1> **在继续执行步骤2之前，必须获取项目信息并检测/询问关于看板UI的情况。**

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

</critical-step1>

1.1 Get Project Directory and Name

1.1 获取项目目录和名称

Ask the user or auto-detect from package.json/pyproject.toml.

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

1.2 Detect or Install Kanban UI

1.2 检测或安装看板UI

bash

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

If KANBAN_FOUND → Use

--with-kanban-ui

flag. Tell the user:

Detected Beads Kanban UI. Configuring worktree management via API.

If KANBAN_NOT_FOUND → Ask:

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
    }
  ]
)

If "Yes" → Run

npm install -g beads-kanban-ui

, then use

--with-kanban-ui

flag

If "Skip" → do NOT use
```
--with-kanban-ui
```
flag

bash

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。该工具可提供带有依赖图谱和API驱动工作树管理的可视化看板。是否安装？",
      "header": "看板UI",
      "options": [
        {"label": "是，安装（推荐）", "description": "执行命令：npm install -g beads-kanban-ui"},
        {"label": "跳过", "description": "直接使用git工作树。可后续再安装。"}
      ],
      "multiSelect": false
    }
  ]
)

如果选择“是” → 执行
```
npm install -g beads-kanban-ui
```
，然后使用
```
--with-kanban-ui
```
参数
如果选择“跳过” → 不使用
```
--with-kanban-ui
```
参数

Step 2: Run Bootstrap

步骤2：运行搭建脚本

bash

undefined

bash

undefined

With Kanban UI:

带看板UI的情况：

npx beads-orchestration@latest bootstrap
--project-name "{{PROJECT_NAME}}"
--project-dir "{{PROJECT_DIR}}"
--with-kanban-ui

Without Kanban UI (git worktrees only):

不带看板UI的情况（仅使用git工作树）：

npx beads-orchestration@latest bootstrap
--project-name "{{PROJECT_NAME}}"
--project-dir "{{PROJECT_DIR}}"


The bootstrap script will:
1. Install beads CLI (via brew, npm, or go)
2. Initialize `.beads/` directory
3. Copy agent templates to `.claude/agents/`
4. Copy hooks to `.claude/hooks/`
5. Configure `.claude/settings.json`
6. Create `CLAUDE.md` with orchestrator instructions
7. Update `.gitignore`

**Verify bootstrap completed successfully before proceeding.**

---

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`

**在继续之前，请确认搭建已成功完成。**

---

Step 3: STOP - User Must Restart

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

<critical> **YOU MUST STOP HERE AND INSTRUCT THE USER TO RESTART CLAUDE CODE.**

Tell the user:

Setup phase complete. You MUST restart Claude Code now.

The new hooks and MCP configuration will only load after restart.

After restarting:
Open this same project directory
Tell me "Continue orchestration setup" or run
/create-beads-orchestration
again
I will run the discovery agent to complete setup
Do not skip this restart - the orchestration will not work without it.

DO NOT proceed to Step 4 in this session. The restart is mandatory. </critical>

<critical> **必须在此处停止，并指导用户重启Claude Code。**

告知用户：

搭建阶段已完成。你必须立即重启Claude Code。

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

重启后：
打开同一个项目目录
告诉我“继续编排系统搭建”或再次运行
/create-beads-orchestration
我将运行发现Agent以完成搭建
请勿跳过此重启步骤 - 否则编排系统将无法正常工作。

请勿在本次会话中继续执行步骤4。重启是必须的。 </critical>

Step 4: Run Discovery (After Restart OR Detection)

步骤4：运行发现流程（重启后或检测到搭建已完成时执行）

<post-restart> **Run this step if:** - Step 0 detected `BOOTSTRAP_COMPLETE`, OR - User returned after restart and said "continue setup" or ran `/create-beads-orchestration` again

Verify bootstrap completed (check for
```
.claude/agents/scout.md
```
) - already done in Step 0
Run the discovery agent:

python

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

Discovery will:

Scan package.json, requirements.txt, Dockerfile, etc.
Fetch specialist agents from external directory
Inject beads workflow into each supervisor
Write supervisors to
```
.claude/agents/
```

After discovery completes, tell the user:

Orchestration setup complete!

Created supervisors: [list what discovery created]

You can now use the orchestration workflow:
Create tasks with
bd create "Task name" -d "Description"
The orchestrator will delegate to appropriate supervisors

All work requires code review before completion </post-restart>

<post-restart> **在以下情况执行此步骤：** - 步骤0检测到`BOOTSTRAP_COMPLETE`，或 - 用户重启后返回并说“继续搭建”或再次运行`/create-beads-orchestration`

验证搭建已完成（检查
```
.claude/agents/scout.md
```
是否存在）- 步骤0已完成此操作
运行发现Agent：

python

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/
```

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

编排系统搭建完成！

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

现在你可以使用编排工作流：
使用
bd create "Task name" -d "Description"
创建任务
编排器会将任务委派给合适的主管Agent

所有工作在完成前都需要代码评审 </post-restart>

What This Creates

搭建完成后的产物

Beads CLI for git-native task tracking (one bead = one worktree = one task)
Core agents: scout, detective, architect, scribe, code-reviewer (all run via Claude Task)
Discovery agent: Auto-detects tech stack and creates specialized supervisors
Hooks: Enforce orchestrator discipline, code review gates, concise responses
Worktree-per-task workflow: Isolated development in
```
.worktrees/bd-{BEAD_ID}/
```

With
--with-kanban-ui
:

Worktrees created via API (localhost:3008) with git fallback
Requires Beads Kanban UI running

Without
--with-kanban-ui
:

Worktrees created via raw git commands

Beads CLI：用于git原生任务跟踪（一个bead对应一个工作树和一个任务）
核心Agent：scout、detective、architect、scribe、code-reviewer（均通过Claude Task运行）
发现Agent：自动检测技术栈并创建专业化主管Agent
钩子：强制执行编排器规范、代码评审关卡、简洁响应要求
单任务单工作树工作流：在
```
.worktrees/bd-{BEAD_ID}/
```
中进行独立开发

使用
--with-kanban-ui
参数时：

通过API（localhost:3008）创建工作树（git作为备选方案）
需要运行Beads Kanban UI

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

通过原生git命令创建工作树

Epic Workflow (Cross-Domain Features)

史诗工作流（跨领域功能）

For features requiring multiple supervisors (e.g., DB + API + Frontend), use the epic workflow:

对于需要多个主管Agent协作的功能（如数据库 + API + 前端），请使用史诗工作流：

When to Use Epics

何时使用史诗

Task Type	Workflow
Single-domain (one supervisor)	Standalone bead
Cross-domain (multiple supervisors)	Epic with children

任务类型	工作流
单领域（仅需一个主管Agent）	独立bead
跨领域（需多个主管Agent）	包含子任务的史诗

Epic Workflow Steps

史诗工作流步骤

Create epic:

bd create "Feature name" -d "Description" --type epic

Create design doc (if needed): Dispatch architect to create
```
.designs/{EPIC_ID}.md
```

Link design:

bd update {EPIC_ID} --design ".designs/{EPIC_ID}.md"

Create children with dependencies:

bash

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

Dispatch sequentially: Use
```
bd ready
```
to find unblocked tasks (each child gets own worktree)
User merges each PR: Wait for child's PR to merge before dispatching next
Close epic:
```
bd close {EPIC_ID}
```
after all children merged

创建史诗：

bd create "Feature name" -d "Description" --type epic

创建设计文档（如有需要）：指派architect Agent创建
```
.designs/{EPIC_ID}.md
```

关联设计文档：

bd update {EPIC_ID} --design ".designs/{EPIC_ID}.md"

创建带依赖的子任务：

bash

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

按顺序委派任务：使用
```
bd ready
```
查找未被阻塞的任务（每个子任务拥有独立工作树）
用户合并每个PR：等待子任务的PR合并后再委派下一个任务
关闭史诗：所有子任务合并完成后，执行
```
bd close {EPIC_ID}
```

Design Docs

设计文档

Design docs ensure consistency across epic children:

Schema definitions (exact column names, types)
API contracts (endpoints, request/response shapes)
Shared constants/enums
Data flow between layers

Key rule: Orchestrator dispatches architect to create design docs. Orchestrator never writes design docs directly.

设计文档确保史诗的所有子任务保持一致性：

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

核心规则：编排器需指派architect Agent创建设计文档，不得直接编写设计文档。

Hooks Enforce Epic Workflow

钩子强制执行史诗工作流

enforce-sequential-dispatch.sh: Blocks dispatch if task has unresolved blockers
enforce-bead-for-supervisor.sh: Requires BEAD_ID for all supervisors
validate-completion.sh: Verifies worktree, push, bead status before supervisor completes

enforce-sequential-dispatch.sh：如果任务存在未解决的阻塞，将阻止任务委派
enforce-bead-for-supervisor.sh：所有主管Agent都需要关联BEAD_ID
validate-completion.sh：在主管Agent完成任务前，验证工作树、推送状态和bead状态

create-beads-orchestration

Original

Translation

Create Beads Orchestration

搭建Beads编排系统

What This Skill Does

该技能的功能

Beads Kanban UI

Beads看板UI

Step 0: Detect Setup State (ALWAYS RUN FIRST)

步骤0：检测搭建状态（务必首先执行）

Workflow Overview

工作流概述

Step 1: Get Project Info (Fresh Setup Only)

步骤1：获取项目信息（仅全新搭建时执行）

1.1 Get Project Directory and Name

1.1 获取项目目录和名称

1.2 Detect or Install Kanban UI

1.2 检测或安装看板UI

Step 2: Run Bootstrap

步骤2：运行搭建脚本

With Kanban UI:

带看板UI的情况：

Without Kanban UI (git worktrees only):

不带看板UI的情况（仅使用git工作树）：

Step 3: STOP - User Must Restart

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

Step 4: Run Discovery (After Restart OR Detection)

步骤4：运行发现流程（重启后或检测到搭建已完成时执行）

What This Creates

搭建完成后的产物

Epic Workflow (Cross-Domain Features)

史诗工作流（跨领域功能）

When to Use Epics

何时使用史诗

Epic Workflow Steps

史诗工作流步骤

Design Docs

设计文档

Hooks Enforce Epic Workflow

钩子强制执行史诗工作流

Requirements

要求

More Information

更多信息