adspecs 0.1.12

package/skills/adspecs-write-sow/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: "adspecs-write-sow"
+description: "根据项目信息、合同要点与实施范围创建或更新工作说明书（SOW）。"
+argument-hint: "描述项目背景、甲乙方、实施范围与关键约定"
+compatibility: "需要 adspecs 项目结构及 docs/ 目录"
+metadata:
+  author: "Qingwen Chen"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+**必须** 在继续之前考虑用户输入（如果非空）。
+
+## 路径配置加载
+
+在开始执行之前，先确定输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键         | 默认值                 | 用途                                           |
+| -------------- | ---------------------- | ---------------------------------------------- |
+| `sow_dir`      | `docs/00-planning/sow` | 工作说明书（SOW）输出目录                      |
+| `planning_dir` | `docs/00-planning`     | 规划阶段文档目录（输入解析时引用已有规划报告） |
+
+将解析后的路径分别记为 `SOW_DIR` 和 `PLANNING_DIR`，后续步骤中引用此变量而非硬编码路径。
+
+## 执行前检查
+
+**检查扩展钩子（编写 SOW 前）**:
+
+- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.before_write_sow` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选前置钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+  - **必选钩子** (`optional: false`):
+
+    ```
+    ## 扩展钩子
+
+    **自动前置钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    等待钩子命令结果后再继续执行。
+    ```
+
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
+
+## 概述
+
+用户在触发消息中 `/adspecs-write-sow` 之后输入的文本**就是**项目与 SOW 描述。假设你在本次对话中始终可以获取到它，即使 `$ARGUMENTS` 字面上出现在下方。除非用户提供了空命令，否则不要要求用户重复输入。
+
+SOW（工作说明书）是**项目级合同/配套文件**，用于定义乙方为甲方实施项目的工作内容、范围、计划、组织职责、假设约定与验收标准。与 PRD 不同，SOW **不是**按功能特性拆分的开发文档，因此本技能不使用 `feature.json` 功能注册流程，而是按项目生成单一 SOW 文档。
+
+## 输入解析流程
+
+1. **检查已有文档**：扫描 `{PLANNING_DIR}/`（默认 `docs/00-planning/`）是否已有 planning-report 报告；如有，读取其中的项目背景、目标、实施范围、模块清单、分期策略等，作为 SOW 编写的权威输入来源，避免重复采集。
+2. **提取关键要素**：从用户输入与 planning-report 中识别甲方/乙方、项目名称、实施范围（模块/功能/集成/数据转换/客制化）、项目周期与里程碑、质保与验收要求。
+3. **检查已有 SOW**：扫描 `{SOW_DIR}/` 是否已存在目标 SOW 文件；如有则进入**更新模式**，保留用户已确认内容，仅补全或修订缺失章节。
+4. **做出合理推断**：对通用合同条款（问题分级、确认时限、办公模式、工作时间、SLA）沿用模板默认值，并将假设写入“关键假设条件”章节。对未明确的可选信息，基于行业标准和业务上下文推断其合理取值。
+5. **标记待澄清项**：仅对显著影响**合同主体/范围/付款验收**的关键决策标记 [NEEDS CLARIFICATION]（最多 3 个）。
+
+## 输出生成流程
+
+根据项目描述，执行以下操作：
+
+1. **生成简洁的项目短名称**（2-4 个词）用于文件命名：
+   - 从描述中提取甲方简称、系统/产品名或项目关键词
+   - 尽量使用 `客户简称-系统名` 形式（如 `abc-srm`、`xingye-crm`）
+   - 保留行业术语与缩写（SRM、CRM、ERP、MES、WMS 等）
+   - 示例：
+     - "为 ABC 公司实施 SRM 系统" → "abc-srm"
+     - "兴业 CRM 项目工作说明书" → "xingye-crm"
+     - "XX 集团 MES 一期实施" → "xx-mes-phase1"
+
+2. **创建 SOW 目录和文件**:
+
+   SOW 默认存储在 `{SOW_DIR}` 目录下，除非用户明确提供了 `SOW_OUTPUT_DIRECTORY`。
+
+   **`SOW_FILE` 的解析规则**:
+   1. 如果用户明确提供了 `SOW_OUTPUT_DIRECTORY`（例如通过参数或配置），使用它作为输出目录
+   2. 否则使用 `{SOW_DIR}` 作为输出目录
+   3. 文件名规则：
+      - 若识别到项目短名称：`{输出目录}/工作说明书SOW-<short-name>.md`
+      - 否则：`{输出目录}/工作说明书SOW.md`
+   4. 设置 `SOW_FILE` 为最终解析后的完整路径
+
+   **创建目录和 SOW 文件**:
+   - `mkdir -p {输出目录}`
+   - 将 `.adspecs/templates/20-工作说明书SOW模板.md` 复制到 `SOW_FILE` 作为起点
+   - 如果模板文件不存在，直接依据本技能末尾《SOW 章节结构》生成同等结构的文档
+
+   **重要**:
+   - 每次 `/adspecs-write-sow` 调用只生成或更新一个 SOW 文档
+   - 若 `SOW_FILE` 已存在，进入**更新模式**：保留用户已填写的实际内容，仅补全或修订缺失章节，切勿用占位符覆盖已确认信息
+
+3. 加载 `.adspecs/templates/20-工作说明书SOW模板.md` 以了解所需的结构（若不存在，使用本技能末尾《SOW 章节结构》作为权威结构）。
+
+4. 遵循以下执行流程：
+   1. 从参数中解析项目描述
+      如果为空：错误 "No project / SOW description provided"
+   2. 提取描述中的关键要素：
+      - 甲方、乙方全称与简称
+      - 项目名称、系统/产品范围（模块、功能、集成、数据转换、客制化）
+      - 实施地点与办公模式
+      - 项目周期、里程碑、需求冻结时间
+      - 质保服务与 SLA 约定
+      - 交付物与验收方式
+   3. 对于不明确的方面：
+      - 基于行业惯例与模板默认条款做出合理推断（如集中办公、5×8 工作时间、S/A/B/C 问题分级、5 工作日确认视为接受等）
+      - 仅在以下情况标记为 [NEEDS CLARIFICATION: 具体问题]：
+        - 该选择显著影响**合同范围、付款条件或验收责任**
+        - 存在多种合理解释且法律/商务含义不同
+        - 没有合理的默认值（如甲乙方主体、合同编号、实施范围边界）
+      - **限制：最多 3 个 [NEEDS CLARIFICATION] 标记**
+      - 按影响排序澄清优先级：合同主体/范围 > 付款与验收条件 > 计划与里程碑 > 服务细节
+   4. 填写封面信息、文档修改记录、审批签字与保密声明
+   5. 填写各正文章节（前言、项目综述、项目范围、项目计划、项目组织及职责、关键假设与约定、项目验收、附录A）
+   6. 对涉及金额、周期、数量的空缺，保留 `[XX]` 占位并在《待补充信息清单》中汇总，供商务/项目经理确认
+   7. 返回：成功（SOW 可进入双方评审与签署流程）
+
+5. 使用模板结构将 SOW 写入 `SOW_FILE`，用从项目描述派生的具体细节替换占位符，同时保留章节顺序、编号和标题。
+
+6. **SOW 质量验证**: 在编写初始 SOW 后，根据质量标准对其进行验证：
+
+   a. **创建 SOW 质量检查清单**: 在 `{输出目录}/checklists/sow_checklist.md` 生成检查清单文件（多 SOW 时文件名追加 `-<short-name>`），包含以下验证项：
+
+   ```markdown
+   # 工作说明书（SOW）质量检查清单：[项目名称]
+
+   **目的**: 在提交双方评审与签署之前验证 SOW 的完整性、合规性与一致性
+   **创建日期**: [DATE]
+   **文档**: [链接到 SOW 文件]
+
+   ## 合同一致性
+
+   - [ ] 文档名称与合同/项目章程约定一致（尤其是作为付款条件的交付物名称）
+   - [ ] 甲方、乙方全称与简称正确且前后一致
+   - [ ] 合同编号、签约日期字段已填写或明确标注待定
+   - [ ] 页脚文档名称与页码要求已在使用说明中提示（定稿环节遵循）
+
+   ## 范围完整性
+
+   - [ ] 实施业务/模块范围明确
+   - [ ] 实施功能范围表已填写（模块/功能/功能描述）
+   - [ ] 系统集成范围与双方接口开发职责清晰
+   - [ ] 初始数据转换范围与甲乙方数据准备职责明确
+   - [ ] 客制化开发与报表范围（含报表数量上限）明确
+   - [ ] 系统环境要求（软硬件、网络）职责划分清晰
+   - [ ] 范围为“最大实施范围框架”并说明变更走变更流程
+
+   ## 计划与组织
+
+   - [ ] 总体计划阶段、里程碑与交付物已列出
+   - [ ] 需求冻结时间与逾期不纳入交付的约定明确
+   - [ ] 甲方/乙方责任与义务分别完整
+   - [ ] 项目组织架构与通讯录来源说明清楚
+
+   ## 假设、约定与验收
+
+   - [ ] 关键假设条件覆盖资源、组织、数据、采购、办公场所等
+   - [ ] 质保服务内容、服务时间与 SLA 指标完整
+   - [ ] 问题严重级别（S/A/B/C）定义清晰
+   - [ ] 验收标准、验收方法、验收内容与交付物表完整
+   - [ ] 附录A 变更控制程序与交付物接受程序完整
+
+   ## 就绪度
+
+   - [ ] 无残留 [NEEDS CLARIFICATION] 标记
+   - [ ] 待补充商务/金额字段已在《待补充信息清单》中汇总
+   - [ ] 不适用章节已整节删除（无“N/A”残留）
+
+   ## 备注
+
+   - 标记为不完整的项需在提交签署前更新 SOW
+   ```
+
+   b. **运行验证检查**: 对照每个检查清单项审查 SOW：
+   - 对于每一项，确定其通过或失败
+   - 记录发现的具体问题（引用相关章节）
+
+   c. **处理验证结果**:
+   - **如果所有项通过**: 将检查清单标记为完成，并继续必选执行后钩子部分
+
+   - **如果有项失败（不包含 [NEEDS CLARIFICATION]）**:
+     1. 列出失败的项和具体问题
+     2. 更新 SOW 以处理每个问题
+     3. 重新运行验证直到所有项通过（最多 3 次迭代）
+     4. 如果 3 次迭代后仍然失败，在检查清单备注中记录剩余问题并警告用户
+
+   - **如果 [NEEDS CLARIFICATION] 标记残留**:
+     1. 从 SOW 中提取所有 [NEEDS CLARIFICATION: ...] 标记
+     2. **限制检查**: 如果超过 3 个标记，仅保留 3 个最关键的问题（按合同主体/范围/付款影响），对其余做出合理推断
+     3. 对于每个需要澄清的问题（最多 3 个），以此格式向用户呈现选项：
+
+        ```markdown
+        ## 问题 [N]：[主题]
+
+        **上下文**: [引用相关 SOW 章节]
+
+        **需要明确的内容**: [NEEDS CLARIFICATION 标记中的具体问题]
+
+        **建议答案**:
+
+        | 选项   | 答案             | 含义                      |
+        | ------ | ---------------- | ------------------------- |
+        | A      | [第一个建议答案] | [这对合同/项目意味着什么] |
+        | B      | [第二个建议答案] | [这对合同/项目意味着什么] |
+        | C      | [第三个建议答案] | [这对合同/项目意味着什么] |
+        | 自定义 | 提供你自己的答案 | [说明如何提供自定义输入]  |
+
+        **你的选择**: _[等待用户回复]_
+        ```
+
+     4. **关键 - 表格格式**: 确保 markdown 表格格式正确：
+        - 使用一致的间距，管道对齐
+        - 每个单元格的内容周围应有空格：`| 内容 |` 而非 `|内容|`
+        - 标题分隔符必须至少有 3 个破折号：`|--------|`
+     5. 按顺序编号问题（Q1、Q2、Q3 - 最多 3 个）
+     6. 在等待回复之前一起呈现所有问题
+     7. 等待用户对所有问题的选择回复（例如："Q1: A, Q2: 自定义 - [详情], Q3: B"）
+     8. 将 SOW 中的每个 [NEEDS CLARIFICATION] 标记替换为用户选择或提供的答案来更新 SOW
+     9. 在所有澄清解决后重新运行验证
+
+   d. **更新检查清单**: 在每次验证迭代后，以当前的通过/失败状态更新检查清单文件
+
+## 必选执行后钩子
+
+**必须在向用户报告完成之前完成本节。**
+
+检查项目根目录是否存在 `.adspecs/extensions.yml`。
+
+- 如果不存在，或 `hooks.after_write_sow` 下没有注册钩子，跳到完成报告。
+- 如果存在，读取它并查找 `hooks.after_write_sow` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**：
+
+    ```
+    ## 扩展钩子
+
+    **自动钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+## 完成报告
+
+向用户报告完成情况，包含：
+
+- `SOW_FILE` — SOW 文档路径
+- 检查清单结果摘要
+- 《待补充信息清单》摘要（需商务/项目经理确认的金额、周期、数量等字段）
+- 是否准备好进入双方评审与签署流程
+
+## 快速指南
+
+- SOW 面向**双方项目经理与商务/法务**，用于约束交付边界与责任，而非描述技术实现。
+- 明确区分**甲方责任**与**乙方责任**，避免职责空白或重叠。
+- 范围描述统一采用“最大实施范围框架”，范围变更一律指向 `附录A-1 项目变更控制程序`。
+- 涉及付款条件的交付物名称必须与合同一致；金额、周期、报表数量等敏感字段以占位符保留并汇总待确认。
+
+### 章节要求
+
+- **必填章节**: 前言、项目范围、项目计划、项目组织及职责、关键假设与约定、项目验收、附录A。
+- **可选章节**: 术语表、系统集成范围、初始数据转换范围、客制化开发范围、质保 SLA — 仅在与项目相关时保留。
+- 当某个章节不适用时，**完全删除**它（不要留下“N/A”）。
+
+### SOW 编写指南
+
+1. **做出合理推断**: 对通用合同条款（问题分级、验收确认时限、集中办公、工作时间、SLA）沿用模板默认值，不逐项询问。
+2. **记录假设**: 将默认假设写入“关键假设条件”章节。
+3. **限制澄清标记**: 最多 3 个 [NEEDS CLARIFICATION]，仅用于合同主体、范围边界、付款/验收条件等关键决策。
+4. **保护已确认信息**: 更新模式下不得用占位符覆盖用户已填写的甲乙方、金额、日期等实际内容。
+5. **合规提示**: 在文档中保留定稿、打印、签署、存档的合规要求提示（页脚、骑缝章、签署日期具体到年月日）。
+
+**合理默认值示例**（不要逐项询问）:
+
+- 交付物确认时限：甲方 5 个工作日内未回应视为接受
+- 问题严重级别：S/A/B/C 四级及对应 SLA
+- 办公模式：实施集中办公（同城），异地由甲方承担差旅
+- 工作时间：星期一至星期五 5×8 小时，不含公众假日
+- 验收方式：分阶段验收 + 《项目验收报告》整体签署
+
+## SOW 章节结构
+
+当模板文件缺失时，按以下权威结构生成 SOW：
+
+- 封面信息（项目名称、文档名称、合同编号、甲方、乙方、签约日期）
+- 文档修改记录（版本 / 日期 / 责任人 / 版本描述）
+- 审批签字（甲方项目经理 / 乙方项目经理）+ 保密声明
+- 目录
+- 1 前言（1.1 文档目的、1.2 相关文档、1.3 术语）
+- 2 项目综述（2.1 项目背景、2.2 项目目标）
+- 3 项目范围（3.1 项目组织范围、3.2 项目实施地点、3.3 实施范围：3.3.1 业务/模块范围、3.3.2 功能范围、3.3.3 系统集成范围、3.3.4 初始数据转换范围、3.3.5 客制化开发与报表开发范围、3.3.6 系统环境要求）
+- 4 项目计划（4.1 总体计划）
+- 5 项目组织及职责（5.1 项目组织架构、5.2 责任与义务：5.2.1 甲方责任、5.2.2 乙方责任）
+- 6 关键假设与约定（6.1 关键假设条件：6.1.1 一般关键假设、6.2 项目约定：6.2.1 质保服务约定）
+- 7 项目验收（7.1 验收标准、7.2 验收方法、7.3 验收内容：7.3.1 验收内容、7.3.2 交付物）
+- 8 附录A：项目控制程序（A-1 项目变更控制程序、A-2 交付物接受程序）
+
+## 完成标志
+
+- [ ] SOW 已写入 `SOW_FILE` 并对照质量检查清单验证通过
+- [ ] 《待补充信息清单》已汇总需商务/项目经理确认的字段
+- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过
+- [ ] 完成报告已呈现给用户，包含 SOW 文件路径、检查清单结果与待补充信息摘要