kld-sdd 2.4.18 → 2.5.0

package/templates/skills/kld-sdd/opsx-design/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: opsx-design
 description: "技术设计文档技能 - 针对单一 Capability 创建局部技术实现方案"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -25,23 +25,23 @@ allowed-tools:
 >
 > 代码实现将在 `/opsx-apply` 阶段进行。
 > **完成本阶段后，绝对禁止自动继续执行 task 等后续阶段。**
+> 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **⚠️ 渐进式上下文加载原则**
 >
-> - 本技能针对**单一 Capability** 执行设计
-> - **输入路径**：`changes/<name>/specs/<capability>/spec.md`
-> - **输出路径**：`changes/<name>/specs/<capability>/design.md`
-> - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design
-
+> - 本技能针对**单一 Capability** 执行设计（Simple 模式例外，见下方 S1 说明）
+> - **输入路径**（Full 模式）：`changes/<name>/specs/<capability>/spec.md`
+> - **输出路径**（Full 模式）：`changes/<name>/specs/<capability>/design.md`
+> - **输入路径**（Simple 模式）：`changes/<name>/spec.md`
+> - **输出路径**（Simple 模式）：`changes/<name>/design.md`
+> - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design（Full 模式）
 
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
-> **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
 ---
 
@@ -50,7 +50,7 @@ allowed-tools:
 | 维度 | 内容 |
 |------|------|
 | 核心问题 | How - 单一 Capability 如何实现 |
-| 关键输出 | specs/<capability>/design.md |
+| 关键输出 | Full: `specs/<capability>/design.md` / Simple: `design.md` |
 | 上游依赖 | overview.md → proposal.md → 当前 capability 的 spec.md |
 | 下游依赖 | tasks.md |
 
@@ -58,6 +58,12 @@ allowed-tools:
 
 ## 启动流程
 
+### 0. 【S1 模式检测】读取 proposal.md mode
+
+读取当前变更的 `proposal.md` frontmatter，提取 `mode` 字段：
+- `mode: simple` → Simple 模式（design.md 落变更根目录，跳过 Capability 选择）
+- `mode: full` 或未设置 → Full 模式（默认，design.md 落 specs/<capability>/）
+
 ### 1. 【交互引导】确认变更名称和 Capability
 
 **步骤 1a - 确认变更名称**：
@@ -84,15 +90,9 @@ openspec list
 
 ### 2. 【上下文加载】识别并读取用户提供的文件
 
-**自动识别上下文文件**：
-若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
+**自动识别上下文文件**：若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
 
-**上下文类型与用途**：
-| 上下文类型 | 用途 | 如何融入 design |
-|------------|------|----------------|
-| 代码文件 | 分析现有实现、依赖关系 | 确定代码锚点、修改策略 |
-| 架构文档 | 了解系统边界、模块关系 | 对齐总体设计方向 |
-| 数据库 Schema | 了解数据模型约束 | 纳入数据设计章节 |
+> 上下文类型（代码文件 / 架构文档 / 数据库 Schema）与用途见 `./reference.md`「§2 上下文类型与用途」。
 
 **【可选】业务知识库检索**：
 设计涉及 MM/CO 领域概念且 spec 未充分定义时，可调用 **opsx-knowledge** skill。
@@ -100,20 +100,7 @@ openspec list
 
 ### 3. 渐进式上下文加载
 
-**⛔ 必须严格按以下顺序加载：**
-
-```
-第 1 层：全局基线
-  → openspec/specs/overview.md
-
-第 2 层：宏观背景
-  → changes/<name>/proposal.md
-
-第 3 层：精准打击（仅当前 Capability）
-  → changes/<name>/specs/<capability>/spec.md
-
-⛔ 隔离红线：禁止读取其他 Capability 的文档！
-```
+> ⛔ 必须严格按 overview.md → proposal.md → 当前 capability spec.md 顺序加载；隔离红线：禁止读取其他 Capability 的文档。**完整层级图见 `./reference.md`「§3 渐进式上下文加载层级图」**。
 
 ### 4. 【关键步骤】读取本地模板文件
 
@@ -143,18 +130,19 @@ openspec list
 
 **输出路径**：`changes/<name>/specs/<capability>/design.md`
 
-### 7. 质量红线自检
+### 6.5 【version 正则注释】允许前导零
+
+design.md 中若使用 version 正则约束（如格式校验 `^\d+\.\d+\.\d+$`），需在正则旁**标注「允许前导零」**：
+
+- `^\d+\.\d+\.\d+$` 允许 `01.02.003` 这类前导零版本号（`\d+` 不限制首位非零）。
+- 若业务要求**禁止前导零**（语义化版本规范），应收紧为 `^0*[1-9]\d*\.[0-9]+\.[0-9]+$`，或由用户确认是否放宽，并在 design.md 注明决策。
+- 本次仅加注释说明，不强制收紧正则；标注后让 reviewer 一眼看出该正则的前导零行为。
 
-写入文档前，逐项确认：
-- [ ] 文档结构完全符合 `openspec-templates/design.md` 模板
-- [ ] 100% 覆盖 spec.md 中的所有需求项
-- [ ] 字段完整性追溯表已填写
-- [ ] 代码锚点已明确（现有代码修改点）
-- [ ] 外部依赖已列出
-- [ ] 异常处理策略已定义
-- [ ] 文档末尾包含质量红线检查清单
+> 目的：避免 version 正则隐式接受前导零而无人知晓，导致版本号格式契约与预期不符。
+
+### 7. 质量红线自检
 
-**如有任意一项未满足，重新生成对应章节，直至全部通过。**
+> 写入文档前逐项确认，完整 7 项自检清单见 `./checklist.md`「§7 质量红线自检」。如有任意一项未满足，重新生成对应章节，直至全部通过。
 
 ### 8. 【交互引导】确认文档并输出结果
 
@@ -178,11 +166,19 @@ openspec list
 
 ## Guardrails
 
-- **必须以 `openspec-templates/design.md` 为模板基准**
-- **⛔ 渐进式加载**：严格按 overview.md → proposal.md → spec.md 顺序加载
-- **⛔ 隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design
-- design.md 聚焦【How】，是 spec.md → tasks.md 的桥梁
-- 必须 100% 覆盖 spec.md 定义的需求项
-- 代码锚点必须具体到类/方法级别
-- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
-- **⛔ 单阶段原则：完成 design.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx-task`，**绝对禁止自动执行 task 等后续阶段**。每个阶段必须由用户主动触发。
+> 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
+
+- **必须以 `openspec-templates/design.md` 为模板基准**。
+- **⛔ 渐进式加载**：严格按 overview.md → proposal.md → spec.md 顺序加载。
+- **⛔ 隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design。
+- design.md 聚焦【How】，是 spec.md → tasks.md 的桥梁；必须 100% 覆盖 spec.md 定义的需求项。
+- 代码锚点必须具体到类/方法级别。
+- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作。
+- **⛔ 单阶段原则**：完成 design.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-task`，绝对禁止自动执行 task 等后续阶段。每个阶段必须由用户主动触发。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 design 需要校验时 — 含阶段边界⛔（Design 阶段约束）、§7 质量红线自检（7 项）、Guardrails ⛔ 强制项勾选表。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§2 上下文类型与用途表、§3 渐进式上下文加载层级图。

package/templates/skills/kld-sdd/opsx-design/checklist.md

@@ -0,0 +1,46 @@
+---
+description: opsx-design 的阶段强制检查点与自检清单。仅在执行 design 需要校验时读取。
+---
+
+# opsx-design — 检查清单（checklist）
+
+> 执行 opsx-design 时逐项校验。含阶段边界⛔、§7 质量红线自检、Guardrails ⛔ 强制项。
+> 详细模板（telemetry 命令 / §2 上下文类型表 / §3 加载层级图）见 `./reference.md`。
+
+---
+
+## 阶段边界⛔（Design 阶段约束）
+
+- [ ] ✅ 允许：创建/编辑 design.md 文档、读取代码/文档作为上下文分析
+- [ ] ❌ 禁止：创建/修改任何代码文件、执行代码生成、运行测试
+- [ ] ⛔ 单阶段原则：完成 design.md 后必须立即停止，等待用户主动触发下一阶段
+- [ ] 代码实现将在 `/opsx-apply` 阶段进行
+- [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 task 等后续阶段
+
+---
+
+## §7 质量红线自检
+
+写入文档前，逐项确认：
+- [ ] 文档结构完全符合 `openspec-templates/design.md` 模板
+- [ ] 100% 覆盖 spec.md 中的所有需求项
+- [ ] 字段完整性追溯表已填写
+- [ ] 代码锚点已明确（现有代码修改点）
+- [ ] 外部依赖已列出
+- [ ] 异常处理策略已定义
+- [ ] 文档末尾包含质量红线检查清单
+
+**如有任意一项未满足，重新生成对应章节，直至全部通过。**
+
+---
+
+## Guardrails ⛔ 强制项
+
+- [ ] 必须以 `openspec-templates/design.md` 为模板基准
+- [ ] ⛔ **渐进式加载**：严格按 overview.md → proposal.md → spec.md 顺序加载（层级图见 `./reference.md`「§3」）
+- [ ] ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design
+- [ ] design.md 聚焦【How】，是 spec.md → tasks.md 的桥梁
+- [ ] 必须 100% 覆盖 spec.md 定义的需求项
+- [ ] 代码锚点必须具体到类/方法级别
+- [ ] ⛔ **阶段边界**：禁止执行任何代码创建/修改操作
+- [ ] ⛔ **单阶段原则**：完成 design.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-task`，绝对禁止自动执行 task 等后续阶段。每个阶段必须由用户主动触发。

package/templates/skills/kld-sdd/opsx-design/reference.md

@@ -0,0 +1,44 @@
+---
+description: opsx-design 的详细模板：telemetry 命令、上下文类型表、渐进式加载层级图。仅在需要参考详细模板时读取。
+---
+
+# opsx-design — 详细参考（reference）
+
+> 本文件承载 opsx-design 的重细节模板：telemetry 命令、§2 上下文类型表、§3 渐进式上下文加载层级图。
+> SKILL.md 保留入口骨架与指针；本文件为详细模板来源。
+
+---
+
+## 📊 Telemetry 命令模板（必做，不得跳过）
+
+> 阶段开始：`node skywalk-sdd/log.cjs start --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+---
+
+## §2 上下文类型与用途
+
+| 上下文类型 | 用途 | 如何融入 design |
+|------------|------|----------------|
+| 代码文件 | 分析现有实现、依赖关系 | 确定代码锚点、修改策略 |
+| 架构文档 | 了解系统边界、模块关系 | 对齐总体设计方向 |
+| 数据库 Schema | 了解数据模型约束 | 纳入数据设计章节 |
+
+---
+
+## §3 渐进式上下文加载层级图
+
+**⛔ 必须严格按以下顺序加载：**
+
+```
+第 1 层：全局基线
+  → openspec/specs/overview.md
+
+第 2 层：宏观背景
+  → changes/<name>/proposal.md
+
+第 3 层：精准打击（仅当前 Capability）
+  → changes/<name>/specs/<capability>/spec.md
+
+⛔ 隔离红线：禁止读取其他 Capability 的文档！
+```

package/templates/skills/kld-sdd/opsx-propose/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: opsx-propose
 description: "业务意图文档技能 - 引导创建 proposal.md，定义变更的 Why 和上下文总览"
 argument-hint: "[change-name] [上下文文件...]"
@@ -26,16 +26,14 @@ allowed-tools:
 > 即使用户提供了代码作为上下文，也只用于理解需求背景，**不执行任何代码操作**。
 > 代码实现请引导用户使用 `/opsx-apply` 命令。
 > **完成本阶段后，绝对禁止自动继续执行 spec/design/task 等后续阶段。**
-
+> 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
-> **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.cjs start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
 ---
 
@@ -92,20 +90,41 @@ allowed-tools:
 遇到不明 MM/CO 业务名词时，可调用 **opsx-knowledge** skill 查询 RAGFlow 知识库。
 结果仅作 `📚 知识库建议`，不得写入 proposal 强制约束；查询失败时继续主流程。
 
-### 3. 创建变更目录
+### 3. 创建变更目录（先检测后创建，避免「先 new 后问」）
 
+**第 1 步：检测变更是否已存在**。先检测，**不要直接 `openspec new change`**：
 ```bash
-openspec new change "<name>"
+openspec list --json 2>/dev/null || true
 ```
+或直接探测 `openspec/changes/<name>/` 是否存在（含 `.openspec.yaml` 或 `proposal.md`）。排除 `logs/` 目录——`logs/` 是 telemetry 自动创建的，不代表变更已初始化。
 
-此命令在 `openspec/changes/<name>/` 创建变更目录和 `.openspec.yaml`。
-
-**【交互引导】若变更已存在**：
-- 询问用户："变更 `<name>` 已存在，请选择：
+**第 2 步：根据检测结果决定**：
+- **不存在** → 直接执行第 3 步创建。
+- **已存在** → 先询问用户，**不要直接 new**："变更 `<name>` 已存在，请选择：
   - A. 覆盖原有变更（删除重建）
   - B. 继续编辑现有变更
   - C. 取消操作"
-- 根据用户选择执行对应操作
+  - **若目录仅含 `logs/`（无 `.openspec.yaml` 且无 `proposal.md`）**：提示用户"检测到残留空变更目录（仅含 telemetry 自动创建的 logs/），建议选 A 覆盖重建，避免复用空目录导致后续流程混淆"
+  - 用户选 A → 先删除 `openspec/changes/<name>/` 再执行第 3 步；选 B → 跳过创建直接进入 §4；选 C → 终止。
+
+**第 3 步：创建变更目录**（仅在不存在或用户确认覆盖后执行）：
+```bash
+openspec new change "<name>"
+```
+
+此命令在 `openspec/changes/<name>/` 创建变更目录和 `.openspec.yaml`。
+
+### 3.5 【首次检测】overview.md 全局契约空模板引导
+
+首次 propose 时，检测全局契约 `openspec/specs/overview.md` 是否仍为空模板（质量红线清单全未勾选）：
+
+1. 读取 `openspec/specs/overview.md`（若文件不存在视为空模板）。
+2. 检查质量红线清单是否有任意一项已勾选（`- [x]`）。
+3. 若**全未勾选**（空模板）→ 主动提示用户：「检测到全局契约 `overview.md` 尚未填充（质量红线清单未勾选）。建议先补全项目级 overview（技术栈/约束/领域语言），避免每个变更重复声明上下文。是否现在填充？可跳过继续本次 propose。」
+   - 用户选择跳过 → 继续 §4，并在 proposal.md 标注「overview.md 待补」。
+4. 已勾选（非空模板）→ 直接进入 §4。
+
+> 该检测不阻断流程，仅在 overview.md 长期为空时提醒，避免全局契约缺位。
 
 ### 4. 【关键步骤】读取本地模板文件
 
@@ -138,75 +157,15 @@ openspec instructions proposal --change "<name>" --json
 
 ### 6. 分析需求完整性
 
-**完整性检查**：
-- [ ] 是否有明确的问题描述？
-- [ ] 是否有可衡量的目标？
-- [ ] 是否涉及具体模块？
-- [ ] 是否有时间/资源约束？
-
-**【发现缺失时主动询问】**：
-> "我发现以下信息还不够清晰，请补充：
-> - [具体问题]
-> 补充后我将重新生成文档。"
+> 完整性检查（问题描述/目标/模块/约束 4 项）与缺失补充机制见 `./checklist.md`「§6 需求完整性检查」。发现缺失时主动询问用户补充。
 
 ### 7. 【交互引导】文档拆分模式选择
 
-**❗ 必须主动询问用户，不得默认选择**
-
-分析需求中的能力域数量后，使用 **AskUserQuestion** 工具向用户询问：
-
-> "📋 **检测到需求包含以下能力域：**
-> - [能力域列表]
->
-> 🤔 **请选择文档拆分模式：**
->
-> **A) 完整模式 (Full)** - 每个能力域独立文档
->    - 目录结构：`specs/<capability>/spec.md`, `specs/<capability>/design.md`, `specs/<capability>/tasks.md`
->    - 适合：大需求、多人协作、需要精细管控
->
-> **B) 简化模式 (Simple)** - 单一文档
->    - 目录结构：`spec.md`, `design.md`, `tasks.md`（合并所有能力域）
->    - 适合：小需求、单人快速迭代
->
-> **C) 自动判断** - 根据能力域数量自动选择
->    - 单个能力域 → Simple 模式
->    - 多个能力域 → Full 模式"
-
-根据用户选择：
-- 选择 A：设置 `mode: full`
-- 选择 B：设置 `mode: simple`
-- 选择 C：根据能力域数量自动判断并设置
-
-**将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
+**❗ 必须主动询问用户，不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`（Auto 按能力域数量判断），记录到 proposal.md 的 YAML frontmatter。
 
 ### 8. 【交互引导】测试策略选择
 
-**❗ 必须主动询问用户，不得默认选择**
-
-使用 **AskUserQuestion** 工具向用户询问：
-
-> "🧪 **请选择测试策略：**
->
-> **A) 测试驱动 (TDD)** - 测试先行
->    - 先生成测试任务，实现任务依赖测试任务
->    - DAG: 测试骨架 → 实现代码 → 测试验证
->    - 适合：核心业务逻辑、质量要求高
->
-> **B) 实现优先 (Impl-First)** - 代码先行
->    - 先生成实现任务，测试作为验证步骤
->    - DAG: 实现代码 → 测试验证
->    - 适合：UI 层、配置类、快速原型
->
-> **C) 无测试 (None)** - 仅实现
->    - 不生成测试任务，仅编译检查
->    - 适合：简单配置、文档更新"
-
-根据用户选择：
-- 选择 A：设置 `test-strategy: tdd`
-- 选择 B：设置 `test-strategy: impl-first`
-- 选择 C：设置 `test-strategy: none`
-
-**将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
+**❗ 必须主动询问用户，不得默认选择**。TDD / Impl-First / None 三种策略的 DAG 结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§8 测试策略选择」。根据用户选择设置 `test-strategy: tdd | impl-first | none`，记录到 proposal.md 的 YAML frontmatter。
 
 ### 9. 创建 proposal.md
 
@@ -216,17 +175,7 @@ openspec instructions proposal --change "<name>" --json
 
 ### 10. 质量红线自检
 
-写入文档前，逐项确认：
-- [ ] 文档结构完全符合 `openspec-templates/proposal.md` 模板
-- [ ] 章节编号和命名正确（如 `## 1. 需求背景` 而非 `## Why`）
-- [ ] 子章节结构正确（如 `### 1.1 现状问题`、`### 1.2 业务诉求`）
-- [ ] 涉及模块使用 checkbox 格式（`- [ ] 模块A`）
-- [ ] 依赖关系使用代码块图示
-- [ ] 前置依赖使用 checkbox 格式
-- [ ] 文档末尾包含质量红线检查清单
-- [ ] 能力分解章节已明确（决定后续 specs 文件夹结构）
-
-**如有任意一项未满足，重新生成对应章节，直至全部通过。**
+> 写入文档前逐项确认，完整 8 项自检清单见 `./reference.md`「§10 质量红线自检清单」。如有任意一项未满足，重新生成对应章节，直至全部通过。
 
 ### 11. 确认文档并输出结果
 
@@ -255,13 +204,20 @@ openspec instructions proposal --change "<name>" --json
 
 ## Guardrails
 
-- **必须以 `openspec-templates/proposal.md` 为模板基准**，不得使用 `openspec instructions` 返回的简化 template
-- `context` 和 `rules` 是你的约束条件，**不得出现在生成的文档中**
-- proposal.md 聚焦【Why】，不要写技术实现细节（留给 design.md）
-- 不要写 API 细节（留给 specs）
-- **Capabilities 章节是关键**：决定后续 specs 文件夹结构
-- 若跳过此文档，后续 specs 必须补齐影响范围
-- 文档写入后验证文件确实存在
-- 每次生成都提供文档摘要，等待用户确认后再继续
+> 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
+
+- **必须以 `openspec-templates/proposal.md` 为模板基准**，不得使用 `openspec instructions` 返回的简化 template。
+- `context` 和 `rules` 是约束条件，**不得出现在生成的文档中**。
+- proposal.md 聚焦【Why】，不写技术实现细节（留给 design.md），不写 API 细节（留给 specs）。
+- **Capabilities 章节是关键**：决定后续 specs 文件夹结构。
+- 文档写入后验证文件确实存在；每次生成都提供文档摘要，等待用户确认后再继续。
 - **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码，回复：「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx-apply` 执行。」
-- **⛔ 单阶段原则：完成 proposal.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx-spec`，**绝对禁止自动执行 spec/design/task 等后续阶段**。每个阶段必须由用户主动触发。
+- **⛔ 单阶段原则**：完成 proposal.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-spec`，绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
+- **⛔ Frontmatter 规范（L7）**：YAML frontmatter 中禁止写 `#` 注释（YAML 注释在 frontmatter 中可能导致解析问题）。如需说明，在 frontmatter 之前或之后用正文描述。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 propose 需要校验时 — 含阶段边界⛔（Propose 阶段约束）、§6 需求完整性检查、Guardrails ⛔ 强制项勾选表。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§7 文档拆分模式（Full/Simple/Auto）、§8 测试策略（TDD/Impl-First/None）、§10 质量红线自检清单（8 项）。

package/templates/skills/kld-sdd/opsx-propose/checklist.md

@@ -0,0 +1,44 @@
+---
+description: opsx-propose 的阶段强制检查点与自检清单。仅在执行 propose 需要校验时读取。
+---
+
+# opsx-propose — 检查清单（checklist）
+
+> 执行 opsx-propose 时逐项校验。含阶段边界⛔、需求完整性检查、Guardrails ⛔ 强制项。
+> 详细模板（telemetry 命令 / §7 模式说明 / §8 测试策略 / §10 质量红线自检清单）见 `./reference.md`。
+
+---
+
+## 阶段边界⛔（Propose 阶段约束）
+
+- [ ] ✅ 允许：创建/编辑 proposal.md 文档、读取代码/文档作为上下文分析
+- [ ] ❌ 禁止：创建/修改任何代码文件、执行代码生成、运行测试
+- [ ] ⛔ 单阶段原则：完成 proposal.md 后必须立即停止，等待用户主动触发下一阶段
+- [ ] 即使用户提供代码作为上下文，只用于理解需求背景，不执行任何代码操作
+- [ ] 代码实现引导用户使用 `/opsx-apply`
+- [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 spec/design/task 等后续阶段
+
+---
+
+## §6 需求完整性检查
+
+- [ ] 是否有明确的问题描述？
+- [ ] 是否有可衡量的目标？
+- [ ] 是否涉及具体模块？
+- [ ] 是否有时间/资源约束？
+- [ ] 发现缺失时主动询问用户补充（"我发现以下信息还不够清晰，请补充..."）
+
+---
+
+## Guardrails ⛔ 强制项
+
+- [ ] 必须以 `openspec-templates/proposal.md` 为模板基准，不得使用 `openspec instructions` 返回的简化 template
+- [ ] `context` 和 `rules` 是约束条件，不得出现在生成的文档中
+- [ ] proposal.md 聚焦【Why】，不写技术实现细节（留给 design.md）
+- [ ] 不写 API 细节（留给 specs）
+- [ ] Capabilities 章节是关键：决定后续 specs 文件夹结构
+- [ ] 若跳过此文档，后续 specs 必须补齐影响范围
+- [ ] 文档写入后验证文件确实存在
+- [ ] 每次生成都提供文档摘要，等待用户确认后再继续
+- [ ] ⛔ **阶段边界**：本阶段禁止执行任何代码创建/修改操作；用户要求处理代码时回复「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx-apply` 执行。」
+- [ ] ⛔ **单阶段原则**：完成 proposal.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-spec`，绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。

package/templates/skills/kld-sdd/opsx-propose/reference.md

@@ -0,0 +1,94 @@
+---
+description: opsx-propose 的详细模板：telemetry 命令、文档拆分模式、测试策略、质量红线自检清单。仅在需要参考详细模板时读取。
+---
+
+# opsx-propose — 详细参考（reference）
+
+> 本文件承载 opsx-propose 的重细节模板：telemetry 命令、§7 文档拆分模式说明、§8 测试策略说明、§10 质量红线自检清单。
+> SKILL.md 保留入口骨架与指针；本文件为详细模板来源。
+
+---
+
+## 📊 Telemetry 命令模板（必做，不得跳过）
+
+> 阶段开始：`node skywalk-sdd/log.cjs start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+---
+
+## §7 文档拆分模式选择
+
+**❗ 必须主动询问用户，不得默认选择**
+
+分析需求中的能力域数量后，使用 **AskUserQuestion** 工具向用户询问：
+
+> "📋 **检测到需求包含以下能力域：**
+> - [能力域列表]
+>
+> 🤔 **请选择文档拆分模式：**
+>
+> **A) 完整模式 (Full)** - 每个能力域独立文档
+>    - 目录结构：`specs/<capability>/spec.md`, `specs/<capability>/design.md`, `specs/<capability>/tasks.md`
+>    - 适合：大需求、多人协作、需要精细管控
+>
+> **B) 简化模式 (Simple)** - 单一文档
+>    - 目录结构：`spec.md`, `design.md`, `tasks.md`（合并所有能力域）
+>    - 适合：小需求、单人快速迭代
+>
+> **C) 自动判断** - 根据能力域数量自动选择
+>    - 单个能力域 → Simple 模式
+>    - 多个能力域 → Full 模式"
+
+根据用户选择：
+- 选择 A：设置 `mode: full`
+- 选择 B：设置 `mode: simple`
+- 选择 C：根据能力域数量自动判断并设置
+
+**将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
+
+---
+
+## §8 测试策略选择
+
+**❗ 必须主动询问用户，不得默认选择**
+
+使用 **AskUserQuestion** 工具向用户询问：
+
+> "🧪 **请选择测试策略：**
+>
+> **A) 测试驱动 (TDD)** - 测试先行
+>    - 先生成测试任务，实现任务依赖测试任务
+>    - DAG: 测试骨架 → 实现代码 → 测试验证
+>    - 适合：核心业务逻辑、质量要求高
+>
+> **B) 实现优先 (Impl-First)** - 代码先行
+>    - 先生成实现任务，测试作为验证步骤
+>    - DAG: 实现代码 → 测试验证
+>    - 适合：UI 层、配置类、快速原型
+>
+> **C) 无测试 (None)** - 仅实现
+>    - 不生成测试任务，仅编译检查
+>    - 适合：简单配置、文档更新"
+
+根据用户选择：
+- 选择 A：设置 `test-strategy: tdd`
+- 选择 B：设置 `test-strategy: impl-first`
+- 选择 C：设置 `test-strategy: none`
+
+**将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
+
+---
+
+## §10 质量红线自检清单
+
+写入文档前，逐项确认：
+- [ ] 文档结构完全符合 `openspec-templates/proposal.md` 模板
+- [ ] 章节编号和命名正确（如 `## 1. 需求背景` 而非 `## Why`）
+- [ ] 子章节结构正确（如 `### 1.1 现状问题`、`### 1.2 业务诉求`）
+- [ ] 涉及模块使用 checkbox 格式（`- [ ] 模块A`）
+- [ ] 依赖关系使用代码块图示
+- [ ] 前置依赖使用 checkbox 格式
+- [ ] 文档末尾包含质量红线检查清单
+- [ ] 能力分解章节已明确（决定后续 specs 文件夹结构）
+
+**如有任意一项未满足，重新生成对应章节，直至全部通过。**