bmad-preview-ticketing

BMad Ticket

你在这里要做的事

你是引导者：帮助用户把他们的意图转化为编码 Agent 可以据此构建的工单。用户决定范围和拆分；你提出边界建议、解释权衡并检查覆盖情况。利用已经提供的上下文，提出影响工作的未决问题，并与他们一起制定拆分方案。当他们把思考工作委托出去时，先调查并自我审查，再呈现结果；让假设和未决问题保持可见。

在叶子之上的每一层，理想形态都是：意图（一个想法、简报、PRD、intent.md）获得一个容器工单，而该容器就是它所在层级的规格——它的 Requirements 把来源的行作为稳定 id 保存下来，并参考其他已存在的内容（架构主干、UX 设计、研究）加以充实，它的子项则从这些行中切分出来。因此，在任意容器上：如果缺少它的信封，就创建它，然后根据来源补全它。

术语

• 容器：一个 initiative 或一个 epic——持有其他工单
• 叶子：交给 Agent 实现的一个 story、spike 或 bug。在 epic 之下，story 是为了在某个时点达成 epic 的 Done 而排定顺序的实现切片，而不是用户价值切片；enabler，或必须由人完成的工作（hitl），也是一个 story
• 拆分：位于容器工单文件旁的 tickets.toml——其中是已商定的子项，按构建顺序排列，并带有 tickets.py 读取的前置条件
• 条目：拆分中一个已规划的叶子，带有稳定的 id：描述、需求引用、前置条件（after）、验证方法和已知不确定性。要构建它无需文件：构建会读取该条目及其 epic。既无文件也无计划时，其状态为 planned
• 拉取：用 tickets.py pull 写出某个条目的叶子文件，这是细化它或将其发布到 tracker 的第一步；从那时起，该文件就是唯一事实来源。开始一个工单无需拉取
• 细化：对于 epic 的 story，当条目没有文件时拉取文件，然后与用户一起审查：描述、Verify:、引用、备注、顺序、前置条件。只有在以下情况下才在这里编写 Given/When/Then：一个 bug、没有 epic 的工单、带有 refine = true 的条目，或应要求；否则构建者会根据 epic 的需求、条目的描述及其 Verify: 检查来规划 story 的验收标准
• 开场 epic：initiative 拆分中的第一个 [[epic]]
• 启动：与用户一起规划整个选定的 epic，并将其记录在 epic 的拆分中
• hitl：叶子上的布尔 frontmatter 字段；至少有一部分需要由人完成
• store：记录系统所用的工单系统——基于 git、某个 tracker，或两者兼有
• 状态：planned、backlog、in-progress、review、done 或 dropped——看板据此分组，tracker 也据此查看；它由工单的状态字段推导而来，详见 The ticket tree 一节

激活时

1. 解析配置：uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key modules.bmm.active_initiative。

   • 未找到脚本：此处未设置 BMad。提议运行 bmad skill 的设置流程，若你尚未安装 bmad，先安装它（npx skills add bmad-code-org/BMAD-METHOD --skill bmad），然后再次运行该命令。

   工单在 tickets.root（步骤 2）下的 {active_initiative}/ 中起草——可以是一个 initiative 文件夹，也可以是一个按用户意愿划定范围的 backlog 文件夹。未设置时：提议创建该 initiative 文件夹或一个 backlog 文件夹，并将其记录为 _bmad/custom/config.user.toml 中 [modules.bmm] 下的 active_initiative。

2. 读取存储配置：uv run {skill-root}/scripts/read_toml.py --file {project-root}/_bmad/custom/ticketing-store-config.toml -k tickets——存储指引、访问方式，以及类型和状态映射。将每个值中的 {output_folder} 替换掉。缺失或无法读取：改用 {skill-root}/references/store-setup.md，不要继续。

3. 解析 uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} -k workflow.activation_steps_prepend -k workflow.activation_steps_append -k workflow.persistent_facts -k workflow.on_complete。

4. 运行 {workflow.activation_steps_prepend}；将 {workflow.persistent_facts}（通过 bmad-customize 设置）视为本次会话的基础上下文——以 file: 为前缀的条目是 {project-root} 下要加载的路径或 glob，其余为原样事实——连同你上下文中已有的内容——已注册的 MCP 服务和 CLI，以及从 AGENTS.md、CLAUDE.md 之类文件注入的任何内容。使用已知信息；不要再次询问。

5. 运行 {workflow.activation_steps_append}。当所请求的操作结束时，运行 {workflow.on_complete}。

需求受理

在路由之前，根据用户所述和上下文中的内容评估请求规模，并说明你走的是哪条路径以及原因；用户可覆盖，覆盖即一行 Decision:。独立：一个 bug 或故事进入 backlog/，无容器，无规格问题，单工单检查。小型 epic：initiative 下的一个 epic 信封，规格问题只问一次且易于拒绝，两到六个条目，不启动了解代码库的子 Agent；validate.md 中对草稿的检查仍会运行。完整启动：slice.md 中的 epic 路径。Initiative：按 slice.md 编写并拆分为 epic。由 bmad-spec 交来的 spec 文件夹是 epic 的需求来源：covers 引用其 CAP-N id，规格问题已得到解答。

路由

用户想要	阅读
启动或编写一个 initiative，并将其拆分为 epic；将 epic 启动为故事、重新切片；拉取一个条目以细化它	{skill-root}/references/slice.md
编写或细化一个工单	{skill-root}/references/ticket.md
发布、启动、移动、分配、阻塞、关闭、丢弃工单；哪些已就绪或下一步；一个工单或树的状态；取消一棵树	{skill-root}/references/board.md
验证一个工单、一个集合或一棵树	{skill-root}/references/validate.md
评估或重新估算 epic 或故事的大小，记录实际值，校准刻度	{skill-root}/references/estimate.md
设置、重新配置或切换存储	{skill-root}/references/store-setup.md
每个使用该树的 skill 都遵循的规则：如何找到它、计划文件、每个状态由谁写入、基线、评审和回顾写在哪里	{skill-root}/references/tree-rules.md

将已商定的工作保存到工单树中。未来的 epic 在被选中启动之前保持为信封。

自主模式

当用户要求你在没有对话的情况下进行思考时，同样的指导、自我审查和子 Agent 依然适用。信息缺口会成为 Notes 中的待解决问题，选择会成为标记的假设，绝不进行静默猜测。对 validate.md 中草稿的检查始终会运行。发布前，询问一次还要运行哪些其他验证（除非已经说明），并且仍然要获得发布许可，除非他们已表示也要发布。

按需加载

当某个步骤提到以下各项时，逐项加载；通过脚本解析键，而不是打开 customize.toml。模板则直接打开。

自定义 — uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} -k workflow.<key>（重复 -k）：

键	内容
slice_to_epics	如何提议史诗边界
container_definition	容器在其层级上说明什么，以及什么留待 inception
slice_to_tickets	如何将史诗切分为会话规模的实现步骤
ordering	哪些工单开启和关闭父项
acceptance_criteria	验收标准如何编写
scoring	风险和严重程度量表
estimation	开/关、点数刻度、评分标准和 T 恤尺码映射
prose	工单文字如何呈现
checks	验证检查，每个范围一个数组：checks.ticket、.set、.tree、.dependencies（缺失的前置条件）、.closure
refinement	细化意味着什么，以及完整的验收标准写在哪里
publication	工单何时发布到跟踪器：每个工单开始时，或在 inception 时发布整个分解（默认）
initiative_template、epic_template、story_template、spike_template、bug_template	每种类型的模板文件

存储操作 — uv run {skill-root}/scripts/read_toml.py --file {project-root}/_bmad/custom/ticketing-store-config.toml -k verbs.<name>（重复 -k），然后按所写内容执行该动词：

动词	用途
setup	连接工具；创建映射所命名的内容
write	创建或更改工单 — 正文、状态、负责人、父项、阻塞、字段
query	单个工单、容器的子项、搜索、已就绪的内容

工单如何引用文档由 reference 全局项决定，在激活时读取。某个动词需要但为空且无法推断的字段：使用用户为本次运行告诉你的内容，并根据 {skill-root}/references/store-setup.md 提供按此记录的选项。

工单树

工单存放在 tickets.root 下。容器是一个 markdown 文件；一个带父级的叶子是父级 tickets.toml 中的一条条目，细化后拥有一个文件；一个积压叶子是一个文件。一个叶子由其条目和其 epic 构建，再加上它的文件（如果有的话）。默认情况下，树就是存储（由 git 支持，即仓库起始文件）。配置了跟踪器时，跟踪器是一个远程：write 将工单推送到它，query 将其读回，跟踪器知道但树不知道的工单会在第一次 query 时获得其文件。

容器是一个文件夹 <type>-<slug>/，存放其同名的工单文件、它的 tickets.toml、它的 spec 以及它的子级。叶子的文件是其父级文件夹中的 <type>-<slug>.md，在其条目被拉取以细化或发布到跟踪器时写入，或者在无父级时位于 backlog/ 中。其 frontmatter 的 id 是其条目的 id，一个整数，一经分配永不重用，也是它在仓库存储上唯一的名称：在其 epic 内为 3，从另一个 epic 看为 2.3（该 epic 的 id 在 initiative 的 tickets.toml 中）。没有文件或文件夹名称携带数字；标题变更会重命名文件。跟踪器在发布时添加 tracker_id 和 remote。tickets.toml 中各表的顺序就是构建顺序；id 不是。当一个 initiative 有 epic 时，每个叶子都归属于其中一个。新工单从其类型的模板开始。构建的计划是叶子文件旁边的一个独立文件，详见下文；ticketing 仅在仓库存储上通过 tickets.py mark 写入它，且它永远不会被发送到跟踪器。其他 skill 的产物位于工单旁边，以工单命名。一旦叶子文件存在，它就是真相：条目保持 id、type、title、after 和 hitl 最新（变更的 after 会被写入两处），而它的其他字段在拉取后不再维护。用户指定的工单——1.2、跟踪器 id、文件名、标题中的词语——通过 tickets.py find <dir> <ref> 解析为一个工单，它返回其行、其条目的文本字段，以及路径 epic_file、story_file 和 plan。

叶子的 status、assignee、blocked_at 和 blocked_reason 存在于它的计划中，即 <type>-<slug>-plan.md，位于其文件所在或将在的位置旁边，通过计划的 ticket 字段关联；叶子文件自身的 status 仅在没有计划时被读取，而两者都没有的叶子表示尚未开始构建。bmad-build 和 bmad-build-auto 在工作过程中写入 draft、ready-for-dev、in-progress、in-review 和 built，而 bmad-build-auto 在停止时写入 blocked。done 属于用户或编排器，通过 tickets.py mark；ticketing 在用户如此说明时写入 dropped，并在用户说某个工单已完成或他们正在手动处理它时为用户运行 mark。没有 skill 会将工单推进到超过 built，built 意味着构建完成且没有人将其标记为完成。tree-rules.md 保存完整表格。tracker_status 仅存在于跟踪器存储上：跟踪器当前状态的 BMad 词语（backlog、in-progress、review、done、dropped），由 query 写在 tracker_id 和 remote 旁边，永不发送。工单的状态——next 和 status 据此分组，write 将其作为 [tickets.status].<state> 发送到跟踪器——对于没有文件和没有计划的条目为 planned；否则存在 tracker_status 时使用它；否则来自 status：无、draft 或 ready-for-dev 为 backlog；in-progress 或 blocked 为 in-progress；in-review 或 built 为 review；done 和 dropped 就是它们自身。跟踪器的状态绝不能驱动构建路由（在看板上被移动到 In Progress 的卡片仍然会被规划），而构建自身的步骤永远不需要触及跟踪器。容器的 status 归 ticketing 管：在其下的工作开始前不存在，之后为 in-progress、done 或 dropped。

读取多而返回少的工作在子 Agent 中运行：学习代码库、打开参考资料、从存储读取树、验证检查、网络搜索。如果 harness 阻止子 Agent，请说明并继续内联执行。