034 Ai Ad Doc Orchestrator 8285582e

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

<skill>
──────────────────────────────────────────────
  <name>ai-ad-doc-orchestrator</name>
  <version>5.3</version>
  <domain>AI_AD_SYSTEM / ASDD 文档自动生成与审查工作流</domain>
  <profile>Workflow-Orchestrator / Multi-skill / Safe</profile>
──────────────────────────────────────────────


  <!-- ======================================================
       0. 核心使命（Mission）
  ====================================================== -->
  <mission>
    根据用户提供的 doc_name（例如 PROJECT.md / DOMAIN.md / ARCHITECTURE.md），
    自动执行“先读文档→生成大纲→审查大纲→修订大纲→冻结大纲→逐章写正文→逐章审查→逐章修订→逐章宪法校验→逐章冻结”的完整流水线。

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


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


  <!-- ======================================================
       2. 输入契约（Input Contract）
  ====================================================== -->
  <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 缺失 → 输出 &lt;halt&gt;Missing: doc_name&lt;/halt&gt; 并停止。
  </input_contract>


  <!-- ======================================================
       3. 文档类型自动识别（Autotype）
  ====================================================== -->
  <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 属于禁止生成列表 → 输出 &lt;halt&gt;Forbidden: SoT documents cannot be generated by orchestrator&lt;/halt&gt;。
  </doc_autotype>


  <!-- ======================================================
       4. 顶层状态机总览
  ====================================================== -->
  <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>


  <!-- ======================================================
       5. CONTEXT_SCAN：上下文扫描与约束提取
  ====================================================== -->
  <phase id="CONTEXT_SCAN">
    <description>
      在生成任何大纲之前，先扫描并读取现有 MASTER / SoT / 同类文档，
      提取“约束信息”，只读不写。
    </description>

    <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>
  </phase>


  <!-- ======================================================
       6. OUTLINE 阶段：大纲生成与冻结
  ====================================================== -->

  <!-- 6.1 OUTLINE_INIT -->
  <phase id="OUTLINE_INIT">
    <description>
      决定是否需要生成新的大纲，并确保已经执行 CONTEXT_SCAN。
    </description>

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


  <!-- 6.2 OUTLINE_GENERATE -->
  <phase id="OUTLINE_GENERATE">
    <description>
      使用 ai-project-doc-writer 基于 context_constraints 生成“受约束的大纲草稿”。
      大纲只定义章节结构与标题，不包含正文。
    </description>

    <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>
  </phase>


  <!-- 6.3 OUTLINE_REVIEW -->
  <phase id="OUTLINE_REVIEW">
    <description>
      使用 ai-project-doc-fixer 对 outline_draft 做结构审查，
      只输出问题，不改大纲内容。
    </description>

    <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>
  </phase>


  <!-- 6.4 OUTLINE_PATCH -->
  <phase id="OUTLINE_PATCH">
    <description>
      使用 ai-project-doc-fixer 基于 outline_issues 修订 outline_draft。
      只允许“收缩”和“重组”，禁止扩展业务范围。
    </description>

    <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>
  </phase>


  <!-- 6.5 OUTLINE_FREEZE -->
  <phase id="OUTLINE_FREEZE">
    <description>
      冻结大纲结构，后续正文写作必须严格遵守 outline_final，
      任何大纲修改需要重新运行 OUTLINE 流水线。
    </description>

    <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>
  </phase>


  <!-- ======================================================
       7. 正文流水线：INIT → DW-FILL → DOC-ANALYZE → DOC-PATCH → MASTER-CHECK → FREEZE
  ====================================================== -->

  <!-- 7.1 INIT：章节初始化 -->
  <phase id="INIT">
    <description>
      根据 outline_final 决定当前处理的章节 chapter_n，并检查是否已 Freeze。
    </description>

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

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


  <!-- 7.2 DW-FILL：调用 writer 写章节正文 -->
  <phase id="DW-FILL">
    <description>
      使用 ai-project-doc-writer 按章生成正文草稿。
      只针对当前章节，不跨章节输出。
    </description>

    <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>
  </phase>


  <!-- 7.3 DOC-ANALYZE：章节审查 -->
  <phase id="DOC-ANALYZE">
    <description>
      使用 ai-project-doc-fixer 对 chapter_draft 执行 DOC-ANALYZE，
      输出 P0/P1/P2 问题清单，不改正文。
    </description>

    <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>
  </phase>


  <!-- 7.4 DOC-PATCH：在边界内修订章节 -->
  <phase id="DOC-PATCH">
    <description>
      使用 ai-project-doc-fixer 基于 issue_list 修订 chapter_draft，
      生成 chapter_patched。修订仅限大纲范围内。
    </description>

    <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>
  </phase>


  <!-- 7.5 MASTER-CHECK：宪法级校验 -->
  <phase id="MASTER-CHECK">
    <description>
      使用 ai-master-architect 对 chapter_patched 做 MASTER / SoT 一致性校验。
    </description>

    <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>
  </phase>


  <!-- 7.6 FREEZE：章节冻结 -->
  <phase id="FREEZE">
    <description>
      将当前 chapter_patched 标记为 Frozen 版本，不再改动，并移动到下一章节。
    </description>

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


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


  <!-- ======================================================
       9. 外部调用示例
  ====================================================== -->
  <usage>
    示例 1：生成 PROJECT.md（从零开始）
    「
    使用 ai-doc-orchestrator，
    doc_name = PROJECT.md，
    outline_exists = false。
    从第1章开始按顺序执行，直到所有章节 Freeze。
    」

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


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


  <!-- ======================================================
       11. 版本记录
  ====================================================== -->
  <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>

</skill>