名称: beads-orchestration 描述: 使用BEADS任务跟踪进行GitHub问题的多智能体协同 自动激活: true 触发器:
- “处理问题”
- “开始问题”
- “@beads”
- “代理就绪标签”
BEADS 多智能体协同技能
这个技能协调一群专业AI代理来自主处理GitHub问题，从创建到合并PR。
快速开始
开始处理GitHub问题
# 用户通过以下任一方式触发:
@beads start #123
bd start 123
/project:beads-start 123
检查BEADS状态
bd ready # 显示可处理的任务
bd list # 显示所有任务
bd stats # 显示项目统计
bd doctor # 检查系统健康
代理列表
| 代理 | 角色 | 触发时机 |
|---|---|---|
| 问题协调器 | 每个问题的主协调器 | 问题收到agent-ready标签时 |
| 研究代理 | 代码库探索 | 协调器创建研究任务时 |
| 架构师代理 | 实施规划 | 研究完成时 |
| 产品经理代理 | 用例和用户效益审查 | 设计审查关卡（并行） |
| 设计师代理 | UX/API设计审查 | 设计审查关卡（并行） |
| 安全设计代理 | 安全威胁建模 | 设计审查关卡（并行） |
| CTO代理 | TDD准备和计划审查 | 设计审查关卡（并行） |
| 编码代理 | TDD实施 | 设计审查关卡批准时 |
| 代码审查代理 | 内部代码审查 | 实施完成时 |
| 安全审计代理 | 安全审查（代码） | 实施完成时 |
| PR守护者 | PR生命周期管理 | PR创建时 |
详见agents/目录中的详细代理定义。
设计审查关卡（新）
对于通过头脑风暴创建的复杂功能，自动的设计审查关卡确保在实施前质量：
设计文档创建
│
▼
┌─────────────────────────────────────────────────┐
│ 设计审查关卡 │
│ │
│ 并行生成： │
│ • 架构师代理（技术架构） │
│ • 设计师代理（UX/API设计） │
│ • CTO代理（TDD准备） │
│ │
│ 所有三个必须批准才能继续 │
└─────────────────────────────────────────────────┘
│
├── 任何需要修改？ → 迭代设计（最多3次）
│
全部批准
│
▼
创建BEADS史诗 → 开始实施
触发设计审查关卡
关卡在以下情况下自动触发：
superpowers:brainstorming完成并提交设计文档时- 用户运行
/project:review-design <path-to-design.md>时
代理审查标准
| 代理 | 关注领域 |
|---|---|
| 产品经理 | 用例清晰度、用户效益、范围、成功指标 |
| 架构师 | 服务架构、依赖、模式、集成 |
| 设计师 | API设计、UX流程、开发者体验、一致性 |
| 安全设计 | 威胁建模、认证授权、数据保护、OWASP Top 10 |
| CTO | TDD准备、代码库对齐、完整性、风险 |
迭代协议
- 最多3次迭代，然后人工升级
- 每次迭代：修订设计 → 重新运行所有审查者
- 升级选项：覆盖 / 延迟 / 取消
详见goodtogo:design-review-gate技能获取完整详情。
工作流概述
GitHub问题 #123（代理就绪标签）
│
▼
┌─────────────────────────────────────┐
│ 问题协调器 │
│ 创建BEADS史诗，委托工作 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 研究阶段 │
│ 研究代理探索代码库 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 规划阶段 │
│ 架构师代理创建计划 │
└─────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 设计审查关卡（并行） │
│ │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────┐ │
│ │ 产品 │ │ 架构师 │ │ 设计师 │ │ 安全设计│ │ CTO │ │
│ │（用户） │ │ （技术）│ │ （UX/API）│ │ （威胁）│ │（TDD）│ │
│ └─────────┘ └──────────┘ └──────────┘ └──────────┘ └───────┘ │
│ │
│ 所有五个必须批准（最多3次迭代） │
└───────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 实施阶段 │
│ 编码代理使用TDD实施 │
└─────────────────────────────────────┘
│
├──────────────────────────────┐
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ 代码审查 │ │ 安全审计 │
│ 代理 │ │ 代理 │
└───────────────────┘ └───────────────────┘
│ │
└──────────────┬───────────────┘
▼
┌─────────────────────────────────────┐
│ PR创建（自动守护） │
│ bin/create-pr-with-shepherd.sh │
│ → 自动调用pr-shepherd技能 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ PR守护者（自动） │
│ 监控CI，处理审查，自动解决线程 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 人工批准和合并 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 关闭史诗并提取学习 │
└─────────────────────────────────────┘
自动PR审查周期
当PR通过bin/create-pr-with-shepherd.sh创建时，脚本输出开始监控的指令：
- 创建PR，具有适当的标题和正文
- 启动pr-shepherd，使用
/project:pr-shepherd <pr-number> - PR守护者监控：CI状态、审查评论、线程解决
- 自动修复：代码中的lint、类型错误、测试失败
- 准备就绪时报告：所有CI通过，所有线程解决
对于手动创建的PR，调用/project:pr-shepherd <pr-number>启动监控周期。
BEADS命令参考
问题管理
# 为GitHub问题创建史诗
bd create "功能：用户认证" --type epic --issue 123
# 在史诗下创建任务
bd create "研究认证模式" --type task --parent bd-abc123
# 添加依赖
bd dep add <被阻塞任务> <阻塞任务>
# 更新状态
bd update <任务ID> --status open|in_progress|blocked|closed
# 关闭并说明原因
bd close <任务ID> --reason "成功完成"
任务发现
# 显示就绪（未被阻塞）的任务
bd ready --json
# 列出史诗下的所有任务
bd list --parent <史诗ID>
# 显示被阻塞的任务
bd blocked
# 显示任务详情
bd show <任务ID> --json
自定义状态标签
# 等待人工输入
bd label add <任务ID> waiting:human
# 等待CI
bd label add <任务ID> waiting:ci
# 代理失败，需要干预
bd label add <任务ID> agent:failed
# 审查迭代跟踪
bd label add <任务ID> review:iteration-1
同步操作
# 检查同步状态
bd sync --status
# 从主分支拉取更新
bd sync --from-main
# 导出到JSONL
bd export
开始处理问题
步骤1：验证问题就绪
# 检查问题是否有代理就绪标签
gh issue view 123 --json labels | jq '.labels[].name' | grep agent-ready
步骤2：创建BEADS史诗
# 获取问题详情
ISSUE=$(gh issue view 123 --json title,body,number)
# 创建链接到问题的史诗
bd create "$(echo $ISSUE | jq -r .title)" --type epic --issue 123 --json
步骤3：发布确认
gh issue comment 123 --body "🤖 代理认领此问题。BEADS史诗已创建。"
步骤4：生成问题协调器
使用任务工具生成问题协调器代理：
Task({
subagent_type: "general-purpose",
description: "问题协调器 for #123",
prompt: `您是问题协调器代理。
阅读代理定义：
.claude/plugins/goodtogo/skills/beads/agents/issue-orchestrator.md
您的任务：
- 史诗ID：<epic-id>
- GitHub问题：#123
- 开始协调工作流
严格按照指定的工作流阶段执行。`,
});
人工升级协议
何时升级
- 需求模糊：问题不清晰
- 冲突约束：无法满足所有需求
- 风险决策：安全或数据问题
- 阻塞超过1小时：需要外部依赖
- 3次失败迭代：代理无法解决问题
如何升级
# 标记任务为等待
bd update <任务ID> --status blocked
bd label add <任务ID> waiting:human
# 发布到GitHub问题
gh issue comment <number> --body "$(cat <<'EOF'
## 🤖 代理请求：<类型>
**任务**：<任务ID>
**问题**：<清晰问题>
### 选项
1. **选项A**：<描述>
2. **选项B**：<描述>
### 代理推荐
<推荐>
---
回复：`@beads approve <任务ID>` 或 `@beads respond <任务ID> <选项>`
EOF
)"
人工响应模式
# 批准被阻塞的任务
@beads approve bd-abc123
# 响应选择
@beads respond bd-abc123 "使用选项A"
# 请求修改
@beads request-changes bd-abc123 "需要更多错误处理"
# 推迟处理
@beads defer bd-abc123 "周一日站会讨论"
代理生成模式
顺序生成
// 首先生成研究代理
const researchResult = await Task({
subagent_type: "general-purpose",
description: "问题 #123 的研究",
prompt: researcherPrompt,
});
// 然后使用研究输出生成架构师
const planResult = await Task({
subagent_type: "general-purpose",
description: "问题 #123 的规划",
prompt: architectPrompt + researchResult,
});
并行生成
// 并行生成代码审查和安全审计
const [reviewResult, securityResult] = await Promise.all([
Task({
subagent_type: "general-purpose",
description: "问题 #123 的代码审查",
prompt: codeReviewPrompt,
}),
Task({
subagent_type: "general-purpose",
description: "问题 #123 的安全审计",
prompt: securityAuditPrompt,
}),
]);
知识集成
关键：开始工作前准备
所有代理在开始任何工作前必须准备其上下文。 这可以防止错误假设并确保与既定模式对齐。
# 通用准备（加载关键规则和注意事项）
npx tsx scripts/beads-prime.ts
# 为特定修改文件准备
npx tsx scripts/beads-prime.ts --files "src/lib/services/*.ts" "src/app/api/*.ts"
# 为特定主题准备
npx tsx scripts/beads-prime.ts --keywords "认证" "jwt"
# 为工作类型准备
npx tsx scripts/beads-prime.ts --work-type planning # 规划前
npx tsx scripts/beads-prime.ts --work-type implementation # 编码前
npx tsx scripts/beads-prime.ts --work-type review # 审查前
npx tsx scripts/beads-prime.ts --work-type research # 研究前
# 组合（最全面）
npx tsx scripts/beads-prime.ts --files "<文件>" --keywords "<主题>" --work-type <类型>
准备命令输出相关事实，分类为：
- 必须遵循：关键规则（从不/总是/必须语句）
- 注意事项：常见陷阱
- 模式：此代码库的最佳实践
- 决策：架构选择
完成工作后
运行自反思以提取学习：
# 获取最近的PR评论
GITHUB_TOKEN=$(gh auth token) npx tsx scripts/beads-fetch-pr-comments.ts --days 7
# 使用自反思技能评估并添加学习
/project:self-reflect
或生成知识管理代理：
Task({
subagent_type: "general-purpose",
description: "从史诗中提取学习",
prompt: `审查完成的史诗<epic-id>并提取学习。
首先：运行\`npx tsx scripts/beads-prime.ts --work-type review\`以加载上下文。
然后分析：
- 使用了哪些模式？
- 发现了哪些注意事项？
- 未来代理应该知道什么？
使用知识捕获服务存储学习。`,
});
成功标准检查列表
关闭史诗前，验证所有：
- [ ] 史诗下的所有BEADS任务已关闭
- [ ] PR已创建并链接到GitHub问题
- [ ]
gtg返回就绪状态（确定性PR就绪门）gtg "$PR_NUMBER" --repo "$OWNER/$REPO" --format json > /tmp/gtg.json STATUS=$(jq -r '.status' /tmp/gtg.json) # 必须返回就绪状态才能继续 - [ ] 人工已批准合并
- [ ] PR已合并到主分支
- [ ] GitHub问题已关闭
- [ ] 学习已提取到知识库
gtg作为确定性门
gtg命令替代手动验证：
- 所有CI检查通过
- 所有PR评论已处理
- 所有PR线程已解决
PR在gtg返回就绪状态前未就绪。
# 确定性检查PR就绪（推荐：解析JSON状态）
gtg 123 --repo owner/repo --format json > /tmp/gtg.json
STATUS=$(jq -r '.status' /tmp/gtg.json)
echo "状态：$STATUS" # 必须为就绪
# 替代：使用语义退出码进行shell脚本
gtg 123 --repo owner/repo -q # 退出码 0 = 就绪
# 查看阻止详情：
gtg 123 --repo owner/repo --format json | jq '.action_items'
故障排除
任务卡在进度中
# 检查任务状态
bd show <任务ID> --json
# 检查孤立代理
# 如果代理失败，重置并重试
bd update <任务ID> --status open
bd label remove <任务ID> agent:failed
循环依赖
# 运行doctor检测
bd doctor
# 如果找到，重构依赖
bd dep remove <任务1> <任务2>
BEADS同步问题
# 检查同步状态
bd sync --status
# 强制导出
bd export
# 从主分支拉取
bd sync --from-main
目录结构
.claude/plugins/goodtogo/skills/beads/
├── SKILL.md # 此文件
└── agents/
├── issue-orchestrator.md # 主协调器
├── researcher-agent.md # 代码库探索
├── architect-agent.md # 实施规划
├── product-manager-agent.md # 用例和用户效益审查（新）
├── designer-agent.md # UX/API设计审查（新）
├── security-design-agent.md # 安全威胁建模（新）
├── cto-agent.md # TDD准备审查
├── coder-agent.md # TDD实施
├── code-review-agent.md # 内部代码审查
├── security-auditor-agent.md # 安全审查（实施）
└── pr-shepherd-agent.md # PR生命周期管理
.claude/plugins/goodtogo/skills/design-review-gate/
└── SKILL.md # 设计审查关卡协调器（新）
.claude/plugins/goodtogo/skills/brainstorming-extension/
└── SKILL.md # 链接头脑风暴到审查关卡（新）
.claude/commands/
└── review-design.md # /project:review-design命令（新）
.claude/rubrics/
├── plan-review-rubric.md # 由CTO代理使用
└── code-review-rubric.md # 由代码审查代理使用
.beads/
├── beads.db # SQLite数据库
├── issues.jsonl # 问题/任务数据
└── knowledge/ # 策划的学习
├── codebase-facts.jsonl
├── patterns.jsonl
└── anti-patterns.jsonl