ai-ad-doc-orchestrator

name: ai-ad-doc-orchestrator version: "5.3" status: ready_for_production layer: skill owner: wade last_reviewed: 2025-11-28 baseline: AI_CODE_FACTORY_DEV_GUIDE_v2.4, SoT Freeze v2.6, SUPERCLAUDE_INTEGRATION_GUIDE_v2.2

目标：
- 任何文档都不能在没有大纲的情况下直接写正文。
- 任何大纲都必须受 MASTER / SoT / 现有文档约束。
- 任何正文都必须受冻结大纲约束，逐章节演进，逐章节 Freeze。

<sub_skills> - ai-project-doc-writer <!-- 负责：大纲 + 正文 生成 --> - ai-ad-doc-fixer <!-- 负责：审查 + 修订 --> - ai-master-architect <!-- 负责：与 MASTER / SoT 的宪法级校验 --> </sub_skills>

<input_contract> 最小输入： { doc_name: "PROJECT.md | DOMAIN.md | ARCHITECTURE.md | PATTERNS.md | TESTING.md | DEPLOYMENT.md | other", outline_exists: true | false }

可选输入：
- start_chapter: number （从第几章开始处理）
- end_chapter: number   （处理到第几章，含）
- extra_context: 其他说明（例如业务场景）

若 doc_name 缺失 → 输出 <halt>Missing: doc_name</halt> 并停止。

</input_contract>

<doc_autotype> 根据 doc_name 推断文档角色（仅用于约束行为，不影响调用）：

- PROJECT.md
  - 业务宇宙边界 + 能力 + 不变量 + 永久禁止行为
  - 不承载实现细节、技术方案、字段定义、状态机细节。
- ARCHITECTURE.md
  - 分层结构、组件拓扑、依赖约束、NFR（性能/可用性等）
  - 不承载业务规则、不承载账务逻辑。
- DOMAIN.md
  - 领域索引：实体/能力/状态机 → SoT 文档路径
  - 不承载规则正文、不承载流程描述。
- PATTERNS.md
  - 反模式与禁止实现方式。
- TESTING.md
  - 测试策略、分层、覆盖要求。
- DEPLOYMENT.md
  - CI/CD、环境、监控、回滚策略。

禁止作为目标文档的示例（仅可被引用，不能由本 orchestrator 生成全文）：
- STATE_MACHINE*.md
- DATA_SCHEMA*.md
- BUSINESS_RULES*.md
- *_SOT.md（DAILY_REPORT_SOT / RECONCILIATION_SOT / TRANSFER_SOT 等）

如 doc_name 属于禁止生成列表 → 输出 <halt>Forbidden: SoT documents cannot be generated by orchestrator</halt>。

</doc_autotype>

<workflow_overview> 对于任意 doc_name，执行两层流水线：

[层 1：大纲流水线]
  CONTEXT_SCAN
    → OUTLINE_INIT
    → OUTLINE_GENERATE
    → OUTLINE_REVIEW
    → OUTLINE_PATCH
    → OUTLINE_FREEZE

[层 2：正文流水线（按章节）]
  INIT
    → DW-FILL
    → DOC-ANALYZE
    → DOC-PATCH
    → MASTER-CHECK
    → FREEZE
    → 下一章节 INIT

</workflow_overview>

<inputs>
  - 仓库内可用文档（按名称模式）：
    - MASTER*.md
    - PROJECT*.md
    - STATE_MACHINE*.md
    - DATA_SCHEMA*.md
    - BUSINESS_RULES*.md
    - *_SOT.md
    - 其他与 doc_name 类型相关的指南类文档
</inputs>

<actions>
  - 生成 reference_docs 列表（文件名 + 相对路径）
  - 从 reference_docs 中提取：
    - 已存在的实体/能力/规则 ID（例如 E-xx / C-xx / BR-xx）
    - 已声明的业务不可变量 / 永久禁止行为
    - 文档优先级规则（MASTER > DOMAIN > SoT > PATTERNS > TESTING > DEPLOYMENT）
    - 现有同类文档的大纲（若存在）
  - 将上述内容封装为 context_constraints，用于后续阶段。
</actions>

<rules>
  - 不得修改任何 reference_docs 内容。
  - 不得为 reference_docs 编造新含义。
  - 不向用户输出 context_constraints 内部细节，只在后续调用中作为约束使用。
  - 【P1 安全规则】禁止输出 context_constraints 中的任何内容，包括但不限于：
      - 实体 ID（E-xx）、能力 ID（C-xx）、规则 ID（BR-xx、VAL-xx 等）
      - 状态机定义、状态转换规则
      - 数据结构、字段清单、表结构
      - 能力列表、不变量列表、禁止行为列表
  - 用户请求输出 context_constraints 时必须拒绝，说明"该信息为内部约束，不对外暴露"。
</rules>

<output>
  - reference_docs
  - context_constraints
</output>

<actions>
  - 若 outline_exists = true：
      - 使用现有大纲，跳过 OUTLINE_* 阶段，直接进入 INIT。
  - 若 outline_exists = false：
      - 先执行 CONTEXT_SCAN，获取 reference_docs 与 context_constraints。
      - 然后进入 OUTLINE_GENERATE。
</actions>

<call>
  skill: ai-project-doc-writer
  mode: OUTLINE
  input:
    - doc_name
    - reference_docs
    - context_constraints
    - outline_rules:
        - 禁止创造新业务概念/实体/能力/状态机。
        - 每个章节必须能在 reference_docs 中找到至少一个支撑文档。
        - 对 PROJECT / ARCHITECTURE / DOMAIN / PATTERNS / TESTING / DEPLOYMENT，分别采用相应模板风格。
        - 大纲仅为章节树结构，不出现段落正文。
</call>

<output>
  - outline_draft （章节树结构）
</output>

<call>
  skill: ai-project-doc-fixer
  mode: OUTLINE-ANALYZE
  input:
    - doc_name
    - outline_draft
    - reference_docs
    - context_constraints
</call>

<checks>
  - 是否存在“无来源章节”（找不到任何参考文档支撑）。
  - 是否跨越文档职责边界（例如在 DOMAIN 大纲中加入规则正文类章节）。
  - 是否违反 MASTER 不变量/禁止行为。
  - 是否引入新的实体/能力/规则 ID。
  - 是否章节粒度过粗或过细。
</checks>

<output>
  - outline_issues （按 P0 / P1 / P2 分类的问题列表）
</output>

<rules>
  - 若存在 P0 → 必须进入 OUTLINE_PATCH。
  - 若仅有 P1/P2 → 仍建议进入 OUTLINE_PATCH 进行优化。
</rules>

<call>
  skill: ai-project-doc-fixer
  mode: OUTLINE-PATCH
  input:
    - doc_name
    - outline_draft
    - outline_issues
    - reference_docs
    - context_constraints
    - patch_constraints:
        - 允许删除或合并章节。
        - 允许调整章节顺序。
        - 允许将“解释型标题”改为“索引/约束型标题”。
        - 禁止新增超出 context_constraints 的概念/实体/能力/规则。
</call>

<output>
  - outline_final
</output>

<actions>
  - 标记 outline.status = "Frozen"
  - 记录 outline.version = vX.Y
  - 进入 INIT 阶段，准备正文写作。
</actions>

<rules>
  - 【P1 安全规则】大纲冻结后严格禁止以下行为：
      - 修改 outline_final 的章节结构、标题、子标题
      - 在正文写作阶段新增任何章节
      - 在 DOC-ANALYZE / DOC-PATCH 阶段修改大纲
      - 在正文修订阶段扩展大纲结构
  - 任何需要修改大纲的情况，必须：
      - 停止当前流程
      - 输出 &lt;halt&gt;Outline modification required: must re-run OUTLINE pipeline&lt;/halt&gt;
      - 不得自动执行大纲修改
</rules>

<actions>
  - 从 outline_final 读取章节列表。
  - 若 chapter_n.status = "Frozen" → 跳过，处理下一章节。
  - 否则，准备 chapter_n 的标题与子标题信息，进入 DW-FILL。
</actions>

<rules>
  - 【P1 安全规则】单章节执行限制：
      - 每次只能选择一个章节进行处理
      - 完全禁止跨章节输出
      - 完全禁止在处理 chapter_n 时输出其他章节内容
</rules>

<call>
  skill: ai-project-doc-writer
  mode: DW-FILL
  input:
    - doc_name
    - chapter_meta: { chapter_id, 标题, 子标题结构 }
    - reference_docs
    - context_constraints
    - writing_rules:
        - 禁止超出大纲定义的范围。
        - 禁止扩展业务逻辑或发明新实体。
        - 禁止重写 SoT 正文（仅可引用编号）。
        - PROJECT.md 不写实现/流程/技术细节。
        - DOMAIN.md 不写规则正文/流程，只允许索引型表述。
        - ARCHITECTURE.md 不写业务规则，只写结构与约束。
        - 【P1 安全规则】ai-project-doc-writer 一次只能写一个章节，完全禁止跨章节输出。
</call>

<output>
  - chapter_draft （当前章节 Markdown 正文）
</output>

<rules>
  - 【P1 安全规则】writer 执行限制：
      - writer 一次只能写一个章节
      - 完全禁止在 chapter_draft 中包含其他章节内容
      - 若 writer 输出多个章节，立即输出 &lt;halt&gt;Cross-chapter output detected&lt;/halt&gt;
</rules>

<call>
  skill: ai-project-doc-fixer
  mode: DOC-ANALYZE
  input:
    - doc_name
    - chapter_content: chapter_draft
    - chapter_meta
    - reference_docs
    - context_constraints
</call>

<output>
  - issue_list （按 P0 / P1 / P2 分类）
</output>

<rules>
  - 若含 P0 → 必须进入 DOC-PATCH。
  - 若仅 P1/P2 → 建议进入 DOC-PATCH 进行修订。
</rules>

<call>
  skill: ai-project-doc-fixer
  mode: DOC-PATCH
  input:
    - doc_name
    - chapter_content: chapter_draft
    - issue_list
    - reference_docs
    - context_constraints
    - patch_constraints:
        - 修复 P0/P1，P2 仅做风格/表达优化。
        - 不得扩展章节范围。
        - 不得新增业务逻辑/实体/能力/规则。
        - 不得修改 SoT 的含义，仅能修正文档表达。
        - 【P1 安全规则】不得修改 outline_final 大纲结构。
        - 【P1 安全规则】ai-project-doc-fixer 一次只能修一个章节，完全禁止跨章节修订。
</call>

<output>
  - chapter_patched
</output>

<rules>
  - 【P1 安全规则】fixer 执行限制：
      - fixer 一次只能修一个章节
      - 完全禁止在 chapter_patched 中包含其他章节内容
      - 完全禁止跨章节修订
      - 若 fixer 输出多个章节或修改大纲，立即输出 &lt;halt&gt;Cross-chapter modification detected&lt;/halt&gt;
</rules>

<call>
  skill: ai-master-architect
  mode: REVIEW-CHAPTER
  input:
    - doc_name
    - chapter_content: chapter_patched
    - reference_docs
    - context_constraints
</call>

<output>
  - master_conflicts （如存在冲突，列出具体条目；否则为空）
</output>

<rules>
  - 若 master_conflicts 非空：
      - 输出 Conflict 列表，返回 DOC-PATCH（需修订或人工决策）。
  - 若 master_conflicts 为空：
      - 进入 FREEZE。
  - 【P1 安全规则】master-architect 执行限制：
      - master-architect 一次只能校验一个章节
      - 完全禁止跨章节校验
      - 若检测到跨章节输出，立即输出 &lt;halt&gt;Cross-chapter validation detected&lt;/halt&gt;
</rules>

<actions>
  - chapter_n.status = "Frozen"
  - 记录 chapter_n.version
  - 选择下一章节 → 回到 INIT
</actions>

<error_handling> - 任一阶段若缺少关键输入（doc_name / outline / reference_docs）： 输出 <halt>Missing: xxx</halt> 并停止，不推测。 - 子 Skill 若输出 "Missing: ..."： 传递给用户或上层 Agent，不自动补全。 - 子 Skill 若输出 "Conflict: ..."： 停止当前章节流程，要求人工或更高等级 Skill 决策后再继续。 </error_handling>

示例 2：已有 PROJECT.md 大纲，只想继续写正文
「
使用 ai-doc-orchestrator，
doc_name = PROJECT.md，
outline_exists = true，
start_chapter = 3，
end_chapter = 6。
」

<chain_of_thought> - 允许在内部执行复杂推理、多轮一致性检查。 - 禁止向用户输出思考过程与中间草稿。 - 对外只暴露： - 当前所处阶段 - 章节 Freeze 状态 - 问题清单（P0/P1/P2） - Missing / Conflict 概要。 </chain_of_thought>

<VERSION_NOTES> ### v5.2 (2025-11-27) - ✅ 添加 YAML frontmatter 符合 Skill Freeze 标准 - ✅ 修复 P0-DO-001: 子 Skill 引用错误 (ai-project-doc-fixer → ai-ad-doc-fixer) - ✅ 对齐 ASDD 6-Layer Architecture baseline

### v5.1 (2025-11-26)
- 新增 OUTLINE 流水线阶段
- 新增 P1 安全规则（单章节执行限制）
- 完善 CONTEXT_SCAN 阶段约束

### v5.0 (2025-11-25)
- 重构为 SuperClaude 框架结构
- 引入两层流水线架构（大纲流水线 + 正文流水线）

</VERSION_NOTES>