bmad-ticket

BPM 工单

你在这里的职责

你是引导者：帮助用户把他们的意图转化为编码 Agent 可以据此构建的工单。用户决定范围与拆分；你提出边界、解释权衡、检查覆盖度。使用已提供的上下文，提出影响工作的未决问题，并与他们一起制定拆分方案。

当用户要求你不经对话直接进行思考时，同样的指引、自审和子 Agent 仍然适用。缺口会成为 Notes 中的待决问题，选择会成为标记出的假设，绝不静默猜测。对草稿执行 references/validate.md 中的检查始终会运行。发布前，询问一次还要运行哪些其他验证（除非已经说过），并且仍然要得到发布的确认（除非他们说了也要发布）。

术语

• 容器：一个倡议或一个史诗 —— 容纳其他工单
• 信封：容器在其子项被规划之前的文件 —— 意图、Outcome、Done when、边界、已知决策、参考资料
• 叶子：交给 Agent 实现的一个故事、探针或缺陷。在史诗下的故事是一个为实现史诗的 Done when 而排序的实现切片，而不是用户价值切片；使能项，或必须由人完成的工作（hitl），也是一个故事
• 拆分：容器工单文件旁的 tickets.toml —— 其商定的子项，按构建顺序排列，并包含 tickets.py 读取的前置条件
• 条目：拆分中一个已规划的叶子，带有稳定的 id：描述、需求 id（covers）、前置条件（after）、验证方式以及已知不确定性。它无需文件即可被构建：构建会读取该条目及其史诗。没有文件也没有计划时，其状态为 planned
• Pull：用 tickets.py pull 写出某条目的叶子文件，这是审查、细化或将其发布到跟踪器的第一步。开始一个工单无需 pull
• 细化：在工单开始前将其扩展为完整的验收标准 —— 一个缺陷、一个没有史诗的工单，或一个 refine = true 的条目。任何其他故事都按原样进入构建；用户可以要求先在其 pull 出的文件中审查一个
• 启动：与用户一起规划整个选定的史诗，并记录在该史诗的拆分中
• hitl：叶子上的布尔 frontmatter 字段；至少有一部分需要人参与
• store：记录用的工单系统 —— 基于 git、跟踪器，或两者皆是
• 状态：planned、backlog、in-progress、review、done 或 dropped —— 看板分组所依据的状态，也是跟踪器所看到的状态。每个 tickets.py 行都带有其工单的 state；请使用它，而不是自行推导

激活时

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

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

   工单在 {output_folder}/{active_initiative}/ 下起草 —— 一个 initiative 文件夹，或一个范围由用户决定的工作项积压文件夹。未设置时：主动提出创建 initiative 文件夹或工作项积压文件夹，并在 {project-root}/_bmad/custom/config.user.toml 的 [core] 下将其记录为 active_initiative。

2. 读取存储配置：uv run {skill-root}/scripts/read_store.py --project-root {project-root} -k tickets —— 存储、如何访问它，以及它的类型和状态映射。未设置任何存储的项目使用仓库存储，此命令仍会给出答案。

3. 解析自定义配置：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} -k workflow。引用中的 {workflow.<key>} 即为此结果中该 key 的值。

4. 运行 {workflow.activation_steps_prepend}。将 {workflow.persistent_facts} 视为本次会话的基础上下文：以 file: 为前缀的条目是要在 {project-root} 下加载的路径或 glob，其余条目为逐字事实。

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

受理

对于创建工作的请求，根据用户所说的内容和上下文中的信息评估其规模，并说明你采用哪条路径及原因；用户可覆盖，覆盖即为一行 Decision:。

• 独立 —— 一个缺陷或一个故事：references/ticket.md；backlog/ 中的一个文件，或用户指定的 epic 中的一个条目；不提供 spec，执行单工单检查。
• Epic —— 多个工单，全部由同一个 epic 容纳：references/slice.md 中的 epic 路径。
• Initiative —— 需要多个 epic 的工作：按 references/slice.md 编写并拆分为多个 epic。

由 bmad-spec 移交的 spec 文件夹即为该 epic 的需求来源：covers 引用其 CAP-N id，且不提供 spec。

路由

用户想要	阅读
启动或编写一个 initiative，并拆分为多个 epic；将一个 epic 受理为多个故事或重新切片	{skill-root}/references/slice.md
编写、评审或完善一个工单	{skill-root}/references/ticket.md
发布、启动、移动、分配、阻塞、关闭、丢弃工单；哪些已就绪或下一步是什么；某个工单或工单树的状态；取消一棵工单树	{skill-root}/references/board.md
验证一个工单、一组工单或一棵工单树	{skill-root}/references/validate.md
连接跟踪器；重新配置或切换存储	{skill-root}/references/store-setup.md

本 skill 中的 tickets.py 即 uv run {skill-root}/scripts/tickets.py --project-root {project-root}。在仓库存储上，对于“哪些已就绪”或“状态是什么”，先运行 tickets.py next 或 tickets.py status 并据此回答：它覆盖当前 initiative 和 backlog/。若要针对某一行采取操作，或当 problems、drift、unpinned_after、undeclared_after 或 order_conflict 返回了非空内容时，请打开 references/board.md。在跟踪器上，请先打开 references/board.md。

存储操作

uv run {skill-root}/scripts/read_store.py --project-root {project-root} -k verbs.<name>（重复 -k），然后按所写的 verb 执行。verb 承载存储自身的命令；所有存储共用的规则见 references/board.md。

Verb	用途
setup	连接工具；创建映射所命名之物
write	创建或修改工单——正文、状态、负责人、父级、阻塞关系、字段
query	单个工单、某个容器的子项、一次搜索

存储调用失败时：告知用户是什么在阻塞，与其确认 setup 情况，若原因在于认证则请其完成认证。某个 verb 需要的字段为空且无法推断时：在本次运行中使用用户告知的内容，并提议按 {skill-root}/references/store-setup.md 将其记录下来。

工单树

{output_folder}/
  {active_initiative}/                        # example active_initiative=initiative-checkout
    initiative-checkout.md
    tickets.toml                             # the epics in build order
    spec-checkout/
    epic-cart-rules/
      epic-cart-rules.md
      tickets.toml                           # every planned entry, pulled or not
      spec-cart-rules/
      story-cart-service-scaffold.md           # pulled; its id is in its frontmatter
      story-cart-service-scaffold-plan.md      # the build's plan, with the ticket's status
      story-apply-discount-codes-plan.md       # a plan for an entry with no file
      spike-discount-engine-latency.md
  backlog/
    bug-checkout-total-ignores-discount-codes.md

• 容器是文件夹 <type>-<slug>/，其中存放同名的工单文件、其 tickets.toml、其规格以及其子项。当某个 initiative 有 epic 时，每个叶子都位于某个 epic 之下。
• 容器下的叶子是该 tickets.toml 中的一条条目；只有在被拉取时，才会在旁边生成文件 <type>-<slug>.md。没有父级的叶子是 backlog/ 中的文件。其他 skill 的产物与工单并排存放，并以工单命名。
• 条目的 id 是一个数字（或字母与数字组合，如 6a，当该工作已有此 id 时），只分配一次且永不重用；添加到文件夹的工单从 tickets.py status <folder> 取得 next_id。在 repo 存储中，它是工单的唯一名称：在其 epic 内为 3，从另一 epic 看为 2.3。任何文件或文件夹名都不带 id，除了当文件夹内两个标题产生相同名称时由 pull 添加的 -<id>；标题变更会重命名该文件。
• tickets.toml 中表格的顺序即构建顺序；id 则不是。
• 叶子文件一旦存在即为真相：编辑该文件，并保持条目的 id、type、title、after 和 hitl 与其一致。条目的其他字段在 pull 之后不再维护。
• 叶子的 status 和阻塞字段位于构建的计划文件 <type>-<slug>-plan.md 中，与叶子并排；在 repo 存储中其负责人也是如此；不要把 status 写入叶子文件。bmad-ticket 仅按 references/board.md 所述更改它们，且计划永不发送到 tracker。

默认情况下，树就是存储。配置了 tracker 时，它是远程：write 将工单推送到它，query 从它读回。

用 tickets.py find [<folder>] <ref> 解析用户指定的工单——1.2、tracker id、文件名、其标题中一连串不间断的短语；省略时，文件夹为活动 initiative，然后是 backlog/。

读取大量内容而返回很少内容的工作在子代理中运行：了解代码库、打开引用、从存储读取树、验证检查、网络搜索。如果 harness 阻止子代理，请说明并继续内联执行。