AI Ad Doc Orchestrator

<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 缺失 → 输出 <halt>Missing: doc_name</​halt> 并停止。

</​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 属于禁止生成列表 → 输出 <halt>Forbidden: SoT documents cannot be generated by orchestrator</​halt>。

</​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）： 输出 <halt>Missing: xxx</​halt> 并停止，不推测。 - 子 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>