doc-bdd-autopilot

用途

doc-bdd-autopilot 是一条自动化 BDD 生成流水线。它从上游 EARS（docs/03_EARS/）、用户提示词或实现计划（IPLAN-*）出发，分析来源，生成完整的 Given-When-Then 场景 BDD 套件，校验就绪状态，维护 BDD-00_index.md，并驱动审计↔修复循环，直到达到通过的 ADR-Ready 分数——可处理单个 BDD 或批量。

层级：第 4 层。上游：EARS（带 BRD/PRD 追溯）/ 提示词 / IPLAN 输入。下游：经过校验的 BDD + 索引条目。

技能依赖

../doc-bdd/SKILL.md：BDD 结构、YAML 场景 schema 与编写规则（生成）
../doc-bdd-audit/SKILL.md：质量门（ADR-Ready 评分 + 发现项）
../doc-bdd-fixer/SKILL.md：根据审计报告应用修复
../doc-naming/SKILL.md：元素 ID 标准

输入契约

接受：目标 BDD id/路径；上游 EARS id/路径；自由文本提示词；或 IPLAN 路径。可选：分数阈值（默认 90）、最大修复迭代次数（默认 3）、批量列表。若无显式输入，则将请求视为提示词。

智能文档检测

对每个目标，检查 BDD 是否已存在（嵌套文件夹 docs/04_BDD/BDD-NN_{slug}/）：

缺失 → 生成模式（来自 EARS / 提示词 / IPLAN）。
已存在 → 审查与修复模式（审计，若低于阈值则修复）。

从继承的 PRD/BRD 链确定 deliverable_type（code/document/ux/risk/process）。生成前验证上游 EARS 存在。

模型预检

建议性、尽力而为。显示为此层推荐的模型；它无法切换会话模型。在调用驱动前：

若 .claude/aidoc-flow.config.yaml 不存在，或没有 model.* 键，则完全跳过此节（无输出）。
解析推荐模型：若设置了 model.per_layer.BDD 则用之，否则用 model.default。
根据 model.precheck（warn | silent | block）执行：
- warn（默认）——打印一行，然后继续到驱动： ℹ BDD recommends model '<rec>'. If you're not on it, run /model <rec> (or set model.precheck: silent to hide this).
- silent——不打印；继续。
- block——打印上述行并加上 precheck=block: confirm you want to draft on the current model, or run /model <rec> first.，然后等待用户确认再继续。

工作流

Saga 驱动的生成循环（review_mode: team）

步骤 1——调用驱动。就这么做。harness 在调用此 SKILL 前设置 PREV_OUTPUT、ARTIFACT_ID、ARTIFACT_PATH 环境变量。你的第一个编排动作必须是 Bash 工具（上述模型预检先运行），精确运行：

python3 "${CLAUDE_PLUGIN_ROOT}/tools/saga_driver.py" \
  --layer 04_BDD \
  --allow-skip-permissions

--allow-skip-permissions 让驱动派发的阶段无需权限提示即可写文件——无人值守自动驾驶需要它。去掉该标志则以 Claude Code 的正常提示运行同一循环。

使用宽松超时（≥1800s）。不要预先分析输入。不要读取上游。不要分类类型/范围。驱动及其派发的子进程（/aidoc-flow:doc-bdd 用于草稿，/aidoc-flow:doc-bdd-audit 用于审查，/aidoc-flow:doc-bdd-fixer 用于修复）处理所有这些。驱动按 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md 抢先执行状态机；此 SKILL 的职责是调用它并报告。

步骤 2——驱动返回后，报告。读取 .aidoc/review/04_BDD/${ARTIFACT_ID}/saga.json。最终状态必须是 CLOSED（PASS）、ESCALATED（终态 FAIL）或 PARTIAL_TIMEOUT（软截止；可恢复）之一。打印状态、若存在则打印 verdict.json 的最终分数，以及一行摘要。

步骤 3——索引更新（仅在 CLOSED 时）。向 docs/04_BDD/BDD-00_index.md 添加一行引用新 BDD；更新上游工件的下游条目。

这就是 team 模式下的整个工作流。若你发现自己在做其他任何事——起草文字、派发 Task 子代理、调用其他斜杠命令——停下，认识到你在绕过驱动，改为调用上述 Bash 命令。

线性流水线（review_mode: single_pass）

未变的遗留行为——当 profile 如此指定、Task 子代理派发不可用、或在写入时（on_author）成本是首要考虑时使用。以下 5 步会话内模式生成 BDD 但不产生 saga.json；harness 的 saga-journal 检查随后会使该层失败，因此此模式仅适用于手动试运行。

输入分析——分类输入（EARS / 提示词 / IPLAN），定位上游 EARS 及其 BRD/PRD 追溯元素，决定生成还是审查与修复。
类型与范围——确认引用的 EARS（及其 PRD/BRD 元素）存在；将 EARS 语句映射到场景类别；保留下一个 BDD-NN。
生成——按 ../doc-bdd/SKILL.md 生成 BDD：先是 Document Control，全部 5 个部分，一个 feature: 块，以及跨五个类别的 scenarios: YAML 列表——每个场景是一个映射，含 given/when/then 阶段列表、元素级 ears: 列表、id BDD.NN.03.xxxx、type/priority、内联 @threshold: 引用和 spec_trace。序列图通过 ../charts-flow/SKILL.md。
校验——从头运行 ../doc-bdd-audit/SKILL.md。
审计↔修复循环——当 score < threshold 且 iterations < max 时：运行 ../doc-bdd-fixer/SKILL.md，然后重新审计。通过时，更新 docs/04_BDD/BDD-00_index.md；迭代耗尽时，标记人工审查。

执行模式

单个——一个 BDD（生成或审查与修复）。
批量——多个 BDD，以 3 个为块处理以限制上下文；按上游 EARS 顺序生成。
试运行——报告计划动作（场景、类别、ID）而不写文件。

质量门

生成在审计通过（ADR-Ready ≥ 阈值，0 个 Tier-1 错误）或达到迭代上限（然后：人工审查标记）前不完成。
BDD 索引仅在 BDD 通过后更新。
每轮全新审计——无缓存分数。

错误处理

引用的上游 EARS/PRD/BRD 缺失：停止；报告缺失依赖。
达到最大迭代仍低于阈值：写报告，标记人工审查，继续批量。
来源输入不明确：回退到提示词模式；在 BDD 中记录假设。
写入/权限错误：记录，跳过该项，继续批量。

适配

在应用默认值前，读取项目适配 profile（.aidoc/profile.yaml）并在生成和内部审计/修复阶段都应用它。遵循 section_toggles、active_layers、audit_threshold（仅可提高——仅更严格）和 glossary。忽略任何未知或超出范围的键；无 profile 时，使用框架默认值。权威：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

技能介绍

用途