bmad-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BMad Spec

BMad 规范

Overview

概述

Canonical transformer for the BMad spec-kernel ecosystem. Takes any intent input — vague idea, brain dump, PRD, GDD, RFC, brief, Slack thread, customer email, meeting transcript, mockups, mixed multi-source — and produces SPEC.md carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit or would bloat the kernel with expansive line-item detail. Together they are the machine contract every downstream BMad skill consumes.

Multiple skills may call to update the same spec over time.

BMad规范内核生态系统的标准转换器。可接收任意意图输入——模糊想法、头脑风暴记录、PRD、GDD、RFC、简报、Slack线程、客户邮件、会议记录、原型图、多源混合内容——并生成包含五字段内核（Why、Capabilities、Constraints、Non-goals、Success signal）的SPEC.md文件，以及承载不适合放入内核或会导致内核过于冗长的负载内容的配套文件。这些文件共同构成所有下游BMad技能遵循的机器契约。

多个技能可随时间调用以更新同一规范。

Conventions

约定

Bare paths (e.g.
```
assets/spec-template.md
```
) resolve from the skill root.
```
{skill-root}
```
is this skill's install dir;
```
{project-root}
```
is the working dir.
```
{workflow.<name>}
```
resolves to fields in
```
customize.toml
```
.

裸路径（如
```
assets/spec-template.md
```
）从技能根目录解析。
```
{skill-root}
```
为本技能的安装目录；
```
{project-root}
```
为工作目录。
```
{workflow.<name>}
```
解析为
```
customize.toml
```
中的字段。

On Activation

激活流程

Resolve customization:

uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

. On failure, read

{skill-root}/customize.toml

directly.

Run

{workflow.activation_steps_prepend}

. Treat

{workflow.persistent_facts}

as foundational context (

file:

entries are loaded).

Resolve config:

uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}

(merges

_bmad/config.toml

_bmad/config.user.toml

, and the

_bmad/custom/

overrides). From the merged JSON resolve

{user_name}

{communication_language}

{document_output_language}

{project_name}

{output_folder}

(under

core

), and

{date}

Detect mode. Headless when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. Interactive otherwise. In interactive mode, greet by
```
{user_name}
```
in
```
{communication_language}
```
, stay in that language, and mention that
```
bmad-party-mode
```
and
```
bmad-advanced-elicitation
```
are available for deeper exploration on any field.

Run

{workflow.activation_steps_append}

Activation is complete. If

activation_steps_prepend

activation_steps_append

were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

解析自定义配置：执行

uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

。若执行失败，则直接读取

{skill-root}/customize.toml

。

运行

{workflow.activation_steps_prepend}

。将

{workflow.persistent_facts}

视为基础上下文（加载其中的

file:

条目）。

解析配置：执行

uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}

（合并

_bmad/config.toml

、

_bmad/config.user.toml

及

_bmad/custom/

中的覆盖配置）。从合并后的JSON中解析

{user_name}

、

{communication_language}

、

{document_output_language}

、

{project_name}

、

{output_folder}

（位于

core

下）和

{date}

。

检测模式。满足以下任一条件时为无头模式：无TTY、程序化调用者（另一技能或非交互式运行器），或第一条消息预先提供所有输入并要求返回产物路径。否则为交互式模式。在交互式模式下，以
```
{communication_language}
```
向
```
{user_name}
```
打招呼，并保持该语言，同时提及
```
bmad-party-mode
```
和
```
bmad-advanced-elicitation
```
可用于对任意字段进行深度探索。

运行

{workflow.activation_steps_append}

。

激活完成。若

activation_steps_prepend

或

activation_steps_append

非空，需确认所有条目已按顺序执行后再继续。在所有激活步骤完成前，不得启动主工作流。

Workspace

工作区

The spec is always a folder named

{workflow.spec_output_path}/{workflow.run_folder_pattern}

, resolving by default to

{output_folder}/specs/spec-{slug}/

{slug}

describes the thing being specced, not the input shape:

Source artifact already carries a slug (e.g.,
```
prd-foo-bar-2026-05-23/
```
): inherit (
```
foo-bar
```
).
Sparse, in-chat, or multi-source input: interactive asks; headless caller provides it as part of the input. If absent and underivable, headless blocks with
```
error_code: "missing_slug"
```
.
Same slug = same folder. A second invocation with the same
```
{slug}
```
lands at the existing spec folder and updates in place, preserving capability IDs.

No input. Interactive: ask the user to share a file path, paste content, explain the idea in detail, or point to a source. Headless: respond with JSON containing

error_code: "insufficient_intent"

Inside the spec folder:

<spec-folder>/
  SPEC.md                  ← uppercase, the kernel — DERIVED from .memlog.md, never hand-edited
  <companion-1>.md         ← optional, content-typed (e.g. glossary.md); spec-authored ones are derived too
  <companion-2>.md
  stories.yaml             ← optional, written only by Story Breakdown — fixed name, never in companions:
  .memlog.md               ← canonical, append-only memory; what SPEC.md is distilled from

规范始终是一个名为

{workflow.spec_output_path}/{workflow.run_folder_pattern}

的文件夹，默认解析为

{output_folder}/specs/spec-{slug}/

。

{slug}

描述的是被规范的对象，而非输入形式：

源产物已包含slug（如
```
prd-foo-bar-2026-05-23/
```
）：继承该slug（
```
foo-bar
```
）。
零散的聊天输入或多源输入：交互式模式下询问用户；无头模式下由调用者作为输入的一部分提供。若缺失且无法推导，无头模式将阻塞并返回
```
error_code: "missing_slug"
```
。
相同slug对应同一文件夹。使用相同
```
{slug}
```
的第二次调用将指向现有规范文件夹并就地更新，保留能力ID。

无输入场景：交互式模式下，要求用户分享文件路径、粘贴内容、详细解释想法或指明来源。无头模式下，返回包含

error_code: "insufficient_intent"

的JSON。

规范文件夹内部结构：

<spec-folder>/
  SPEC.md                  ← 大写，内核文件——由.memlog.md派生，禁止手动编辑
  <companion-1>.md         ← 可选，按内容类型命名（如glossary.md）；由规范生成的文件同样为派生文件
  <companion-2>.md
  stories.yaml             ← 可选，仅由故事拆分功能生成——固定名称，不属于配套文件：
  .memlog.md               ← 标准的追加式日志；SPEC.md的提炼来源

Memory and derivation

日志与派生

.memlog.md

is canonical — an append-only, chronological record of every decision, constraint, capability (with its stable

CAP-N

), assumption, open question, and bit of user direction, one line each in the order it happened, never edited or reordered.

SPEC.md

and every spec-authored companion are derived on each run from the memlog (the decision-of-record) plus the sources it cites for raw content — never hand-patched.

Deriving the contract from a living log instead of editing the contract in place is what lets the steps around the spec (PRD, UX, architecture, epics) run in any order and feed the same spec without merge drift: the log only accumulates, the artifact is re-rendered. So the spec is updated only by re-deriving it here — bmad-spec is its single writer; a hand-edit to

SPEC.md

from outside is unsupported and is overwritten on the next derive.

Writes go through the shared script —

{project-root}/_bmad/scripts/memlog.py

, the same location as

resolve_customization.py

(atomic; never read it back except to resume):

uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>"

— once, at create.

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>"

— as each lands.

Terminal moments (a validation verdict, "spec finalized") are
```
--type event
```
entries; the memlog carries no status field.

.memlog.md

是标准日志——按时间顺序追加记录每个决策、约束、能力（含稳定的

CAP-N

标识）、假设、未解决问题和用户指示，每条记录占一行，按发生顺序排列，永不编辑或重排。

SPEC.md

及所有由规范生成的配套文件均每次运行时从日志（决策记录）及其引用的原始内容源派生，禁止手动修改。

从动态日志而非直接编辑契约来派生契约，可确保围绕规范的各个环节（PRD、UX、架构、史诗）能按任意顺序推进并同步更新同一规范，避免合并偏差：日志仅不断累积，产物重新渲染。因此，规范仅能通过在此处重新派生进行更新——bmad-spec是其唯一写入者；外部对

SPEC.md

的手动编辑不受支持，且会在下次派生时被覆盖。

写入操作通过共享脚本

{project-root}/_bmad/scripts/memlog.py

完成（与

resolve_customization.py

位于同一位置，操作原子化；除恢复场景外从不读取）：

uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>"

—— 创建时执行一次。

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>"

—— 每次产生新内容时执行。

关键节点（验证结论、“规范定稿”）作为
```
--type event
```
条目记录；日志不包含状态字段。

The Operation

核心操作

Read the input and its ancillary linked materials. If there is no input, follow the no-input branch in Workspace (ask or block). If a prior

.memlog.md

exists at the target folder, read it — the operation becomes an update, and the memlog (not the rendered

SPEC.md

) is the authority on what was decided and on capability IDs. Preserve those IDs; new capabilities get the next unused

CAP-N

; never reuse retired IDs. Otherwise this is a create, and the first move is

memlog.py init

When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a brief produced by an upstream BMad skill), trust the authored separation: lift kernel-fitting content into SPEC.md, lift overflow into appropriately-named companions. When the input is mixed (a brain dump, a transcript, an RFC, a customer email), do the sorting yourself: walk each claim, apply the three-lens load-bearing test (Spec Law rule 7), and route to the kernel field or a companion.

Distill the input into the five-field kernel using

{workflow.spec_template}

as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: express (best-effort distill, every gap becomes an

open_questions[]

entry) or guided (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.

A recognized domain implication the input leaves unaddressed is such a gap — name it as an

open_questions[]

entry (healthcare input silent on PHI/HIPAA, payments silent on PCI, control systems silent on fail-safe) and move on. Flag it; never invent the answer or coach toward it. If these dominate, the input is too thin — suggest

bmad-prd

Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.

Log each decision, capability, constraint, and accepted change to

.memlog.md

as it is made — that running record is what the render reads. Because the log is append-only, a later entry supersedes an earlier one on the same point while the history stays intact. When two currently-live sources or companions disagree on the same field, or an either/or never got resolved, surface it to the user rather than silently choosing — the resolution is itself a new memlog entry.

If the input is genuinely too thin to distill (e.g. "an app for hikers" with no surrounding context), stop and suggest

bmad-prd

(or sibling ceremony skill). This skill distills; it does not coach.

读取输入及其关联的附属材料。若无输入，遵循工作区中的无输入分支逻辑（询问用户或阻塞）。若目标文件夹中存在先前的

.memlog.md

，则读取该文件——此时操作为更新，日志（而非已渲染的

SPEC.md

）是决策内容和能力ID的权威来源。保留这些ID；新能力使用下一个未被使用的

CAP-N

；永不复用已废弃的ID。否则为创建操作，第一步执行

memlog.py init

。

当输入为结构化且已预分类时（如带附录的PRD、GDD、上游BMad技能生成的简报），信任原有的内容划分：将适合放入内核的内容提取至SPEC.md，将超出内核容量的内容提取至对应名称的配套文件。当输入为混合内容时（如头脑风暴记录、会议记录、RFC、客户邮件），自行分类：逐条梳理每个主张，应用三视角负载测试（规范法则第7条），并将其分配至内核字段或配套文件。

以

{workflow.spec_template}

为框架，将输入提炼为五字段内核。若输入内容丰富，直接提取——无需引导。若输入内容稀疏，选择：快速提炼（尽最大努力提炼，每个空白处生成

open_questions[]

条目）或引导式提炼（逐个字段引导用户完善）。无头模式默认使用快速提炼并记录该选择。交互式模式下询问用户选择。

若输入未提及某个公认的领域隐含要求，这也属于空白——将其命名为

open_questions[]

条目（如医疗输入未提及PHI/HIPAA、支付输入未提及PCI、控制系统未提及故障安全）并继续处理。仅标记此类问题；绝不自行编造答案或引导用户给出答案。若此类问题占主导，说明输入内容过于单薄——建议使用

bmad-prd

。

从第一次提炼开始保持精简：每句话都必须有存在的价值。冗余内容会消耗token并分散下游读者的注意力。

将每个决策、能力、约束和已接受的变更在做出时记录至

.memlog.md

——这份动态记录是渲染操作的数据源。由于日志是追加式的，后续条目将取代先前针对同一问题的条目，同时保留历史记录。当两个当前有效的源或配套文件在同一字段上存在分歧，或二选一的决策未被解决时，需向用户指出该问题而非默默选择——问题的解决方案本身就是一条新的日志条目。

若输入确实过于单薄无法提炼（如“一款面向徒步者的应用”且无任何上下文），停止操作并建议使用

bmad-prd

（或同类仪式技能）。本技能仅负责提炼内容；不提供引导创作的功能。

Load-bearing

负载内容

A claim is load-bearing if any consumer (downstream skill, implementing agent, verification pass) would change a decision without it.

若某个主张会导致任何消费者（下游技能、实现Agent、验证环节）改变决策，则该主张属于负载内容。

Companions

配套文件

When load-bearing content does not fit the five-field kernel, it lives in a companion. The kernel cites it; the companion holds it. Companions are part of the contract; every consumer reads

companions:

in SPEC.md frontmatter to discover them. Companions follow the same lean discipline as SPEC.md (Spec Law rule 8).

Spawn a companion when the content needs more than one kernel-shape line: multi-item catalogs (per-entity matrices like archetypes, drinks, modes, routes), tables, diagrams (always), editorial voice rules, long-form reference material the kernel cites by name (glossary, brownfield notes, project conventions). Single-line decision-benders stay in Constraints; intent+success pairs stay in Capabilities. If a kernel field is starting to bullet into sub-bullets, the content has outgrown the kernel and wants a companion.

Companions are either:

Spec-authored companions are written by bmad-spec and live as siblings of SPEC.md (e.g.,
```
glossary.md
```
,
```
patron-archetypes.md
```
). bmad-spec owns them and may edit them on update operations.
Adopted companions are load-bearing artifacts written by an upstream skill that downstream still needs to read. bmad-spec references them into
```
companions:
```
by relative path but does NOT edit them (e.g., a
```
DESIGN.md
```
or
```
EXPERIENCE.md
```
from a UX run, an integration partner's API spec). The originating skill owns them.

Two rules govern companions:

Name spec-authored companions for the content type they hold.
```
glossary.md
```
,
```
<entity-class>.md
```
(e.g.
```
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
```
. The principle: "a reader should know what is inside before opening it." Adopted companions keep whatever name their originating skill gave them.
Diagrams always land in a companion, regardless of size. SPEC.md kernel holds prose only. Mermaid blocks, ASCII diagrams, and image references all live in a companion (e.g.
```
architecture-diagrams.md
```
), with sibling image files referenced from there.

Pre-existing project-wide docs (e.g.

project-context.md

) that downstream needs are listed as adopted companions, never duplicated into SPEC.md or a spec-authored companion.

stories.yaml

, when produced, is spec-authored but deliberately not a companion — see Story Breakdown below.

当负载内容不适合放入五字段内核时，将其放入配套文件。内核中会引用这些文件；配套文件承载具体内容。配套文件是契约的一部分；所有消费者都会读取SPEC.md前置元数据中的

companions:

来发现这些文件。配套文件需遵循与SPEC.md相同的精简原则（规范法则第8条）。

当内容需要多于一行内核格式的空间时，生成配套文件：多条目目录（如原型、饮品、模式、路线等按实体分类的矩阵）、表格、图表（无论大小）、编辑风格规则、内核按名称引用的长篇参考资料（术语表、遗留系统说明、项目约定）。单行决策约束保留在Constraints中；意图+成功标准对保留在Capabilities中。若某个内核字段开始出现多级项目符号，说明内容已超出内核容量，应放入配套文件。

配套文件分为两类：

规范生成的配套文件：由bmad-spec编写，与SPEC.md同级（如
```
glossary.md
```
、
```
patron-archetypes.md
```
）。bmad-spec拥有这些文件的所有权，并可在更新操作中编辑它们。
引入的配套文件：由上游技能编写的负载内容产物，下游仍需读取。bmad-spec通过相对路径将其引用到
```
companions:
```
中，但不会编辑它们（如UX环节生成的
```
DESIGN.md
```
或
```
EXPERIENCE.md
```
、集成合作伙伴的API规范）。这些文件的所有权归原生成技能所有。

配套文件需遵循两条规则：

规范生成的配套文件按内容类型命名。如
```
glossary.md
```
、
```
<实体类别>.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
```
。原则：“读者在打开文件前应知道其中内容”。引入的配套文件保留原生成技能赋予的名称。
图表始终放入配套文件，无论大小。SPEC.md内核仅包含文字内容。Mermaid代码块、ASCII图表和图片引用均放入配套文件（如
```
architecture-diagrams.md
```
），并在其中引用同级图片文件。

下游需要的现有项目级文档（如

project-context.md

）列为引入的配套文件，绝不复制到SPEC.md或规范生成的配套文件中。

stories.yaml

（若生成）由规范生成，但特意不属于配套文件——详见下文的故事拆分部分。

Spec Law

规范法则

Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.

Each capability has both
intent
and
success
. Missing either = not a capability.
Intents describe WHAT, not HOW. Implementation prescription belongs in a companion (stack, conventions).
Constraints actually bend design decisions. A "constraint" that rules nothing out is decoration.
Non-goals are explicit. At least one. Absence means downstream skills fill the vacuum.
Success signal is concrete enough to test or demonstrate against. "Users love it" doesn't qualify.
Capability IDs are stable and unique. Never reused, never renumbered.
Preservation. Every load-bearing source claim lands in SPEC.md or a companion. Wrapper ceremony does not.
Lean prose. Every sentence carries load-bearing content. Cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and
```
.memlog.md
```
.

每个规范必须满足以下八条规则。核心操作以满足这些规则为目标；自验证环节强制执行这些规则。

每个能力同时包含
intent
和
success
。缺少任意一项则不构成能力。
意图描述WHAT，而非HOW。实现细节应放入配套文件（技术栈、约定）。
约束必须实际影响设计决策。无法排除任何可能性的“约束”属于冗余内容。
非目标需明确。至少包含一项。若缺失，下游技能会自行填补空白。
成功标准需足够具体，可用于测试或演示。“用户喜欢它”不符合要求。
能力ID需稳定且唯一。永不复用，永不重新编号。
完整性。每个负载内容源的主张都必须放入SPEC.md或配套文件中。仅作为流程包装的内容可忽略。
精简文字。每句话都承载负载内容。删除冗余内容、模棱两可的表述、背景故事和开场白。适用于SPEC.md、配套文件和
```
.memlog.md
```
。

Self-Validate

自验证

After every create or update, sweep the resulting artifact in two passes before presenting.

Pass 1 — Coherence. Judge the spec against Spec Law rules 1–6 and 8. For anything that fails or feels weak, attempt to fix it without inventing content the input did not support. Calls made without direct confirmation become

assumptions[]

; gaps that could not be filled become

open_questions[]

Pass 2 — Preservation. Walk the source claim by claim. Confirm each load-bearing claim landed in SPEC.md or a companion. Wrapper-ceremony drops are logged under "Wrapper-only content" so the drop is on the record, not silent.

Record the verdict for each pass to

.memlog.md

(

append --type event

). In interactive mode, review it with the user. In headless mode,

.memlog.md

is one of the files returned, so the caller (or its downstream LLM) reads the verdict there.

每次创建或更新后，在呈现产物前对其进行两轮检查。

第一轮——一致性。根据规范法则第1-6条和第8条判断规范是否合格。对于不符合规则或存在缺陷的内容，尝试在不添加输入中未包含的内容的前提下修复。未获直接确认的修改将作为

assumptions[]

记录；无法填补的空白将作为

open_questions[]

记录。

第二轮——完整性。逐条梳理源内容的每个主张。确认每个负载内容主张都已放入SPEC.md或配套文件中。仅作为流程包装的内容将记录在“仅包装内容”下，确保删除操作有迹可循而非静默处理。

将每轮检查的结论记录至

.memlog.md

（使用

append --type event

）。交互式模式下，与用户一起回顾结论。无头模式下，

.memlog.md

是返回的文件之一，因此调用者（或其下游LLM）可在其中读取结论。

Spec with no change signal

无变更信号的规范处理

When the user points the skill at an existing spec folder (or its SPEC.md) with no change signal, offer to review assumptions or open questions, or determine what they want to do.

当用户指向现有规范文件夹（或其SPEC.md）但未给出变更信号时，提供查看假设或未解决问题的选项，或询问用户需求。

Story Breakdown (optional, interactive-only)

故事拆分（可选，仅交互式模式）

Requires

SPEC.md

on disk — run the normal Operation first if it doesn't exist yet. Headless runs never do this, even when the invocation text asks for it: if mode detection (On Activation, step 4) resolved headless, skip this section entirely and proceed with the normal headless response. In interactive mode, offer it at most once per run when the input reads as multiple independently shippable slices; a decline ends the offer for this run, not forever. Also run it on direct request ("break this into stories") whenever

SPEC.md

exists. When a spec update runs and

stories.yaml

exists, check the story descriptions against the updated spec; if any no longer matches, say so and offer to re-run Story Breakdown. The update itself never rewrites

stories.yaml

Either way, walk the capabilities and constraints with the user and propose a story per independently reviewable slice — this is a conversation, not a silent render. For each story, ask the user for

spec_checkpoint

done_checkpoint

, and any

invoke_dev_with

note rather than defaulting them silently; capturing that human judgment is what the fields are for. If the conversation surfaces load-bearing detail beyond dispatch notes (a constraint, a design decision), route it into SPEC.md or a companion —

invoke_dev_with

carries dispatch notes only (Spec Law rule 7 still applies).

The output is

stories.yaml

, a sibling of

SPEC.md

inside the spec folder, discovered by that fixed name — same convention as

SPEC.md

and

.memlog.md

. Never list it in

companions:

and never point a frontmatter key at it: companions carry the what-to-build contract every consumer reads;

stories.yaml

is input for whichever tool dispatches the stories.

Field definitions, the validity rules, and a worked example live in

assets/stories-schema.md

. Before writing or re-writing the file, check every entry against those rules; fix violations rather than presenting a file that fails them. Record the check's verdict to

.memlog.md

(

append --type event

), the same discipline as Self-Validate.

Derive

stories.yaml

from

.memlog.md

exactly like any other spec-authored artifact: log each proposed story (

--type decision

) as the user agrees to it, then render. On a later run against the same spec folder, re-derive the same way, handling ids per the schema's update semantics.

要求磁盘上存在

SPEC.md

——若不存在，先执行正常核心操作。无头模式下绝不执行此操作，即使调用文本要求拆分：若激活流程第4步检测为无头模式，完全跳过本节并继续正常的无头响应。交互式模式下，仅当输入可拆分为多个独立可交付的模块时，在每次运行中最多提供一次该选项；用户拒绝后，本次运行不再提供。当用户直接请求（“将此拆分为用户故事”）且

SPEC.md

存在时，也执行此操作。当规范更新完成且

stories.yaml

已存在时，检查用户故事描述是否与更新后的规范匹配；若不匹配，告知用户并提供重新运行故事拆分的选项。更新操作本身绝不会重写

stories.yaml

。

无论哪种情况，与用户一起梳理能力和约束，针对每个独立可评审的模块提出一个用户故事——这是一个对话过程，而非静默渲染。对于每个用户故事，询问用户提供

spec_checkpoint

、

done_checkpoint

和任何

invoke_dev_with

备注，而非默认填充；捕获人工判断是这些字段的作用。若对话过程中出现超出调度备注的负载内容（如约束、设计决策），将其分配至SPEC.md或配套文件——

invoke_dev_with

仅承载调度备注（仍需遵循规范法则第7条）。

输出为

stories.yaml

，位于规范文件夹内，与SPEC.md同级，通过固定名称被发现——与

SPEC.md

和

.memlog.md

遵循相同约定。绝不在

companions:

中列出该文件，也绝不向前置元数据中的任何键指向该文件：配套文件承载所有消费者都需读取的构建契约；

stories.yaml

是用于调度用户故事的工具的输入。

字段定义、有效性规则和示例位于

assets/stories-schema.md

。在写入或重写文件前，检查每个条目是否符合这些规则；修复违规内容，而非呈现不符合规则的文件。将检查结论记录至

.memlog.md

（使用

append --type event

），与自验证环节遵循相同规范。

stories.yaml

的派生方式与其他规范生成的产物完全相同：当用户同意某个提议的用户故事时，将其记录至日志（

--type decision

），然后进行渲染。后续针对同一规范文件夹的运行中，以相同方式派生，根据模式的更新语义处理ID。

Output

输出

Interactive — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. Name the story count too if

stories.yaml

was written this run. If

assumptions[]

open_questions[]

are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.

Headless — return JSON per

assets/headless-schemas.md

Run

{workflow.on_complete}

if set.

交互式模式——以对话方式分享规范文件夹路径。用一两句话说明能力数量、生成的配套文件和验证结论。若本次运行生成了

stories.yaml

，同时说明用户故事数量。若

assumptions[]

或

open_questions[]

非空，列出这些内容（简短——每条一行）并邀请用户逐一处理。明确告知用户解决这些问题可更新源输入（若为文件）、规范或两者的组合——由用户选择偏好的组合。不要输出JSON或大段内容。

无头模式——按照

assets/headless-schemas.md

返回JSON。

若设置了

{workflow.on_complete}

，则运行该命令。

After Spec is Output

规范输出后

Any update to the spec — resolved assumptions, answered open questions, other changes — is appended to

.memlog.md

as it happens. When a change overrides something that came from a source input, offer to update that source too, so upstream and the spec don't silently diverge.

对规范的任何更新——已解决的假设、已回答的未解决问题、其他变更——都会在发生时追加至

.memlog.md

。当变更覆盖了来自源输入的内容时，提供更新该源输入的选项，避免上游内容与规范悄然偏离。

Frontmatter conventions

前置元数据约定

```
companions:
```
array of
```
.md
```
files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like
```
glossary.md
```
) or outside it (adopted companions like
```
../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md
```
). The split between spec-authored and adopted is implicit by path; downstream treats both the same.
```
sources:
```
array of paths to files that were fully absorbed into the SPEC, with no remaining downstream value (e.g., a PRD whose every load-bearing claim is now in the kernel). Listed for audit and for bmad-spec to re-read on update. Downstream does NOT read these. Files that downstream still needs to read belong in
```
companions:
```
, not here.
Do not list the memlog, README files, organizational artifacts, or any operational record of how upstream skills produced their artifacts. Those are not source content; they are process metadata that downstream consumers don't need.

```
companions:
```
：下游必须与SPEC.md一起读取的
```
.md
```
文件数组。路径可指向规范文件夹内部（如
```
glossary.md
```
等规范生成的配套文件）或外部（如
```
../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md
```
等引入的配套文件）。规范生成和引入的配套文件通过路径隐含区分；下游对两者一视同仁。
```
sources:
```
：已被完全吸收到SPEC中的文件路径数组，这些文件对下游不再有价值（如所有负载内容主张已纳入内核的PRD）。列出这些文件用于审计及bmad-spec在更新时重新读取。下游不会读取这些文件。下游仍需读取的文件应放入
```
companions:
```
，而非此处。
请勿列出日志、README文件、组织性产物或任何上游技能生成产物的操作记录。这些不属于源内容；它们是下游消费者无需关心的流程元数据。