bmad-handoff

BMAD 移交

用途： 扫描规划输出文件夹，查找所有状态为 ready-for-dev 的故事，将其汇总到单个 handoff-manifest.json 中，并将文件放在任何下游开发工具都能读取的位置——不与任何特定运行器耦合。

这是规划插件生成的最后一个构件。接下来发生的事情由外部开发工具负责，而非此技能。

运行时机

在故事编写阶段完成，并且你（或用户）已确认至少有一个故事的状态为 ready-for-dev 后，运行此技能。清单是某个时间点的快照；重新运行此技能即可刷新。

工作流

使用 TodoWrite 跟踪这些步骤的进度。

1. 定位输出文件夹

查找 bmad-output/project-context.md（默认输出文件夹），或询问用户输出文件夹的位置。默认值：bmad-output/。

2. 查找故事文件

在输出文件夹下对 **/{epic}.{story}.*.story.md 进行 glob 匹配。 如果没有匹配结果，则接受其他扁平布局（stories/*.story.md）。

3. 筛选 ready-for-dev 状态

读取每个故事文件的 **Status:** 标头字段（位于故事标头块中，而非 ## Status 标题）。仅包含状态值严格等于 ready-for-dev 的故事。

如果没有找到此类故事，则报告发现的状态并停止——不要生成空清单。

4. 提取每个故事的字段

对于每个符合条件的故事文件，提取：

字段	故事文件中的来源
id	文件名主体或 ## Story 标题中的 ID
storyFilePath	相对于项目根目录的路径
status	**Status:** 标头字段值
epic	文件名的第一段，例如 2.1.stripe.story.md 中的 "2"
storyNumber	第二段，例如 "1"
title	第一个 H1 标题或 ## Story 标题文本
ownedScope	## Owned File/Module Scope — 原样列出每个路径
wave	## Dependency Maps → wave/parallel_set 注释（整数或 null）
parallelSet	同一章节中的 parallel set 标签（若存在，则为字符串；否则为 null）
dependencies	## Dependency Maps → 被阻塞的故事 ID（数组，可以为空）
acceptanceCriteriaSummary	## Acceptance Criteria 中前 3 项验收标准，每项 ≤120 个字符
lockedSectionsNote	静态字符串 — 参见 schema
devAgentRecord	静态 null — 留给开发工具填充的占位符

5. 计算 wave 顺序

如果故事尚未包含明确的 wave 注释：

• dependencies 数组为空的故事属于 wave 1。
• 当某个故事的每项依赖都位于 wave N 或更早时，该故事属于 wave N+1。
• 添加计算得出的 wave 值；未标注时，parallelSet 保持为 null。

6. 写入清单

写入 {outputFolder}/handoff-manifest.json。

使用 ${CLAUDE_PLUGIN_ROOT}/skills/bmad-handoff/templates/handoff-manifest.schema.json 中的 schema 作为结构约定。将 schemaVersion: "1.0" 填入清单。

故事按 wave 升序排序，同一 wave 内按 id 升序排序。

7. 向用户报告

打印简洁摘要：

Handoff manifest written → bmad-output/handoff-manifest.json
  schemaVersion : 1.0
  stories       : <N> ready-for-dev
  waves         : <W>  (wave 1 has <X> stories, can start immediately)
  output path   : bmad-output/handoff-manifest.json

如果有故事缺少必需章节（例如没有 ## Owned File/Module Scope），请将其列为警告——不要悄悄省略或编造数据。

清单字段定义（快速参考）

完整的架构说明和适配器说明请参阅 REFERENCE.md。

字段	类型	必填	说明
schemaVersion	string	是	Semver 字符串；当前值 = "1.0"
generatedAt	string	是	ISO-8601 UTC 时间戳
projectName	string	是	来自 project-context.md 或用户输入
outputFolder	string	是	用于查找 story 的相对路径
stories	array	是	每个已准备好进行开发的 story 对应一个对象
stories[].id	string	是	唯一的 story 标识符
stories[].storyFilePath	string	是	.story.md 文件的相对路径
stories[].status	string	是	此清单中始终为 "ready-for-dev"
stories[].epic	string	是	Epic 标识符
stories[].storyNumber	string	是	Epic 内的 story 编号
stories[].title	string	是	易于阅读的 story 标题
stories[].ownedScope	array	是	此 story 可修改的文件／模块路径
stories[].wave	integer	是	执行波次（1 = 无依赖项）
stories[].parallelSet	string|null	否	明确分组时使用的标签
stories[].dependencies	array	是	必须先完成的 story ID
stories[].acceptanceCriteriaSummary	array	是	前 3 项 AC 条目，每项 ≤120 个字符
stories[].lockedSectionsNote	string	是	给开发工具的指示
stories[].devAgentRecord	null	是	由开发工具填充；生成时始终为 null

lockedSectionsNote 始终为以下字符串：

"Sections Acceptance Criteria, Dev Notes, and Testing are LOCKED. External dev tools must not edit them. Populate only the Dev Agent Record section."

子 Agent 策略

对于较小的待办列表（≤15 个 story），此技能以单线程运行——提取循环速度很快，且上下文可容纳在单次会话中。

对于较大的待办列表（16 个或更多 story），并行分派 story 提取任务：

Agent	任务
Agent 1…N	读取分配范围内的 story 文件；提取字段；返回 JSON 片段
Coordinator	合并片段；计算波次顺序；写入清单

每个 Agent 会收到其负责范围内的文件路径列表，以及上方的字段提取表。它会返回一个 story 对象的 JSON 数组（暂不包含 wave 字段）。 Coordinator 会合并、计算波次、排序并写入清单。

关键指南

1. 切勿编造字段值——如果 story 文件中缺少某个字段，输出 null 并在摘要中添加警告。
2. 不要修改 story 文件——此技能对 story 内容仅执行只读操作。
3. ownedScope 对并行冲突安全至关重要；切勿合并或概述其中的内容。
4. 此清单是一个稳定的版本化接口。添加或删除字段前，先递增 schemaVersion（作为单独的架构修订，而非在本次运行中修改）。
5. 不要根据 ready-for-dev 状态以外的任何条件筛除 story——依赖项解析是开发工具的职责。
6. 如果用户要求“重新运行”或“刷新”清单，请覆盖现有文件。

---

---

属于 BMAD Planning & Orchestrator 插件——由 BMAD Code Organization 为 BMAD Method 提供的 Claude Code harness（https://github.com/bmad-code-org/BMAD-METHOD）。体现了 bmad-handoff 的理念。所有方法论相关致谢均归 BMAD Code Organization 所有。