doc-spec-autopilot

doc-spec-autopilot

用途

自动化的 SPEC 生成流水线。从上游 BDD/ADR 文档、用户提示词或实现计划（IPLAN-*）中分析来源，生成完整的组件 SPEC，验证是否已满足就绪条件，维护 SPEC-00_index.md，并推动审计↔修复循环直至评分达标——适用于单个 SPEC 或批量处理。

层级：6。上游：BDD/ADR（以及 EARS/PRD/BRD 链），或提示词/IPLAN 输入。下游：经过验证的 SPEC + 索引条目。

技能依赖

技能	作用
../doc-spec/SKILL.md	SPEC 结构和编写规则（生成）
../doc-spec-audit/SKILL.md	质量门禁（评分 + 问题发现）
../doc-spec-fixer/SKILL.md	根据审计报告应用修复
../doc-naming/SKILL.md	ID 标准（短横线格式 SPEC-NN）

输入约定

接受：目标 SPEC ID/路径；上游 BDD/ADR ID 或路径；自由文本提示词；或 IPLAN 路径。可选项：评分阈值（默认值为 90）、最大修复迭代次数（默认值为 3）、批处理列表。如果没有明确输入，则将请求视为提示词。

智能文档检测

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

• 缺失 → 生成模式（根据 BDD/ADR、提示词或 IPLAN 生成）。
• 已存在 → 审查并修复模式（先审计，低于阈值时再修复）。

SPEC-NN 输入视为自身类型（审查）。BDD-NN/ADR-NN 输入视为上游来源：如果匹配的 SPEC 缺失，则生成；否则进行审查。

模型预检

仅供参考，尽力而为。显示为此层推荐的模型；无法切换会话模型。调用驱动程序前：

1. 如果 .claude/aidoc-flow.config.yaml 不存在，或没有 model.* 键，则完全跳过本节（不输出任何内容）。
2. 确定推荐模型：优先使用 model.per_layer.SPEC（如果已设置），否则使用 model.default。
3. 根据 model.precheck（warn | silent | block）采取相应操作：
   • warn（默认值）——打印一行，然后继续调用驱动程序： ℹ SPEC 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 — 调用驱动器。到此为止。 在调用此 SKILL 之前，harness 会设置 PREV_OUTPUT、 ARTIFACT_ID、ARTIFACT_PATH 环境变量。 你的第一个编排操作必须是 Bash 工具（先运行上文的 Model 预检查），并且必须准确运行：

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

--allow-skip-permissions 允许驱动器分派的各阶段无需权限提示即可写入 文件——无人值守自动运行必须使用此选项。 移除此标志即可使用 Claude Code 的常规提示运行相同循环。

设置充足的超时时间（≥1800s）。不要预先分析输入。不要 读取上游内容。不要判断类型／范围。驱动器及其 分派的子进程（草稿阶段使用 /aidoc-flow:doc-spec， 审核阶段使用 /aidoc-flow:doc-spec-audit，修复阶段使用 /aidoc-flow:doc-spec-fixer） 会处理所有这些工作。驱动器会根据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md 抢先执行状态机； 此 SKILL 的任务是调用驱动器并汇报结果。

步骤 2 — 驱动器返回后，进行汇报。 读取 .aidoc/review/06_SPEC/${ARTIFACT_ID}/saga.json。最终状态必须 是 CLOSED（通过）、ESCALATED（终止失败）或 PARTIAL_TIMEOUT（软截止时间；可恢复）。输出状态、 verdict.json 中的最终分数（如果存在）以及 1 行摘要。

步骤 3 — 更新索引（仅限 CLOSED）。 在 docs/06_SPEC/SPEC-00_index.md 中添加一行，引用新 SPEC；更新上游制品的 下游条目。

以上就是 team 模式的全部工作流。如果你发现自己在此执行任何其他操作——撰写 文案、分派 Task 子代理、调用其他斜杠命令——请停止，意识到你正在 绕过驱动器，并改为调用上面的 Bash 命令。

线性流水线（review_mode: single_pass）

未更改的旧版行为——当配置文件指定此模式、Task 子代理分派不可用，或在写入时（on_author）成本是首要考虑因素时使用。以下 5 步会话内模式生成 SPEC，但不会生成 saga.json；harness 的 saga 日志检查 会因此导致该层失败，所以此模式仅适用于手动试运行。

1. 输入分析 — 判断输入类型（BDD／ADR／提示词／IPLAN），定位 上游材料，并决定是生成还是审核并修复。
2. 上游就绪检查 — 确认上游 ADR／BDD 已存在且已就绪； 预留下一个 SPEC-NN。
3. 生成 — 按照 ../doc-spec/SKILL.md 生成 SPEC：首先编写文档控制 信息，使用 YAML 编写全部 8 个章节，接口／数据模型／行为达到 C4-L3， 使用累积标签（@brd @prd @ears @bdd @adr），对数字使用 @threshold 引用，下游 @tdd: TDD-NN 契约，以及通过 ../charts-flow/SKILL.md 添加图表标签。
4. 验证 — 从头运行 ../doc-spec-audit/SKILL.md。
5. 审核 ↔ 修复循环 — 当分数低于阈值且迭代次数少于上限时：运行 ../doc-spec-fixer/SKILL.md，然后重新审核。通过后，更新 docs/06_SPEC/SPEC-00_index.md；迭代次数达到上限后，标记为需人工 审核。

执行模式

• 单项 — 一个 SPEC（生成或审核并修复）。
• 批量 — 多个 SPEC，按每批 3 个处理，以限制上下文。
• 试运行 — 报告计划执行的操作（章节、ID、上游标签）， 不写入文件。

质量门禁

• 审核通过（TDD 就绪度分数 ≥ 阈值且 Tier-1 错误数为 0）或达到迭代上限（随后：标记为需人工审核） 后，才算完成生成。
• 仅在 SPEC 通过后更新 SPEC 索引。
• 每个循环都进行全新审核——不使用缓存分数。

错误处理

情况	操作
引用的上游 ADR／BDD 缺失	停止；报告缺失的依赖项
达到最大迭代次数，但分数仍低于阈值	写入报告，标记为需人工审核，然后继续处理批次
源输入含义不明确	回退到提示词模式；在 SPEC 中记录假设
写入／权限错误	记录日志，跳过此项，继续处理批次

适配

应用默认值之前，请先读取项目适配配置文件 （.aidoc/profile.yaml），并在生成阶段和内部 审计/修复阶段应用该配置。遵循 section_toggles、active_layers、 audit_threshold（仅可调高，即只能变得更严格）和 glossary。忽略任何未知或 超出适用范围的键；如果没有配置文件，则使用框架默认值。 权威来源：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

• 创建：../doc-spec/SKILL.md · 审计：../doc-spec-audit/SKILL.md · 修复： ../doc-spec-fixer/SKILL.md
• 权威来源：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-00_index.TEMPLATE.md