BMAD-Speckit-SDD-Flow：面向需求契约与证据链交付的 AI-TDD 控制面

English | 简体中文

目录

• 这是什么
• 核心 AI-TDD 模型
• 适用对象
• 前置条件
• 快速开始
• 运行时模型
• 常用技能与工作流选择
• 1.x 五层架构
• AI-TDD 控制面
• 六心智模型
• Manifest 契约与证据链
• CLI 安装与外部接口
• 交付收口证据
• 发布线兼容说明
• 仓库结构
• 文档入口
• 开发与贡献策略
• 许可证

这是什么

BMAD-Speckit-SDD-Flow 是一个需求契约驱动的 AI-TDD 控制面，用于治理 AI 辅助软件交付。它结合 BMAD-METHOD 的产品与交付结构，以及 Spec-Kit 的规格驱动开发流程，并在此基础上为 Cursor、Claude Code 和 Codex 增加一个由 Orchestrator Agent 统筹的治理控制面（编排中枢），负责路由工作、执行门禁并收口交付。

它不是要替代 BMAD 或 Spec-Kit，而是让从产品意图到技术实现的完整路径更安全、更可追溯，也更适合由 AI Agent 执行。工作流通过 CLI 安装到消费项目，然后在 Codex、Claude Code CLI 或 Cursor 中通过 bmads / bmad-speckit 技能激活编排中枢。

本项目中的 AI-TDD 遵循一条原则：没有经过确认的 Manifest，AI 就是在猜；没有当前 attempt 的证据链，交付就只是不可复核的乐观判断。Manifest 未达到足够完备状态前，编排中枢不能派发实现；当前 attempt 尚未闭合 Manifest 关联的 TRACE/EVD/CMD/ART 证据链、Gate Verdict 和 Human-in-the-loop 决策前，不能宣称交付完成。

CLI 是安装与外部接口。它负责把工作流安装到消费项目、校验安装面，并暴露看板、评分、Coach、SFT 数据提取等运行时只读或数据集成能力。日常交付控制属于用户在 AI 宿主中激活后的编排中枢。

它提供：

• 需求契约驱动的交付控制面。
• 跨 Cursor、Claude Code 与 Codex 的 Agent 治理。
• AI-TDD 工作流控制。
• 实现前准入门禁。
• 交付前完成门禁。
• 面向 TRACE/EVD/CMD/ART 的多维证据链验收。
• 降低 Agent 失控漂移的有界执行。
• 端到端 BMAD + Spec-Kit 交付流支持。

核心 AI-TDD 模型

运行模型是：

Intent -> Manifest Contract -> AI-TDD-RED -> Bounded Execution -> Evidence Chain -> AI-TDD-GREEN

| 阶段 | 含义 | 控制规则 | | ----------------- | --------------------------------------------------------------------- | --------------------------------------------------- | | Intent | 澄清人类目标、范围、不做项和假设。 | 歧义必须先转成契约语言，不能直接进入执行。 | | Manifest Contract | 注册 MUST、NEG、OUT、TRACE、EVD、CMD、ART、测试和任务。 | Manifest 是需求契约矩阵，不是测试清单。 | | AI-TDD-RED | 准入门禁确认契约和验收基线已经存在。 | 只有入口门禁达到该状态后，才能开始实现。 | | Bounded Execution | Agent 接收有界任务包，在已确认契约内实现。 | Agent 工作必须受 Manifest 约束，并绑定 trace rows。 | | Evidence Chain | 当前 attempt 产生可回放的 TRACE/EVD/CMD/ART 证据和审计 provenance。 | 陈旧证据和未绑定测试不能证明当前 attempt。 | | AI-TDD-GREEN | Gate Verdict 加 Human-in-the-loop 决策关闭本次交付。 | 只有 closeout 证据闭合后，才允许完成表述。 |

适用对象

适合以下场景：

• 你要把受治理的 AI 交付流程安装进消费项目，而不是只堆提示词。
• 你需要需求契约、准入门禁、交付门禁和证据追溯链。
• 你需要一个能 inspect 状态、路由工作、约束 bounded execution、阻断弱交付声明的顶层协调者。
• 你希望把 dashboard、scoring、Coach、SFT workflow 当作外部只读视图或数据集成面使用。

不适合以下场景：

• 你只想要一个没有运行时治理的最小 prompt library。
• 你只想要一个纯 codegen CLI，不需要宿主会话中的主控流程。
• 你打算跳过需求契约和门禁证据，直接让 AI 自由开工。

前置条件

| 工具 | 版本 | 作用 | | ---------- | -------------------------------- | -------------------------------------------------------------------------------- | | Node.js | 22+ | 用于已发布 CLI 和安装面。 | | npm | 9+ | 用于项目本地安装、npx --no-install、临时 npx --package 和 workspace 工作流。 | | PowerShell | Windows 上建议 7+ | 用于 setup、验证和运行时辅助脚本。 | | Git | 2.30+ | 用于 worktree、分支流和贡献流程。 | | AI 宿主 | Codex、Claude Code CLI 或 Cursor | 用于正常的 bmads / bmad-speckit 运行时入口。 |

快速开始

长期使用 $bmads、$bmad-help 和生成后的 skills 时，默认应把包安装为消费项目本地依赖。生成后的 skills 会通过 npx --no-install 调用项目本地 CLI，因此项目内必须存在 node_modules/.bin/bmad-speckit。

npm install --save-dev --ignore-scripts bmad-speckit-sdd-flow@latest
npm ls bmad-speckit-sdd-flow --depth=0
npx --no-install bmad-speckit version
npx --no-install bmad-speckit init . --ai codex --yes --force
npx --no-install bmad-speckit check
npx --no-install bmad-speckit dashboard-status
npx --no-install bmad-speckit bmads

如果要一次安装 Claude Code、Cursor 和 Codex 三个常用宿主面，把 --ai codex 改成 --ai claude,cursor-agent,codex。

--ignore-scripts 会把“依赖安装”和“安装面生成”分开：先安装包，再显式执行你需要的 bmad-speckit init ...。如果省略它，当前根包的 postinstall 会在依赖安装期间运行 scripts/init-to-root.js，可能在你显式选择 AI 宿主前先写入默认安装面。

然后切换到 AI 宿主会话里激活编排中枢：

$bmads

把 $bmad-help 用作工作流路由帮助即可；它不接管根运行时权限。

如果你是通过 CI artifact 安装而不是直接走 npm registry，推荐把本地 tarball 安装为项目依赖：

npm install --save-dev --ignore-scripts ./bmad-speckit-sdd-flow-<version>.tgz
npm ls bmad-speckit-sdd-flow --depth=0
npx --no-install bmad-speckit version
npx --no-install bmad-speckit init . --ai codex --yes --force
npx --no-install bmad-speckit check
npx --no-install bmad-speckit dashboard-status
npx --no-install bmad-speckit bmads

npx --package 只建议用于 smoke test、CI artifact 检查或一次性初始化。它不会把 runtime 持久安装到消费项目里，因此后续生成的 skills 可能因为 npx --no-install 找不到本地包而失败。

运行时模型

正常用户入口是在当前 AI 宿主会话中输入：

$bmads
/bmads
bmads
$bmad-speckit
/bmad-speckit
bmad-speckit

如果只需要 BMAD workflow 路由帮助，而不是让运行时接管根治理权限，使用：

$bmad-help

$bmad-help 会解释推荐的下一步，但它只是只读模型帮助入口。它不会激活编排中枢，不会替代活动需求记录，不会替代 currentMentalModel，也不会满足受控门禁证据。

激活后，编排中枢获得当前请求的根治理权限。它的第一责任不是立刻实现，而是检查活动需求、读取当前需求记录、判断当前心智模型、显示进度，并推荐下一步受控动作。

编排中枢负责这些判断：

| 判断项 | 编排中枢职责 | | ------------ | ------------------------------------------------------------------- | | 活动需求 | 从显式 ID 或运行时 requirement record 中解析当前需求。 | | 当前心智模型 | 读取 currentMentalModel，从受控阶段继续，而不是根据聊天历史猜测。 | | 进度 | 显示哪些内容已确认、被阻塞、缺失或已就绪。 | | 下一步 | 推荐确认、架构、就绪、派发、审计、重跑或交付收口。 | | 证据 | 暴露缺失的 Manifest、追溯、命令、产物、审计、评分或 closeout 证据。 |

CLI 可以用于安装校验、CI、调试、fallback 宿主和外部只读视图。只要宿主技能可用，它就不是日常主流程的激活方式。

正常操作应该保持简单：激活宿主技能，让编排中枢 inspect 当前活动需求，并按它返回的受控下一步执行。不要绕过 Implementation Readiness Gate 直接让实现 Agent 开工。不要用 dashboard green、score green、task done 或聊天信心来宣称交付。交付只能通过 Delivery Closeout Gate 和当前证据链关闭。

已接受的主 Agent 路径是 inspect -> dispatch-plan -> closeout：inspect 解析受控状态，dispatch-plan 生成有边界的子任务，closeout 在允许完成表述前验证交付证据。

常用技能与工作流选择

BMAD-Speckit-SDD-Flow 安装的是分层技能面。规范核心层 _bmad/skills 包含 29 个共享技能。安装到具体宿主时，还会展开 BMAD workflow、agent、core task 和宿主专用 overlay 技能。当前按宿主展开后的技能面为：Codex 70 个，Claude Code 72 个，Cursor 72 个；跨所有支持宿主去重后共有 72 个技能名。

| 范围 | 数量 | 含义 | | ---------------------- | ---- | --------------------------------- | | 规范共享核心层 | 29 | _bmad/skills 中的规范共享技能。 | | Codex 展开技能面 | 70 | 安装到 Codex 后可见的技能。 | | Claude Code 展开技能面 | 72 | 安装到 Claude Code 后可见的技能。 | | Cursor 展开技能面 | 72 | 安装到 Cursor 后可见的技能。 | | 跨宿主去重技能名 | 72 | 所有支持宿主合并后的唯一技能名。 |

使用 $bmads / $bmad-speckit 作为正常的受治理运行时入口。需要理解 BMAD 1.x 工作流地图或 2.x 受治理运行时投影时，使用 $bmad-help 作为状态感知导航器。$bmad-help 是只读导航面：它不会推进心智模型，不会执行 remediation，也不会替代活动需求记录或受控门禁。

| 技能 | 使用场景 | 主要产出 | 控制角色 | | -------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------- | | $bmads / $bmad-speckit | 需要在 Codex、Claude Code 或 Cursor 中进入受治理运行时。 | 当前需求状态、下一步受控动作和证据缺口。 | 当前活动需求的根 Orchestrator Agent 入口。 | | $bmad-help | 需要 BMAD 工作流地图，或不确定下一步该运行什么。 | 推荐路径、阻塞路径或 rerouteRequired 路径。 | 只读模型导航器，不推进心智模型。 | | $requirements-contract-authoring | 需要创建或更新可确认的 PRD、BUGFIX、TASKS 或 story 源文档。 | 内联 implementationConfirmation、traceRows、证据期望和确认 HTML。 | 为用户确认准备源文档，不是独立权威。 | | $req-trace-matrix-prompt-generator | 需要从需求源生成严格的 trace matrix prompt。 | 可用于提示词的需求追溯矩阵合同。 | 生成追溯编写输入，不关闭运行时门禁。 | | $goal-execution-contract-generator | 需要为 /goal 生成冻结执行合同。 | docs/plans 下的 goal 执行合同。 | 为 /goal 生成合同，但不执行 /goal。 | | $grill-with-docs | 需要基于现有文档做对抗式澄清。 | 追问、矛盾点和证据缺口。 | 在确认或执行前提高需求清晰度。 | | $docs-review | 需要检查 README、文档或 diff 的清晰度、结构和风格。 | 文档审查 findings。 | 可选伴随技能；除非另行加入，否则不是项目安装面的一部分。 | | $bmad-create-product-brief | 需要在 PRD 前梳理产品意图。 | Product brief 与发现记录。 | 进入 2.x 控制面的 1.x 上游工作流输入。 | | $bmad-create-prd | 需要结构化产品需求文档。 | 包含目标、范围和验收方向的 PRD。 | 输入需求契约的 1.x 上游需求产物。 | | $bmad-create-architecture | 需要架构边界和技术决策。 | 架构文档和风险决策。 | 后续确认可使用的 1.x 上游架构产物。 | | $bmad-create-epics-and-stories | 需要把产品和架构范围拆成可执行交付切片。 | Epic、story 和 story context。 | 可成为受控实现输入的 1.x 规划产物。 | | $bmad-check-implementation-readiness | 需要检查 PRD、UX、Architecture 和 story 是否就绪。 | readiness findings 和缺失前置条件。 | 控制面前的就绪辅助；最终仍由运行时门禁决定。 | | $bmad-story-assistant | 需要受支持的 story 执行路径。 | story 执行辅助和 story 状态指导。 | 官方 story 路径，优先于只依赖 legacy dev-story。 | | $bmad-standalone-tasks | 需要执行独立任务文档。 | 任务执行结果和证据。 | 任务级辅助，仍必须遵守活动需求门禁。 | | $bmad-bug-assistant | 需要带根因分析和修复计划的 bugfix 流程。 | bug 报告分析、修复计划和验证方向。 | 可进入需求确认的 bugfix 准备路径。 |

1.x 五层架构

1.x 发布线仍然是连接 BMAD 产品发现与 Speckit 技术实现的交付地图。它也是解释“产品意图如何变成可审计、可评审交付”的最直观入口。

| 层级 | 目的 | 主要产出 | | --------------------------------- | ----------------------------------------------------------------- | ------------------------------------------ | | Layer 1: Product Brief | 定义产品意图、用户、目标和问题框架。 | Product brief 与发现记录。 | | Layer 2: PRD + Architecture | 将意图转成需求、架构边界和风险决策。 | PRD 与架构文档。 | | Layer 3: Epic / Story | 将产品和架构范围拆成可执行 story 单元。 | Epic、Story 与 Story 上下文。 | | Layer 4: Speckit Workflow | 按 specify -> plan -> GAPS -> tasks -> implement 推进技术执行。 | spec、plan、gap 分析、tasks、代码和测试。 | | Layer 5: Closeout And Integration | 审计实现、评分证据，并准备可评审交付。 | post-audit、评分、PR、人工评审和发布证据。 |

在 2.x 发布线中，五层架构没有被移除。它成为 AI-TDD 控制面的上游交付地图：产品和 Story 产物会进入需求契约输入，Speckit 工作会成为 bounded execution packet，最终交付仍然只能通过受控证据门禁关闭。

AI-TDD 控制面

本项目中的 AI-TDD 指 Manifest 级的验收驱动开发。Manifest 不是测试清单，而是需求契约矩阵：它把 MUST、NEG（MUST NOT 负向断言）、OUT（OUT OF SCOPE 范围边界）、TRACE、EVD、ACC/E2E、FAIL/EDGE、CMD、ART、TASK、测试、产物、Gate Verdict 和 Human-in-the-loop 决策绑定到同一个验收面。MUST NOT 是 NEG-* 的概念别名；旧 NOT DONE 语义应迁移为 OUT OF SCOPE / OUT-*。

控制面要执行两条规则：

| 规则 | 门禁 | | ----------------------------------- | ------------------------------------------------------ | | Manifest 不完整，不允许进入执行。 | Implementation Readiness Gate，目标状态 AI-TDD-RED。 | | Manifest 仍有未验证项，不允许交付。 | Delivery Closeout Gate，目标状态 AI-TDD-GREEN。 |

readiness gate 不表示功能已经完成。它表示需求契约足够完整、验收基线已经建立，允许从 AI-TDD-RED 开始实现。delivery closeout gate 表示 Manifest 关联的验收项和证据链都已验证，才允许说交付完成。

六心智模型

编排中枢用六个心智模型推进每个需求。它们不是看板标签，而是决定下一步应该确认、架构、准入、执行、审计还是交付收口的治理问题。

| 心智模型 | 治理问题 | 目标结果 | | ------------------------- | -------------------------------------------------------------- | ----------------------------- | | Requirement Confirmation | 做什么、不做什么、哪些证据 ID 可以证明闭合？ | 需求契约已确认。 | | Architecture Confirmation | 实现边界是否仍符合已确认架构和风险范围？ | 架构边界已确认。 | | Implementation Readiness | Manifest 是否足够完整，验收基线是否已注册？ | 准入门禁达到 AI-TDD-RED。 | | Execution Closure | 有界 Agent 是否只在契约内实现，并产生可追溯证据？ | 执行在 Manifest 约束内闭合。 | | Audit Review | finding、rerun、RCA、score 和审计证据是否有可验证 provenance？ | 审计证据当前且可复核。 | | Delivery Confirmation | 当前 closeout attempt 的验收项和交付证据是否全部通过？ | 交付门禁达到 AI-TDD-GREEN。 |

实现 Agent 不能选择全局路线。只有 readiness 通过后，它们才接收 bounded packet；每次子结果、审计结果、重跑或阻塞事件之后，编排中枢都必须重新 inspect 再决定下一条全局分支。

Manifest 契约与证据链

Manifest 是 AI-TDD 契约的事实源。它更接近 contract-as-code，而不是普通自然语言需求文档：它编码“必须做什么”“不能做什么”“哪些内容不在范围内”“每个切片如何追溯”以及“哪些证据可以证明交付”。

每个有意义的交付声明，都应该能在需求、追溯、证据、命令、产物、裁决和人工决策维度上回放。

| 维度 | 必要证明 | 收口含义 | | ---- | ---------------------------------------------------------- | ---------------------------------------- | | 需求 | 已确认的 MUST、NEG 和 OUT Manifest rows。 | 验收目标明确且已版本化。 | | 追溯 | TRACE rows 绑定需求、任务、测试、命令、产物和审计。 | 每个声明都有可回放的契约切片。 | | 证据 | EVD 记录标识每个 trace row 需要的证明。 | 门禁知道必须存在什么证据。 | | 命令 | CMD 记录证明当前 attempt 运行了已注册检查。 | 旧命令输出或无关命令输出不能关闭交付。 | | 产物 | ART 记录报告、receipt、hash、snapshot 或审计输出。 | 结果在聊天会话结束后仍可复核。 | | 决策 | 当前 attempt 记录 Gate Verdict 和 Human-in-the-loop 决策。 | 只有机器门禁和人工决策都闭合后才能交付。 |

当 Manifest 完备性、trace 覆盖、命令证据、产物证据、审计 provenance 或 closeout 证据缺失时，编排中枢应该阻塞、重路由或要求补证，而不是继续实现或直接交付。

CLI 安装与外部接口

使用已发布 npm 包把工作流安装到消费项目。为了让生成后的 skills 稳定运行，应把包安装为项目本地依赖，并通过 npx --no-install 调用 CLI。

npm install --save-dev --ignore-scripts bmad-speckit-sdd-flow@latest
npm ls bmad-speckit-sdd-flow --depth=0
npx --no-install bmad-speckit version
npx --no-install bmad-speckit --help
npx --no-install bmad-speckit init . --ai codex --yes --force
npx --no-install bmad-speckit check
npx --no-install bmad-speckit dashboard-status
npx --no-install bmad-speckit bmads

默认建议带 --ignore-scripts：先把包安装进项目，再显式运行 bmad-speckit init ... 生成目标宿主安装面。如果不带该参数，当前根包的 postinstall 会执行 scripts/init-to-root.js，可能通过默认安装流程写入 _bmad、宿主目录、hooks、skills、配置或状态文件。

Windows 下如果当前 shell 不能解析 shim，可改用 npx.cmd：

npx.cmd --no-install bmad-speckit bmads

公开 CLI 暴露这些辅助接口：

| 接口面 | 命令 | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | 安装与生命周期 | init, check, version, upgrade, uninstall, add-agent。 | | 运行时只读视图 | bmads, bmad-speckit, dashboard-start, dashboard-status, dashboard-stop, dashboard-live, runtime-mcp。 | | 证据与评分 | score, check-score, scores, dashboard, deferred-gap-audit。 | | 数据与反馈 | coach, sft-extract, sft-preview, sft-validate, sft-bundle, feedback。 |

安装矩阵

| 安装方式 | 适用场景 | 会改动的项目文件 | 长期生成 skill 运行时 | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | npm install --save-dev --ignore-scripts bmad-speckit-sdd-flow@latest | 正常消费项目的默认方式。 | 写入 node_modules、package.json 和 lockfile；跳过包生命周期脚本。 | 支持。安装后显式执行 npx --no-install bmad-speckit init ...，生成后的 skills 可调用 npx --no-install bmad-speckit ...。 | | npm install --save-dev bmad-speckit-sdd-flow@latest | 你明确接受 package postinstall 副作用时的便利安装。 | 写入 node_modules、package.json 和 lockfile；当前 postinstall 还可能通过 scripts/init-to-root.js 写入默认安装面。 | 只有在校验本地 shim 并重新显式执行目标宿主的 bmad-speckit init ... 后，才应视为长期可用。 | | npm install --save-dev --ignore-scripts ./bmad-speckit-sdd-flow-<version>.tgz | 在真实消费项目中验证 CI artifact 或 release candidate。 | 写入 node_modules、package.json 和 lockfile；跳过包生命周期脚本。 | 支持，运行时固定到该 tarball 内容；安装后仍应显式 init。 | | npm install --no-save --package-lock=false --ignore-scripts ./bmad-speckit-sdd-flow-<version>.tgz | 临时本地 artifact smoke test。 | 写入 node_modules；原则上不更新 package.json 和 lockfile。 | 仅临时支持。只要 node_modules 还在就能运行，但这不是持久项目契约。 | | npx --yes --package bmad-speckit-sdd-flow@latest bmad-speckit ... | 一次性 CLI 执行、smoke test、CI artifact 检查。 | 不会持久安装项目本地 runtime 依赖。 | 不支持长期 skills。后续生成的 skills 可能因为 npx --no-install 找不到本地包而失败。 | | 全局安装 | 受治理项目外的人工操作便利。 | 不会把 runtime 版本固定到消费项目。 | 不建议用于项目 skills，因为项目无法控制 runtime 版本。如果只跑 npx --no-install 做校验，它还可能掩盖本地依赖缺失。 |

稳定的生成 skill 运行时契约是：通过项目本地安装的公开包 CLI 执行 npx --no-install bmad-speckit ...，而不是调用仓库源码路径。新增或已迁移的 skills 不应把 node packages/bmad-speckit/bin/bmad-speckit.js、scripts/*.ts、tsx 或 ts-node 写成消费者 runtime 命令。如果遗留 skill 文本里仍出现 root script 命令，应视为迁移债务，而不是推荐的消费者 runtime。

bmad-speckit-init 仍保留为兼容别名。新的 README 示例、生成后的 skills 和集成脚本应优先使用 bmad-speckit init ...。

公开 CLI 命令面

下面的截图展示已发布 npm 包暴露的 CLI 命令面。它用于快速理解安装、生命周期、运行时只读视图、评分、Coach 和 SFT 工具入口；它不是用户日常的编排中枢工作流。

安装校验

建议为消费项目保留这些安装校验命令。检查生成文件前，先按目标宿主执行对应的 init 行：

npm ls bmad-speckit-sdd-flow --depth=0
npx --no-install bmad-speckit version
npx --no-install bmad-speckit init . --ai codex --yes --force
npx --no-install bmad-speckit check
npx --no-install bmad-speckit dashboard-status
npx --no-install bmad-speckit bmads

不要把单独运行 npx --no-install 当成本地 runtime 存在的证明。必须先确认项目依赖和本地 shim 都存在，避免全局可执行文件掩盖缺失或未固定版本的项目安装。

如果你用 --ai claude,cursor-agent,codex 初始化所有常用宿主，还要检查这些目标安装面：

node -e "const fs=require('node:fs'); const paths=['_bmad-output/config/bmad-speckit-install-manifest.json','.codex/skills','.claude/hooks/runtime-policy-inject.cjs','.claude/hooks/pre-continue-check.cjs','.cursor/hooks/runtime-policy-inject.cjs','.cursor/hooks/pre-continue-check.cjs']; for (const p of paths){ if(!fs.existsSync(p)){ console.error('missing '+p); process.exit(1); } console.log('found '+p); }"

CLI 用来安装和查看；宿主技能用来让编排中枢接管需求流。

交付收口证据

交付收口证据不同于 CLI 命令面截图。它是按 attempt 归属的门禁材料，用于判断当前需求是否可以通过 Delivery Closeout Gate 收口。

| 证据类型 | 必要证明 | 门禁影响 | | -------- | ---------------------------------------------------------------- | ------------------------------------------------- | | 需求契约 | 已确认的 Manifest、requirement record 和 Manifest/source hash。 | 定义后续所有证据必须满足的契约。 | | 准入 | AI-TDD-RED 状态的 Implementation Readiness Gate 结果。 | 允许有界实现开始。 | | 执行 | Bounded packet 结果、命令证据、产物索引与 trace closure。 | 证明实现没有越过契约边界。 | | 审计 | Findings、rerun、RCA、score record、范围检查与 provenance。 | 识别漂移、陈旧证据和未评审风险。 | | 交付 | TRACE/EVD/CMD/ART 闭合、Gate Verdict 和 Human-in-the-loop 决策。 | 允许当前 attempt 进入 AI-TDD-GREEN 和完成表述。 |

发布线兼容说明

1.x 发布线的 BMAD + Speckit 资产仍然是兼容面：Product Brief、PRD、Architecture、Epic/Story、Speckit specify/plan/GAPS/tasks、实现、审计、评分、看板、Coach 和 SFT extraction 仍然有用。

2.x 发布线现在会先把五层架构作为 1.x 交付地图呈现，再引出 AI-TDD。它的主权威仍然是 AI-TDD 工具链生态和这套控制面。1.x 产物是控制面里的输入和投影，而不是需求契约权威的替代品。

仓库结构

这里描述的是 Git 跟踪的源码和发布结构。开发时可能出现 node_modules/、coverage/、test-results/、_bmad-output/、outputs/、reports/、tmp-*、.worktrees/、宿主缓存目录等本地或生成产物，但它们不是源码模块。

BMAD-Speckit-SDD-Flow/
├── _bmad/                 # 安装到消费项目的规范工作流资产
├── bin/                   # 根发布包的 bin wrapper
├── docs/                  # 用户文档、参考文档、运维说明和证据资产
├── packages/              # npm workspace 包
│   ├── bmad-speckit/      # 根包内打包的内部 CLI workspace
│   ├── ralph-method/      # Speckit 实现阶段的任务级 TDD 证据追踪器
│   ├── runtime-context/   # runtime context registry 与 ensure-run 工具
│   ├── runtime-emit/      # 预打包的 runtime policy / audit emit 工具
│   ├── schema/            # 共享 schema 资产
│   └── scoring/           # 评分、看板、Coach 和 SFT 工具
├── scripts/               # 安装器、CLI 入口、门禁、发布和测试工具
├── specs/                 # Epic/story specs、审计和受治理交付证据
├── src/                   # 宿主与 story 验证流程使用的共享源码辅助模块
├── templates/             # 面向消费项目的模板，例如 MCP 配置
├── tests/                 # 验收、集成、单元、fixture 和宿主一致性测试
└── website/               # 文档站点源码

根 npm 包的实际发布内容由 package.json#files 组装。它不会发布所有本地开发目录，而是发布 _bmad/、bin/、scripts/、部分 docs/assets、scoring、runtime-context 片段和选定验收 fixture 等安装与运行时表面。

文档入口

• 快速开始
• 编排中枢参考
• 消费项目安装指南
• 运行时看板指南
• 运行时 MCP 安装
• Provider 配置
• Cursor 配置
• Claude Code 配置
• Codex 配置
• 本地运行测试

开发与贡献策略

这是一个以个人工作流为主的项目。我把它开源，是因为这套流程可能对其他人有参考价值，但我无法承诺固定节奏地处理 issue、功能请求或 PR。

欢迎提交 bug 反馈、文档修正和小范围兼容性改进。对于较大的功能、架构调整，或不符合我当前使用方向的工作流，更建议 fork 后基于自己的场景做二次开发。

如果你仍希望向上游贡献：

• 阅读 CONTRIBUTING.md，了解本地环境、分支规范、测试和 PR 要求。
• 阅读 CODE_OF_CONDUCT.md，了解社区行为规范。
• 阅读 docs/how-to/run-tests-locally.md，了解本地验证流程。

常用本地验证命令：

npm install
npm test
npm run lint
npm run format:check

对仓库维护者来说，内部 workspace CLI 实现在 packages/bmad-speckit/README.md。消费项目用户仍应以本 README 里的根包契约为准。

许可证

本项目基于 MIT License 发布。