Claude Code 多智能体编排系统 - 基于 Git 的轻量级任务追踪与工作流管理

create-beads-orchestration by avivk5498/the-claude-protocol

148 周安装量

160 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/avivk5498/the-claude-protocol --skill create-beads-orchestration

开发自动化版本控制

🇨🇳中文介绍

创建 Beads 编排系统

为 Claude Code 设置轻量级多智能体编排，并具备基于 git 的原生任务追踪功能。

此技能的作用

此技能引导建立一个完整的多智能体工作流，其中：

编排器（您）负责调查问题、管理任务、委派实施
监督者（专业智能体）在隔离的工作树中执行修复
Beads CLI 使用基于 git 的原生任务管理来追踪所有工作
钩子自动强制执行工作流纪律

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

Beads 看板 UI

安装程序会自动检测 Beads 看板 UI 并进行相应配置。如果未找到，将提供安装选项。

步骤 0：检测安装状态（务必首先运行）

检查引导程序产物：

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

如果输出 BOOTSTRAP_COMPLETE：

引导程序已在之前的会话中运行过
直接跳转到 步骤 4：运行发现

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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

项目目录：安装位置（默认：当前工作目录）
项目名称：用于智能体模板（如未提供，将从 package.json/pyproject.toml 自动推断）
看板 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 看板 UI。正在通过 API 配置工作树管理。

如果 KANBAN_NOT_FOUND → 询问：

AskUserQuestion(
  questions=[
    {
      "question": "未检测到 Beads 看板 UI。它提供了一个带有依赖关系图和 API 驱动的工作树管理的可视化看板。是否安装？",
      "header": "看板 UI",
      "options": [
        {"label": "是，安装它（推荐）", "description": "运行：npm install -g beads-kanban-ui"},
        {"label": "跳过", "description": "直接使用 git worktrees。您可以稍后安装。"}
      ],
      "multiSelect": false
    }
  ]
)

如果选择"是" → 运行 npm install -g beads-kanban-ui，然后使用 --with-kanban-ui 标志
如果选择"跳过" → 请勿使用 --with-kanban-ui 标志

步骤 2：运行引导程序

# 使用看板 UI：
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --with-kanban-ui

# 不使用看板 UI（仅限 git worktrees）：
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}"

安装 beads CLI（通过 brew、npm 或 go）
初始化 .beads/ 目录
将智能体模板复制到 .claude/agents/
将钩子复制到 .claude/hooks/
配置 .claude/settings.json
创建包含编排器说明的 CLAUDE.md
更新 .gitignore

在继续之前，请验证引导程序已成功完成。

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

安装阶段完成。您现在必须重启 Claude Code。

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

重启后：

打开同一个项目目录

告诉我"继续编排系统设置"或再次运行 /create-beads-orchestration

我将运行发现智能体以完成设置

请勿跳过此重启步骤 - 否则编排系统将无法工作。

请勿在此会话中继续执行步骤 4。重启是强制性的。

步骤 4：运行发现（重启后或检测到已完成引导时）

验证引导程序已完成（检查 .claude/agents/scout.md 是否存在）- 已在步骤 0 完成
运行发现智能体：

Task(
    subagent_type="discovery",
    prompt="检测技术栈并为此项目创建监督者"
)

扫描 package.json、requirements.txt、Dockerfile 等
从外部目录获取专业智能体
将 beads 工作流注入每个监督者
将监督者写入 .claude/agents/

发现完成后，告知用户：

编排系统设置完成！

已创建的监督者：[列出发现过程创建的内容]

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

使用 bd create "任务名称" -d "描述" 创建任务

编排器将委派给相应的监督者

所有工作在完成前都需要代码审查

此技能创建的内容

Beads CLI：用于基于 git 的原生任务追踪（一个 bead = 一个工作树 = 一个任务）
核心智能体：scout、detective、architect、scribe、code-reviewer（全部通过 Claude Task 运行）
发现智能体：自动检测技术栈并创建专业监督者
钩子：强制执行编排器纪律、代码审查关卡、简洁响应
每任务工作树工作流：在 .worktrees/bd-{BEAD_ID}/ 中进行隔离开发

使用 --with-kanban-ui 时：

通过 API（localhost:3008）创建工作树，并带有 git 回退机制
需要 Beads 看板 UI 正在运行

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

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

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

对于需要多个监督者的功能（例如，数据库 + API + 前端），请使用 史诗工作流：

任务类型	工作流
单一领域（一个监督者）	独立的 bead
跨领域（多个监督者）	带有子任务的史诗

史诗工作流步骤

创建史诗：bd create "功能名称" -d "描述" --type epic
创建设计文档（如果需要）：委派 architect 创建 .designs/{EPIC_ID}.md
链接设计文档：bd update {EPIC_ID} --design ".designs/{EPIC_ID}.md"

创建具有依赖关系的子任务：

bd create "数据库模式" -d "..." --parent {EPIC_ID}              # BD-001.1
bd create "API 端点" -d "..." --parent {EPIC_ID} --deps BD-001.1  # BD-001.2
bd create "前端" -d "..." --parent {EPIC_ID} --deps BD-001.2       # BD-001.3

顺序委派：使用 bd ready 查找未阻塞的任务（每个子任务获得自己的工作树）
用户合并每个 PR：等待子任务的 PR 合并后再委派下一个
关闭史诗：在所有子任务合并后，运行 bd close {EPIC_ID}

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

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

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

钩子强制执行史诗工作流

enforce-sequential-dispatch.sh：如果任务存在未解决的阻塞项，则阻止委派
enforce-bead-for-supervisor.sh：要求所有监督者提供 BEAD_ID
validate-completion.sh：在监督者完成任务前，验证工作树、推送、bead 状态

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

🇺🇸English

Create Beads Orchestration

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

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.

Beads Kanban UI

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

Step 0: Detect Setup State (ALWAYS RUN FIRST)

Check for bootstrap artifacts:

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

IfBOOTSTRAP_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

IfFRESH_SETUP:

This is a new installation
Proceed to Step 1: Get Project Info

Workflow Overview

The setup is NOT complete until Step 4 (discovery) has run.

Step 1: Get Project Info (Fresh Setup Only)

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

1.1 Get Project Directory and Name

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

1.2 Detect or Install Kanban UI

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

Step 2: Run Bootstrap

# 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}}"

The bootstrap script will:

Install beads CLI (via brew, npm, or go)
Initialize .beads/ directory
Copy agent templates to .claude/agents/
Copy hooks to .claude/hooks/
Configure .claude/settings.json
Create CLAUDE.md with orchestrator instructions
Update .gitignore

Verify bootstrap completed successfully before proceeding.

Step 3: STOP - User Must Restart

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.

Step 4: Run Discovery (After Restart OR Detection)

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

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

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

Epic Workflow (Cross-Domain Features)

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

When to Use Epics

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

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 :

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

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.

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

Requirements

beads CLI : Installed automatically by bootstrap (via brew, npm, or go)

More Information

See the full documentation: https://github.com/AvivK5498/The-Claude-Protocol

Weekly Installs

124

Repository

avivk5498/the-c…protocol

GitHub Stars

146

First Seen

Feb 2, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykFail

Installed on

opencode106

codex100

claude-code99

gemini-cli91

github-copilot89

amp83

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

159,700 周安装

Close epic : bd close {EPIC_ID} after all children merged