ai-ad-spec-kit

<skill>
<name>ai-ad-spec-kit</name>
<version>1.0</version>
<domain>AI_AD_SYSTEM / 规范驱动开发工具包</domain>
<profile>Spec-Driven / Multi-Phase / SoT-Aligned</profile>

<!-- ======================================================
     代码来源说明 (Source Attribution)
====================================================== -->
<source_attribution>
  本 Skill 借鉴自 GitHub 官方开源项目 Spec-Kit:
  - GitHub: https://github.com/github/spec-kit
  - License: MIT
  - 核心理念: 规范先行，代码后行

  适配改动:
  - 将 Constitution 概念对齐到 MASTER.md
  - 将 Specification 对齐到 SoT 文档体系
  - 添加 ASDD 4 层架构合规检查
  - 集成 OpenSpec 变更流程
</source_attribution>

<!-- ======================================================
     0. 核心使命 (Mission)
====================================================== -->
<mission>
  作为规范驱动开发的命令中心，提供从规范定义到代码实现的完整工作流。

  核心原则:
  - 📜 规范先行: 先写规范，再写代码
  - 🔗 SoT 对齐: 所有规范必须与 SoT 文档一致
  - 📝 任务分解: 大需求拆分为可验证的小任务
  - ✅ 持续验证: 每个阶段都有明确的验证点
</mission>

<!-- ======================================================
     1. 五阶段工作流 (5-Phase Workflow)
====================================================== -->
<workflow>
  <phase id="1-CONSTITUTION" command="/speckit.constitution">
    <description>
      定义或确认项目宪法级原则
      对应: MASTER.md + PROJECT_RULES.md
    </description>

    <actions>
      - 读取 docs/sot/MASTER.md
      - 读取 .claude/PROJECT_RULES.md
      - 确认业务边界和不变量
      - 确认永久禁止行为
      - 输出: constitution_context
    </actions>

    <output_format>
      ## 🏛️ Constitution 确认

      ### 业务边界
      - [从 MASTER.md 提取]

      ### 核心不变量
      - [从 PROJECT_RULES.md 提取]

      ### 禁止行为
      - [列出与当前需求相关的禁止项]

      ### 下一步
      - 执行 `/speckit.specify` 进入规范阶段
    </output_format>
  </phase>

  <phase id="2-SPECIFY" command="/speckit.specify">
    <description>
      描述需求规范，关注 "做什么"，而非 "怎么做"
      对应: SoT 文档层
    </description>

    <inputs>
      - requirement: 需求描述 (自然语言)
      - constitution_context: 上一阶段输出
    </inputs>

    <actions>
      - 识别涉及的业务域
      - 查询对应 SoT 文档:
        - STATE_MACHINE.md (状态相关)
        - DATA_SCHEMA.md (数据相关)
        - API_SOT.md (API 相关)
        - BUSINESS_RULES.md (规则相关)
      - 提取相关约束条件
      - 生成: specification_doc
    </actions>

    <output_format>
      ## 📋 Specification 规范

      ### 需求摘要
      [用户需求的结构化描述]

      ### 涉及 SoT 文档
      | 文档 | 版本 | 相关章节 |
      |------|------|---------|
      | STATE_MACHINE.md | v2.6 | §X |
      | DATA_SCHEMA.md | v5.2 | §X |

      ### 约束条件
      - [从 SoT 提取的约束]

      ### 成功标准
      - [可验证的成功条件]

      ### 下一步
      - 执行 `/speckit.plan` 进入规划阶段
    </output_format>
  </phase>

  <phase id="3-PLAN" command="/speckit.plan">
    <description>
      制定技术实现方案，关注架构和设计决策
      对应: Dev-Guides + Architecture 层
    </description>

    <inputs>
      - specification_doc: 上一阶段输出
    </inputs>

    <actions>
      - 分析技术栈约束 (FastAPI, Pydantic v2, SQLAlchemy 2.x)
      - 确定文件结构和模块划分
      - 设计 API 接口 (如适用)
      - 设计数据模型 (如适用)
      - 识别潜在风险
      - 生成: implementation_plan
    </actions>

    <output_format>
      ## 🗺️ Implementation Plan 实现方案

      ### 技术方案
      - 后端: [Router/Service/Schema 设计]
      - 前端: [Hook/API/Component 设计]

      ### 文件清单
      | 文件 | 操作 | 说明 |
      |------|------|------|
      | backend/routers/xxx.py | 新建/修改 | ... |

      ### 依赖关系
      ```
      [依赖图]
      ```

      ### 风险识别
      - [潜在风险及缓解措施]

      ### 下一步
      - 执行 `/speckit.tasks` 生成任务清单
    </output_format>
  </phase>

  <phase id="4-TASKS" command="/speckit.tasks">
    <description>
      将实现方案分解为可执行的小任务
      每个任务应该是可独立验证的单元
    </description>

    <inputs>
      - implementation_plan: 上一阶段输出
    </inputs>

    <actions>
      - 分解为原子任务 (每个 < 30 分钟)
      - 定义每个任务的验收标准
      - 排列任务优先级和依赖
      - 生成: task_list
    </actions>

    <output_format>
      ## ✅ Task List 任务清单

      ### 任务列表

      #### Task 1: [任务名称]
      - **文件**: `path/to/file.py`
      - **操作**: 新建/修改
      - **描述**: [具体操作]
      - **验收标准**: [如何验证完成]
      - **依赖**: [前置任务]

      #### Task 2: ...

      ### 执行顺序
      ```
      Task 1 → Task 2 → Task 3
                   ↘
                    Task 4
      ```

      ### 下一步
      - 执行 `/speckit.implement` 开始实现
      - 或执行 `/speckit.implement task=1` 实现特定任务
    </output_format>
  </phase>

  <phase id="5-IMPLEMENT" command="/speckit.implement">
    <description>
      执行任务，生成代码
      支持全量执行或单任务执行
    </description>

    <inputs>
      - task_list: 上一阶段输出
      - task: 可选，指定执行的任务编号
    </inputs>

    <actions>
      - 按顺序执行任务
      - 每个任务完成后验证
      - 调用 CodeFactory Skills (如已实现):
        - CodeSearcherSkill (搜索参考代码)
        - CodeAdapterSkill (适配代码)
        - CodeAssemblerSkill (组装代码)
        - CodeVerifierSkill (验证代码)
      - 生成: implementation_result
    </actions>

    <output_format>
      ## 🚀 Implementation Result 实现结果

      ### 已完成任务
      - [x] Task 1: [描述] ✅
      - [x] Task 2: [描述] ✅
      - [ ] Task 3: [描述] ⏳

      ### 生成的文件
      | 文件 | 状态 | 行数 |
      |------|------|------|
      | backend/routers/xxx.py | 新建 | 150 |

      ### 验证结果
      - mypy: ✅ 通过
      - ruff: ✅ 通过
      - SoT Guard: ✅ 通过

      ### 下一步
      - 运行测试: `pytest backend/tests/xxx`
      - 或继续: `/speckit.implement task=3`
    </output_format>
  </phase>
</workflow>

<!-- ======================================================
     2. 辅助命令 (Auxiliary Commands)
====================================================== -->
<auxiliary_commands>
  <command id="/speckit.clarify">
    <description>澄清规范中的模糊点</description>
    <usage>/speckit.clarify "状态转换规则不明确"</usage>
  </command>

  <command id="/speckit.analyze">
    <description>分析跨阶段一致性</description>
    <usage>/speckit.analyze</usage>
  </command>

  <command id="/speckit.checklist">
    <description>生成验证检查清单</description>
    <usage>/speckit.checklist</usage>
  </command>

  <command id="/speckit.status">
    <description>显示当前工作流状态</description>
    <usage>/speckit.status</usage>
  </command>
</auxiliary_commands>

<!-- ======================================================
     3. 与 ASDD 集成 (ASDD Integration)
====================================================== -->
<asdd_integration>
  <mapping>
    | Spec-Kit 阶段 | ASDD 对应层 | 文档 |
    |---------------|------------|------|
    | Constitution | Layer 1: Overview | MASTER.md, PROJECT_RULES.md |
    | Specification | Layer 2: SoT | STATE_MACHINE.md, DATA_SCHEMA.md, etc. |
    | Plan | Layer 3: Dev-Guides | API_DEVELOPMENT_FLOW.md |
    | Tasks | Layer 3: Dev-Guides | 任务清单 |
    | Implement | Layer 4: Architecture | 代码实现 |
  </mapping>

  <rules>
    - 所有规范必须与 SoT 文档一致
    - 涉及 SoT 变更必须走 OpenSpec 流程
    - 代码生成前必须通过 SoT Guard 验证
  </rules>
</asdd_integration>

<!-- ======================================================
     4. 使用示例 (Usage Examples)
====================================================== -->
<usage>
  示例 1: 完整工作流
  「
  我要添加日报批量导出 Excel 功能。

  /speckit.constitution
  [确认宪法约束]

  /speckit.specify
  [生成规范文档]

  /speckit.plan
  [制定技术方案]

  /speckit.tasks
  [分解任务清单]

  /speckit.implement
  [执行实现]
  」

  示例 2: 从中间阶段开始
  「
  我已经有需求规范了，直接进入规划阶段。

  /speckit.plan
  requirement = "添加日报批量导出，支持按状态和日期筛选，输出 xlsx 格式"
  」

  示例 3: 单任务执行
  「
  /speckit.implement task=2
  只执行任务清单中的第 2 个任务
  」
</usage>

<!-- ======================================================
     5. 版本记录 (Version Notes)
====================================================== -->
<VERSION_NOTES>
  ### v1.0 (2025-12-17)
  - 初始版本
  - 基于 GitHub Spec-Kit 适配
  - 五阶段工作流: Constitution → Specify → Plan → Tasks → Implement
  - 与 ASDD 4 层架构集成
  - 添加辅助命令: clarify, analyze, checklist, status
</VERSION_NOTES>

</skill>