@hunterzheng/kld-sdd 2.4.19

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

@@ -0,0 +1,201 @@
+---
+name: opsx-propose
+description: "业务意图文档技能 - 引导创建 proposal.md，定义变更的 Why 和上下文总览"
+argument-hint: "[change-name] [上下文文件...]"
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: sdd-team
+  version: "3.0"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+你是一个 SDD（Specification-Driven Development）业务意图文档专家。激活本技能后，你将引导用户创建符合质量红线标准的 **proposal.md** 文档。
+
+> **⚠️ 阶段边界约束**
+>
+> 当前处于 **Propose（规划）阶段**：
+> - ✅ **允许**：创建/编辑 proposal.md 文档、读取代码/文档作为上下文分析
+> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
+> - ⛔ **单阶段原则**：完成 proposal.md 后**必须立即停止**，等待用户主动触发下一阶段
+>
+> 即使用户提供了代码作为上下文，也只用于理解需求背景，**不执行任何代码操作**。
+> 代码实现请引导用户使用 `/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（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
+
+---
+
+## 技能定位
+
+**proposal.md** 是 SDD 四文档链的起点，聚焦回答：**为什么要做这个变更？**
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | Why - 为什么做 |
+| 关键输出 | 业务目标、影响范围、约束条件、能力分解 |
+| 下游依赖 | specs → design.md → tasks.md |
+
+---
+
+## 启动流程
+
+### 1. 输入处理
+
+当用户激活此 skill 时：
+
+**若提供了变更名称/描述**：
+- 解析为 kebab-case 名称（如 "add user authentication" → `add-user-auth`）
+- 跳转到第 2 步
+
+**若未提供任何输入**，使用 **AskUserQuestion** 询问：
+> "请描述本次变更的业务需求：
+> 1. 要解决什么问题？（现状痛点）
+> 2. 达成什么目标？（期望结果）
+> 3. 涉及哪些模块/系统？
+> 4. 有什么约束条件？（时间/技术/资源）"
+
+从描述中推导 kebab-case 名称。
+
+**【澄清机制】若用户描述模糊，主动追问**：
+- 若目标不明确："请用一句话明确本次变更要达成的具体目标"
+- 若影响范围不清："请列出本次变更涉及的所有模块/服务"
+- 若约束未提及："是否有时间限制、技术约束或依赖前提？"
+
+**重要**：未明确需求前不得继续。
+
+### 2. 【上下文加载】识别并读取用户提供的文件
+
+**自动识别上下文文件**：
+若用户在命令中指定了文件路径（如 `/opsx-propose atp-calc ./需求.md ./算法逻辑.md`），
+或在对话中附加/引用了文件，**必须自动读取这些文件**。
+
+**上下文处理原则**：
+- 需求文档 → 提取业务目标、用户场景、验收标准
+- 代码文件 → 分析现有实现，识别修改点
+- API 文档 → 了解接口约束、数据模型
+
+**【可选】业务知识库检索**：
+遇到不明 MM/CO 业务名词时，可调用 **opsx-knowledge** skill 查询 RAGFlow 知识库。
+结果仅作 `📚 知识库建议`，不得写入 proposal 强制约束；查询失败时继续主流程。
+
+### 3. 创建变更目录
+
+```bash
+openspec new change "<name>"
+```
+
+此命令在 `openspec/changes/<name>/` 创建变更目录和 `.openspec.yaml`。
+
+**【交互引导】若变更已存在**：
+- 询问用户："变更 `<name>` 已存在，请选择：
+  - A. 覆盖原有变更（删除重建）
+  - B. 继续编辑现有变更
+  - C. 取消操作"
+- 根据用户选择执行对应操作
+
+### 4. 【关键步骤】读取本地模板文件
+
+**必须先读取** `openspec-templates/proposal.md` 作为文档结构模板：
+```
+使用 Read 工具读取：openspec-templates/proposal.md
+```
+
+此模板定义了文档的完整结构，包括：
+- 章节编号和命名
+- 子章节结构（如 1.1 现状问题、1.2 业务诉求）
+- 格式要求（checkbox、代码块、表格等）
+- 质量红线检查清单
+
+**【重要】不得使用 `openspec instructions` 返回的简化 template，必须以 `openspec-templates/proposal.md` 为准。**
+
+### 5. 获取项目上下文（可选）
+
+```bash
+openspec instructions proposal --change "<name>" --json
+```
+
+解析返回的 JSON，仅获取：
+- `context`：项目背景约束（**仅供参考，不要写入文档**）
+- `rules`：文档编写规则（**仅供参考，不要写入文档**）
+- `outputPath`：文档输出路径
+- `dependencies`：前置依赖文件路径
+
+**注意**：忽略返回的 `template` 字段，使用步骤 4 读取的本地模板。
+
+### 6. 分析需求完整性
+
+> 完整性检查（问题描述/目标/模块/约束 4 项）与缺失补充机制见 `./checklist.md`「§6 需求完整性检查」。发现缺失时主动询问用户补充。
+
+### 7. 【交互引导】文档拆分模式选择
+
+**❗ 必须主动询问用户，不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`（Auto 按能力域数量判断），记录到 proposal.md 的 YAML frontmatter。
+
+### 8. 【交互引导】测试策略选择
+
+**❗ 必须主动询问用户，不得默认选择**。TDD / Impl-First / None 三种策略的 DAG 结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§8 测试策略选择」。根据用户选择设置 `test-strategy: tdd | impl-first | none`，记录到 proposal.md 的 YAML frontmatter。
+
+### 9. 创建 proposal.md
+
+**以 `openspec-templates/proposal.md` 的结构为骨架**，填充内容到 `outputPath`。
+
+**【质量红线】生成文档必须严格遵循模板结构。**
+
+### 10. 质量红线自检
+
+> 写入文档前逐项确认，完整 8 项自检清单见 `./reference.md`「§10 质量红线自检清单」。如有任意一项未满足，重新生成对应章节，直至全部通过。
+
+### 11. 确认文档并输出结果
+
+生成文档后，向用户展示概要：
+> "已生成 proposal.md 草案，概要如下：
+> - 变更名称：[name]
+> - 核心目标：[一句话总结]
+> - 影响模块：[模块列表]
+> - 能力域：[capability 列表]
+>
+> 请确认：
+> - A. 确认无误，继续创建 specs
+> - B. 需要修改 [具体章节]
+> - C. 补充更多信息"
+
+根据用户反馈：
+- 选择 A：保存文档，提示下一步
+- 选择 B/C：根据反馈修改文档
+
+最终输出：
+- 文档路径
+- 内容摘要
+- 下一步提示："运行 `/opsx-spec` 创建技术契约文档 (specs/<capability>/spec.md)"
+
+---
+
+## Guardrails
+
+> 完整 ⛔ 强制项勾选清单见 `./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 等后续阶段。每个阶段必须由用户主动触发。
+
+---
+
+## 渐进披露
+
+- 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 文件夹结构）
+
+**如有任意一项未满足，重新生成对应章节，直至全部通过。**

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

@@ -0,0 +1,168 @@
+---
+name: opsx-spec
+description: "技术契约文档技能 - 为每个能力创建 spec.md，定义业务场景与技术规范"
+argument-hint: "[change-name] [上下文文件...]"
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: sdd-team
+  version: "3.0"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+你是一个 SDD（Specification-Driven Development）技术契约专家。激活本技能后，你将引导用户为每个 Capability 创建 **spec.md** 文档。
+
+> **⚠️ 阶段边界约束**
+>
+> 当前处于 **Spec（契约）阶段**：
+> - ✅ **允许**：创建/编辑 spec.md 文档、读取代码/文档作为上下文分析
+> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
+> - ⛔ **单阶段原则**：完成 spec.md 后**必须立即停止**，等待用户主动触发下一阶段
+>
+> 即使用户提供了代码作为上下文，也只用于分析现有实现，**不执行任何代码操作**。
+> 代码实现将在 `/opsx-apply` 阶段进行。
+> **完成本阶段后，绝对禁止自动继续执行 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（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | What - 具体做什么（业务场景 + 技术规范） |
+| 关键输出 | specs/<capability>/spec.md |
+| 上游依赖 | proposal.md（能力列表） |
+| 下游依赖 | design.md → tasks.md |
+
+**【文件结构】**：每个 capability 生成一个独立的 spec 文件：
+```
+openspec/changes/<name>/
+├── proposal.md
+├── specs/
+│   ├── user-auth/
+│   │   └── spec.md      # capability 1 的规格
+│   ├── data-export/
+│   │   └── spec.md      # capability 2 的规格
+│   └── ...
+├── design.md
+└── tasks.md
+```
+
+---
+
+## 启动流程
+
+### 1. 【交互引导】确认变更名称
+
+若未提供，列出当前所有变更供用户选择：
+```bash
+openspec list
+```
+若变更不存在，引导用户先运行 `/opsx-propose <name>`。
+
+### 2. 【交互引导】确认 Capability
+
+读取 `proposal.md` 中定义的 Capabilities 列表：
+
+使用 **AskUserQuestion** 让用户选择要编写规格的 Capability：
+> "📋 **proposal.md 中定义的能力域：**
+> - A. `user-auth` - 用户认证
+> - B. `data-export` - 数据导出
+> - C. 全部（按顺序逐个创建）
+>
+> 请选择要为哪个 Capability 创建 spec.md："
+
+### 3. 【上下文加载】识别并读取用户提供的文件
+
+**自动识别上下文文件**：若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
+
+> 上下文类型（需求文档 / 代码文件 / API 文档）与用途见 `./reference.md`「§3 上下文类型与用途」。
+
+**【可选】业务知识库检索**：
+术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。
+知识库结果仅供参考，spec 契约以用户确认和 proposal 为准；失败时不阻塞。
+
+### 4. 【关键步骤】读取本地模板文件
+
+**必须先读取** `openspec-templates/spec.md` 作为文档结构模板：
+```
+使用 Read 工具读取：openspec-templates/spec.md
+```
+
+**【重要】不得使用 `openspec instructions` 返回的简化 template，必须以 `openspec-templates/spec.md` 为准。**
+
+### 5. 渐进式上下文加载
+
+```
+第 1 层：全局基线
+  → openspec/specs/overview.md
+
+第 2 层：宏观背景
+  → changes/<name>/proposal.md
+
+第 3 层：当前 Capability 上下文
+  → 已有的 spec.md（若为增量修改）
+```
+
+### 6. 创建 spec.md
+
+**以 `openspec-templates/spec.md` 的结构为骨架**，填充内容。
+
+**输出路径**：`changes/<name>/specs/<capability>/spec.md`
+
+**【质量红线】需求项格式要求**：
+- 需求项使用 `####`（4个#）
+- 场景使用 `#####`（5个#）
+
+### 7. 质量红线自检
+
+> 写入文档前逐项确认，完整 7 项自检清单见 `./checklist.md`「§7 质量红线自检」。自检完成后**必须**输出结构化自检报告（模板见 `./reference.md`「§7 质量自检报告模板」），未通过项自动修复后重新输出，直至全部 ✅。
+
+### 8. 确认文档并输出结果
+
+生成文档后，向用户展示概要：
+> "已生成 spec.md，概要如下：
+> - Capability：[name]
+> - 需求项数量：[N]
+> - 场景数量：[M]
+>
+> 请确认：
+> - A. 确认无误，继续下一个 Capability 的 spec / 进入 design
+> - B. 需要修改
+> - C. 补充更多信息"
+
+最终输出：
+- 文档路径
+- 下一步提示："运行 `/opsx-design <name> <capability>` 创建技术设计文档"
+
+---
+
+## Guardrails
+
+> 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：
+
+- **必须以 `openspec-templates/spec.md` 为模板基准**。
+- spec.md 聚焦【What】，不写 How（留给 design.md）。
+- **需求项格式必须正确**：`####` 需求项、`#####` 场景；每个需求项必须有清晰的验收标准。
+- 技术契约必须可执行、无歧义。
+- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作。
+- **⛔ 单阶段原则**：完成 spec.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-design`，绝对禁止自动执行 design/task 等后续阶段。每个阶段必须由用户主动触发。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 spec 需要校验时 — 含阶段边界⛔（Spec 阶段约束）、§7 质量红线自检（7 项）、Guardrails ⛔ 强制项勾选表。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§3 上下文类型与用途表、§7 质量自检报告模板（结构化表格）。

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

@@ -0,0 +1,46 @@
+---
+description: opsx-spec 的阶段强制检查点与自检清单。仅在执行 spec 需要校验时读取。
+---
+
+# opsx-spec — 检查清单（checklist）
+
+> 执行 opsx-spec 时逐项校验。含阶段边界⛔、§7 质量红线自检、Guardrails ⛔ 强制项。
+> 详细模板（telemetry 命令 / §3 上下文类型表 / §7 质量自检报告模板）见 `./reference.md`。
+
+---
+
+## 阶段边界⛔（Spec 阶段约束）
+
+- [ ] ✅ 允许：创建/编辑 spec.md 文档、读取代码/文档作为上下文分析
+- [ ] ❌ 禁止：创建/修改任何代码文件、执行代码生成、运行测试
+- [ ] ⛔ 单阶段原则：完成 spec.md 后必须立即停止，等待用户主动触发下一阶段
+- [ ] 即使用户提供代码作为上下文，只用于分析现有实现，不执行任何代码操作
+- [ ] 代码实现将在 `/opsx-apply` 阶段进行
+- [ ] ⛔ 完成本阶段后绝对禁止自动继续执行 design/task 等后续阶段
+
+---
+
+## §7 质量红线自检
+
+写入文档前，逐项确认：
+- [ ] 文档结构完全符合 `openspec-templates/spec.md` 模板
+- [ ] 需求项格式正确（`#### 需求项：`，4个#）
+- [ ] 场景格式正确（`##### 场景：`，5个#）
+- [ ] 每个需求项都有验收标准
+- [ ] 技术契约章节完整（数据模型、接口契约）
+- [ ] 文档末尾包含质量红线检查清单
+- [ ] 100% 覆盖 proposal.md 中该 Capability 的描述
+
+**如有任意一项未满足，重新生成对应章节，直至全部通过。** 自检完成后必须输出结构化自检报告（模板见 `./reference.md`「§7 质量自检报告模板」），未通过项自动修复后重新输出。
+
+---
+
+## Guardrails ⛔ 强制项
+
+- [ ] 必须以 `openspec-templates/spec.md` 为模板基准
+- [ ] spec.md 聚焦【What】，不写 How（留给 design.md）
+- [ ] **需求项格式必须正确**：`####` 需求项、`#####` 场景
+- [ ] 每个需求项必须有清晰的验收标准
+- [ ] 技术契约必须可执行、无歧义
+- [ ] ⛔ **阶段边界**：禁止执行任何代码创建/修改操作
+- [ ] ⛔ **单阶段原则**：完成 spec.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-design`，绝对禁止自动执行 design/task 等后续阶段。每个阶段必须由用户主动触发。

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

@@ -0,0 +1,49 @@
+---
+description: opsx-spec 的详细模板：telemetry 命令、上下文类型表、质量自检报告模板。仅在需要参考详细模板时读取。
+---
+
+# opsx-spec — 详细参考（reference）
+
+> 本文件承载 opsx-spec 的重细节模板：telemetry 命令、§3 上下文类型表、§7 质量自检报告模板。
+> SKILL.md 保留入口骨架与指针；本文件为详细模板来源。
+
+---
+
+## 📊 Telemetry 命令模板（必做，不得跳过）
+
+> 阶段开始：`node skywalk-sdd/log.cjs start --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+---
+
+## §3 上下文类型与用途
+
+| 上下文类型 | 用途 | 如何融入 spec |
+|------------|------|--------------|
+| 需求文档 | 提取验收标准、用户故事 | 转化为需求项和场景 |
+| 代码文件 | 了解现有实现约束 | 纳入技术契约和约束条件 |
+| API 文档 | 接口规范参考 | 对齐数据契约和接口格式 |
+
+---
+
+## §7 质量自检报告模板
+
+自检完成后，**必须**向用户展示结构化的自检报告：
+
+> "### 质量自检结果
+>
+> | 检查项 | 状态 | 说明 |
+> |--------|------|------|
+> | 文档结构符合模板 | ✅/❌ | |
+> | 需求项格式正确（4个#） | ✅/❌ | 共 N 个需求项 |
+> | 场景格式正确（5个#） | ✅/❌ | 共 M 个场景 |
+> | 每个需求项有验收标准 | ✅/❌ | |
+> | 技术契约章节完整 | ✅/❌ | |
+> | 质量红线检查清单 | ✅/❌ | |
+> | 覆盖 proposal.md 描述 | ✅/❌ | |
+> | 使用「必须」强制要求 | ✅/⚠️ | |
+> | 技术选型包含版本 | ✅/⚠️ | |
+>
+> **结论**：全部通过 ✅ / 存在问题需修复 ❌"
+
+**未通过项处理**：若有 ❌ 项，自动修复后重新输出报告，直至全部 ✅。