beads-implement

Beads 实施

使用此技能，可通过 bead 或 epic ID 执行工作，尽量减少来回沟通。此技能必须同时支持经典 Beads（bd）和 beads_rust（br）。

工作流

1. 先确定跟踪器

   • 如果用户明确指定了 bd、br、beads 或 beads_rust，请遵照执行。
   • 否则，检测实际安装的工具：
     • 如果只安装了 br，使用 br。
     • 如果只安装了 bd，使用 bd。
     • 如果两者都已安装，优先使用当前工作区／历史记录已采用的跟踪器。
     • 如果两者都已安装，且无法确定工作区使用哪个跟踪器，请提出一个有针对性的问题，不要猜测。
   • 同一轮运行中不要混用两个跟踪器的命令。

2. 初始化所选跟踪器

   • 对于 bd：
     • 首先运行 bd prime。它仍然是获取当前“如何开始处理此 bead”指引的最快方式。
     • 如果无法使用 bd prime，或其内容不清楚，请先查找已加载的本地经典 Beads 技能，并优先使用。
     • 如果不存在本地 bd 技能，请使用本地 CLI 帮助，例如 bd --help、bd show --help 和 bd update --help。
   • 对于 br：
     • 如果存在已加载的本地 br、beads_rust 或同类跟踪器技能，请先查找并使用。
     • 如果不存在本地 br 技能，请使用本地 CLI 帮助，例如 br --help、br show --help、br update --help 和 br epic --help。
     • 设置 ACTOR="${BR_ACTOR:-assistant}"。
     • 使用 br show <id> --json、br ready --json 和 br blocked --json 了解情况，不要期待存在 prime 命令。
     • 只要可用，面向 Agent 的 br 命令都必须使用 --json。
     • 绝不要直接运行 bv。
   • 不要在此技能中引导用户访问公开的网络文档。

3. 打开 bead

   • 对于 bd，尽可能使用 bd show <id> --json，并阅读标题、描述、验收标准和依赖项。
   • 对于 br，使用 br show <id> --json，并阅读标题、描述、验收标准、设计、备注和依赖项。
   • 如果缺少必要信息，或依赖项阻碍了工作，请提出一个有针对性的问题并等待回复。

4. 在跟踪器中开始工作

   • 对于 bd，如果工作流支持，请将 bead 标记为 in_progress（查看 bd prime／bd update --help）。
   • 对于 br，使用 br update --actor "$ACTOR" <id> --claim --json 认领，或设置 --status in_progress。
   • 如果 bead 的含义不明确，请简要备注你打算采取的方案。

5. 创建简短的待办清单

   • 开始执行时，创建一份简短的待办清单，列出计划完成的任务／子任务，并随着进展更新清单。

6. 确定范围

   • 如果 bead 是单项任务，直接实施。
   • 如果 bead 是 epic，识别所有子任务，并按依赖顺序实施。
   • 对于 epic，一次只将一个子 bead 设为当前实施目标，除非用户明确要求并行实施。
   • 对于 br epic，在有助于了解子任务进度和关闭条件是否满足时，使用 br epic status <id> 或依赖关系图。

7. 有针对性地委派（谨慎使用子 Agent）

   • 仅针对当前 bead 中范围明确的部分使用子 Agent。
   • 适合交给子 Agent 的任务：探索代码仓库、查找 API／库文档、创建复现用例、制定测试策略，以及文件清单明确的小范围重构。
   • 明确指定每个子 Agent 的负责范围（文件和预期产出），并尽可能缩小其写入范围。
   • 如果目标是 epic，主 Agent 负责安排执行顺序。除非明确指派，否则子 Agent 可以处理当前子 bead，但不得开始后续子 bead。
   • 子 Agent 不得关闭 bead 或 epic、更新整体计划，或自行推进工作流。
   • 子 Agent 不得假定其更改已集成；它们应返回结果，供主 Agent 审核、合并并决定接受或拒绝。

8. 推进前的评审门禁

   • 对每个 bead 或子 bead，按顺序执行以下循环：
     1. 实现
     2. 评审
     3. 修复评审发现的问题
     4. 运行相关检查/测试
     5. 提交
     6. 更新 Beads
   • 当前子 bead 通过此门禁前，不要开始下一个子 bead。
   • 如果子 Agent 超出范围，请先停止并核实改动，再使用其任何输出。

9. 实现、提交并记录说明（每项任务/子任务重复执行）

   • 完成实现并运行相关检查/测试，通过评审门禁后再提交。
   • 每项任务/子任务提交一次。
   • 提交说明：在主题中包含 bead id。
   • 提交正文：记录实际说明（改动内容、原因、运行的测试、后续事项/风险）。
   • 提交后，将相同说明添加到 bead 中，确保跟踪器在压缩上下文和后续交接后仍保留这些信息。
   • 对于 bd，使用 bd prime 或已加载的本地 Beads 技能推荐的备注/设计工作流。
   • 对于 br，使用 br update --actor "$ACTOR" <id> --notes "..." --json 写回摘要；如果单独记录进展更合适，则使用 br comments add。
   • 对于 br，请记住同步是显式操作。提交跟踪器状态变更到 git 前，运行 br sync --flush-only。

   最简提交模板：

   <BEAD-ID>: <imperative summary>
   
   Why:
   - ...
   
   What:
   - ...
   
   Tests:
   - ...
   
   Notes/Risks:
   - ...
   

10. 权限规则

• 只有主 Agent 可以将 bead 或 epic 标记为完成。
• 只有主 Agent 可以决定当前子 bead 已完成并继续处理下一个子 bead。
• 只有主 Agent 可以将提交合并到共享分支。
• 子 Agent 是执行者和评审者，不是项目经理。

11. 仅在必要时沟通

• 工作进行期间不要打断用户。
• 只有在受阻、缺少信息或需要做出重要决策时，才暂停并请求帮助。

12. 收尾

• 完成后，给 bead 添加明确的关闭原因。
• 对于 bd，按照 bd prime 或已加载的本地 Beads 技能针对当前安装版本推荐的会话结束同步步骤执行。
• 对于 br：
  • 使用 br close --actor "$ACTOR" <id> --reason "Implemented X in commit abc123" --json 关闭。
  • 如果要关闭 epic，请先通过 br epic status <id> 或 br epic close-eligible <id> 检查是否满足条件。
  • 关闭更新后运行 br sync --flush-only，确保 .beads/ 在 git 提交/推送前是最新的。

13. 报告进度

• 说明使用了哪个跟踪器：bd 或 br。
• 简要总结已完成的任务、已创建的提交，以及剩余事项（如有）。