在需要把想法、PRD、会议记录、RFC 等任意输入提炼为…

当用户要求创建、提炼、验证或更新规范，并需要产出 SPEC.md 及配套 companion 文件供下游技能消费时使用。

适用场景

解决思路

1. 激活时解析 customization：运行 `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`。
2. 如果 resolve_customization.py 不存在，提示 BMad 尚未在此设置；提议运行 `bmad` 技能的 setup，若未安装先运行 `npx skills add bmad-code-org/BMAD-METHOD --skill bmad`，然后重试该解析命令。
3. 如果 resolve_customization.py 因其他原因失败，直接读取 `{skill-root}/customize.toml`。
4. 运行 `{workflow.activation_steps_prepend}`；把 `{workflow.persistent_facts}` 当作基础上下文，并加载其中 `file:` 条目。
5. 解析配置：运行 `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}`，该命令合并 `_bmad/config.toml` 与 `_bmad/custom/` 覆盖；从合并 JSON 解析 `{project_name}`、`{output_folder}`（位于 `core` 下）和 `{date}`。
6. 检测模式：无 TTY、程序化调用者（另一技能或非交互 runner）、或首条消息预供所有输入并要求返回 artifact 路径时设为 Headless；否则设为 Interactive。
7. 交互模式问候用户，并提及 `bmad-party-mode` 和 `bmad-advanced-elicitation` 可用于深入探索任意字段。
8. 运行 `{workflow.activation_steps_append}`；激活完成后，若 prepend/append 非空，按顺序确认每个条目已执行，再进入主工作流。
9. 将 spec 始终建成文件夹：`{workflow.spec_output_path}/{workflow.run_folder_pattern}`，默认解析为 `{output_folder}/specs/spec-{slug}/`。
10. 解析 `{slug}`：它描述被 spec 的事物而非输入形态；源 artifact 已带 slug 时继承（如 `prd-foo-bar-2026-05-23/` 继承为 `foo-bar`）；稀疏、聊天或多源输入时，交互模式询问，headless 由调用者提供；缺失且无法推导时，headless 以 `error_code: "missing_slug"` 阻塞。
11. 同一 slug 对应同一文件夹；第二次同 `{slug}` 调用落到已有 spec 文件夹并原地更新，保留 capability IDs。
12. 无输入时：交互模式让用户提供文件路径、粘贴内容、详细解释想法或指向来源；headless 返回含 `error_code: "insufficient_intent"` 的 JSON。
13. 按结构创建 spec 文件夹：`SPEC.md`（大写，kernel，从 `.memlog.md` 派生，绝不手编）、可选的按内容类型命名的 `<companion-N>.md`、`.memlog.md`（规范、只追加内存，`SPEC.md` 从它提炼）。
14. 把 `.memlog.md` 作为 canonical append-only 时间顺序记录：每个 decision、constraint、capability（带稳定 `CAP-N`）、assumption、open question、用户 direction 一行一条，按发生顺序，绝不编辑或重排。
15. 每次运行从 memlog（decision-of-record）及其引用的源原始内容派生 `SPEC.md` 和所有 spec-authored companion，绝不手补。
16. 通过共享脚本 `{project-root}/_bmad/scripts/memlog.py` 写 memlog；该脚本与 `resolve_customization.py` 同位置，原子写入，除恢复外不要读回。
17. 创建时运行一次：`uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>"`。
18. 每项落定即运行：`uv run {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type <decision|constraint|capability|assumption|question|direction|note|event> --text "<one-line gist, reason included>"`。
19. 终端时刻（验证裁决、"spec finalized"）用 `--type event` 追加；memlog 不携带 status 字段。
20. 读取输入及其辅助链接材料；无输入时走无输入分支；目标文件夹已有 `.memlog.md` 时读取它，操作变为更新，memlog（而非渲染的 `SPEC.md`）是决定和 capability IDs 的权威。
21. 更新时保留已有 capability IDs；新 capability 取下一个未使用的 `CAP-N`；绝不重用已退役 IDs；若为创建，第一步运行 `memlog.py init`。
22. 结构化且预排序输入（如 PRD 加 addendum、GDD、上游 BMad 技能生成的 brief）：信任作者分离，把适合 kernel 的内容提升到 SPEC.md，把 overflow 提升到适当命名的 companions。
23. 混合输入（brain dump、transcript、RFC、customer email）：自行排序，逐条 claim，应用三透镜 load-bearing 测试（Spec Law rule 7），路由到 kernel 字段或 companion。
24. 使用 `{workflow.spec_template}` 作骨架，将输入提炼成五字段 kernel：Why、Capabilities、Constraints、Non-goals、Success signal。
25. 输入丰富时直接提取，不做 elicitation。
26. 输入稀疏时选择 express（尽力提炼，每个 gap 变成 `open_questions[]` 条目）或 guided（与用户逐字段走五字段）；Headless 默认 express 并记录选择，Interactive 询问。
27. 输入未触及但可识别的领域含义是 gap：作为 `open_questions[]` 条目命名（如医疗未提 PHI/HIPAA、支付未提 PCI、控制系统未提 fail-safe）并继续；标记它，绝不发明答案或引导；若这些占主导，说明输入太薄并建议 `bmad-prd`。
28. 从第一遍就写精简：每句话必须赚得位置；装饰消耗 token 并稀释下游读者。
29. 每个 decision、capability、constraint 和接受的变更发生时记录到 `.memlog.md`，供渲染读取；append-only 允许后续条目在相同点上取代早期条目，同时保留历史。
30. 当两个当前活跃的 sources 或 companions 在同一字段上不一致，或 either/or 未解决时，向用户暴露而非静默选择；解决本身作为新的 memlog 条目。
31. 如果输入确实太薄无法提炼（如 "an app for hikers" 无上下文），停止并建议 `bmad-prd`（或 sibling ceremony skill）；此技能只提炼，不教练。
32. 判断 load-bearing：如果任何消费者（下游 skill、实现 agent、验证 pass）没有该 claim 就会改变决策，则该 claim 是 load-bearing。
33. 当 load-bearing 内容不适合五字段 kernel 时，创建 companion；kernel 引用它，companion 持有它；companion 是契约一部分，消费者通过 SPEC.md frontmatter 的 `companions:` 发现，并遵循与 SPEC.md 相同的 lean 纪律（Spec Law rule 8）。
34. 当内容需要超过一行 kernel-shape 时生成 companion：多项目录（per-entity matrices 如 archetypes、drinks、modes、routes）、表格、图（总是）、editorial voice rules、kernel 按名称引用的长参考材料（glossary、brownfield notes、project conventions）。
35. 单行 decision-benders 留在 Constraints；intent+success 对留在 Capabilities；若 kernel 字段开始 bullet 成 sub-bullets，内容已超出 kernel，应创建 companion。
36. Spec-authored companions 由 bmad-spec 编写，位于 SPEC.md 同级（如 `glossary.md`、`patron-archetypes.md`）；bmad-spec 拥有它们，更新操作可编辑它们。
37. Adopted companions 是由上游 skill 编写、下游仍需读取的 load-bearing artifacts；bmad-spec 通过相对路径引用进 `companions:`，但不编辑它们（如 UX run 的 `DESIGN.md` 或 `EXPERIENCE.md`、集成伙伴的 API spec）；原 skill 拥有它们。
38. 命名 spec-authored companions 按内容类型：`glossary.md`、`<entity-class>.md`（如 `patron-archetypes.md`、`medication-routes.md`、`flight-modes.md`）、`stack.md`、`conventions.md`、`brownfield.md`、`architecture-diagrams.md`、`state-machines.md`、`failure-modes.md`、`compliance-references.md`；原则是读者打开前应知道里面是什么。Adopted companions 保留原 skill 的名字。
39. Diagrams 无论大小都总是放进 companion；SPEC.md kernel 只放 prose；Mermaid blocks、ASCII diagrams、image references 都住在 companion（如 `architecture-diagrams.md`），同级 image 文件从那里引用。
40. 预先存在的项目级文档（如 `project-context.md`）若下游需要，列为 adopted companions，绝不复制到 SPEC.md 或 spec-authored companion。
41. 遵守 Spec Law 八条规则：1) 每个 capability 同时有 `intent` 和 `success`，缺一不是 capability；2) Intents 描述 WHAT 而非 HOW，实现处方归 companion（stack、conventions）；3) Constraints 必须实际弯曲设计决策，不排除任何东西是装饰；4) Non-goals 明确且至少一个；5) Success signal 足够具体，可测试或演示，"Users love it" 不合格；6) Capability IDs 稳定唯一，绝不重用或重编号；7) Preservation：每个 load-bearing source claim 落在 SPEC.md 或 companion，wrapper ceremony 不落；8) Lean prose：每句话承载 load-bearing 内容，砍装饰、含糊、背景、清嗓，适用于 SPEC.md、companions、`.memlog.md`。
42. 每次 create 或 update 后，在展示前对结果 artifact 做两遍 self-validate。
43. Pass 1 — Coherence：按 Spec Law rules 1–6 和 8 判断 spec；对失败或弱的地方尝试修复而不发明输入不支持的内容；无直接确认的调用变成 `assumptions[]`，无法填补的 gap 变成 `open_questions[]`。
44. Pass 2 — Preservation：逐条走源 claim，确认每个 load-bearing claim 落在 SPEC.md 或 companion；wrapper-ceremony 丢弃记录在 "Wrapper-only content" 下，使丢弃有记录而非静默。
45. 将每遍裁决用 `append --type event` 记录到 `.memlog.md`；交互模式与用户审查；headless 模式 `.memlog.md` 是返回文件之一，调用者或其下游 LLM 在那里读裁决。
46. 当用户指向已有 spec 文件夹（或 SPEC.md）且无变更信号时，提供审查 assumptions 或 open questions，或确定他们想做什么。
47. 可选、仅交互的 ticketing handoff：需要磁盘上有 `SPEC.md`，若不存在先运行正常 Operation；headless 即使调用文本要求也完全跳过本节并继续正常 headless 响应。
48. 交互模式下，当输入读起来像多个可独立交付的 slices 时，每次运行最多提供一次 handoff 给 `bmad-preview-ticketing`；拒绝结束本次运行的 offer，不是永远。
49. 将 spec 文件夹交给 `bmad-preview-ticketing` 作为需求源：它和用户规划工作为一个 epic，其 `tickets.toml` 条目引用此 spec 的 `CAP-N` ids，并从那里运行 board；切片对话浮现的 load-bearing 细节（constraint、design decision）回到这里作为 spec update，绝不只进入 ticket。
50. 当 spec update 运行，搜索 ticket root 中此 spec 文件夹路径在 References；凡 tickets 引用它，指出描述不再匹配的 entries 和 tickets，并提供用 `bmad-preview-ticketing` 重新切片；更新本身绝不编辑 ticket。
51. Interactive 输出：对话式分享 spec 文件夹路径；一两句话说明 capability 数量、产生的 companions、裁决；若 `assumptions[]` 或 `open_questions[]` 非空，简短列出（一行一条）并邀请用户走过；明确处理它们可更新源输入（若为文件）、spec 或两者，由用户偏好；不要 dump JSON 或展示墙。
52. Headless 输出：按 `assets/headless-schemas.md` 返回 JSON。
53. 若设置了 `{workflow.on_complete}`，运行它。
54. Spec 输出后，任何更新（解决的 assumptions、回答的 open questions、其他变更）发生时追加到 `.memlog.md`；当变更覆盖来自源输入的内容，提供更新该源，使上游和 spec 不静默分叉。
55. Frontmatter 的 `companions:` 数组中列下游必须与 SPEC.md 一起读取的 `.md` 文件，以获得完整契约；路径可在 spec 文件夹内（spec-authored companions 如 `glossary.md`）或外（adopted companions 如 `../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md`）；spec-authored 与 adopted 由路径隐式区分，下游同等对待。
56. Frontmatter 的 `sources:` 数组列已完全吸收进 SPEC、无剩余下游价值的文件路径（如每个 load-bearing claim 都已在 kernel 的 PRD），用于审计和 bmad-spec 更新时重读；下游不读这些；下游仍需读取的文件放 `companions:` 而非 `sources:`。
57. 不要列 memlog、README、组织 artifacts、或上游 skill 如何产生其 artifacts 的操作记录；那些不是 source content，是下游消费者不需要的 process metadata。
58. Conventions：裸路径（如 `assets/spec-template.md`）从 skill root 解析；`{skill-root}` 是此技能安装目录，`{project-root}` 是工作目录；`{workflow.<name>}` 解析为 `customize.toml` 中的字段。

适用边界 · 注意事项

• 输入太薄无法提炼（如只有“an app for hikers”且无上下文）时，应改用 `bmad-prd` 或同类仪式技能。
• 未设置 BMad 环境且不愿安装或运行 BMad 相关脚本时，解析 customization/config 和写 memlog 会失败。
• 想绕过 `.memlog.md` 直接手工编辑 `SPEC.md` 时；外部手编不受支持，并会在下次派生时被覆盖。