@hunterzheng/kld-sdd 2.4.19

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

@@ -0,0 +1,162 @@
+---
+name: opsx-archive
+description: "归档变更技能 - 将已结束的 SDD 变更真实移入 archive，并生成最终中文度量报告"
+argument-hint: "[change-name]"
+license: MIT
+compatibility: Requires skywalk-sdd/log.cjs.
+metadata:
+  author: sdd-team
+  version: "3.2"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
+
+> **跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 不要裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请加引号或改成正斜杠。
+> - 不要省略 `--source=opsx-command` 和 `--session-id=<会话ID>`。
+> - 本技能不调用 OpenSpec 自带归档命令；统一使用 SkyWalk-SDD 的 `archive-docs`。
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|---|---|
+| 核心问题 | 变更生命周期结束与度量收口 |
+| 关键输出 | `openspec/changes/archive/<日期>-<change>/`、`openspec/specs/`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.md`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.html`、`openspec/changes/archive/<日期>-<change>/logs/execution-log.md` |
+| 触发时机 | 任务完成、变更取消、变更搁置、或用户要求归档 |
+
+---
+
+## 启动流程
+
+### 1. 确认变更名称并记录阶段开始
+
+如果未提供变更名，运行：
+
+```bash
+openspec list
+```
+
+让用户选择现有变更。确认后记录阶段开始：
+
+```bash
+node skywalk-sdd/log.cjs start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+```
+
+保存 `event_id`。
+
+### 2. 询问归档原因
+
+使用交互问题让用户选择：
+
+> 请选择归档原因：
+> - A. 变更已完成实施
+> - B. 变更已取消
+> - C. 变更已搁置
+> - D. 其他原因
+
+记录为 `<归档原因>`，它会进入 `archive-manifest.json`、archive telemetry 和最终报告。
+
+### 2.5 确认无残留 Apply Worktree（Git 项目）
+
+若项目使用 Apply worktree 隔离，归档前确认：
+
+```bash
+git worktree list
+```
+
+应仅剩主工作区；或 telemetry 中存在 `worktree_finish` + `result=success` 事件。若仍有 `.worktrees/apply-*`，先执行 `node skywalk-sdd/apply-worktree-finish.cjs` 或手工清理。
+
+### 3. 运行 telemetry doctor
+
+```bash
+node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>
+```
+
+如果存在 `severe_issues`，暂停归档并说明必须先修复。`superseded_open_stages` 和 `rework_summary` 只作为返工/重复执行展示，不要求用户人工区分测试回滚或真实研发返工。
+
+### 4. 扫描 tasks 完成状态
+
+```bash
+node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
+```
+
+即使用户选择“变更已完成实施”，未勾选项也不阻断归档。它可能代表任务真实未完成，也可能代表代码已完成但文档未同步；不要猜测，也不要静默忽略。最终必须让 `archive-docs` 将其写入 `archive_result.task_completion` 和报告。
+
+### 5. 一步执行真实归档
+
+执行唯一归档命令：
+
+```bash
+node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reason="<归档原因>" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+```
+
+该命令成功后必须已经完成：
+- 活动目录 `openspec/changes/<name>/` 被移入 `openspec/changes/archive/<日期>-<name>/`。
+- 归档目录写入 `archive-manifest.json`。
+- Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
+- archive 阶段写入 `stage_end`。
+- 未勾选 tasks 被写入 `archive_result.task_completion`。
+- 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md` 及同名 `<name>-report.html`（md+html 双产物，默认归档后 archive 目录，可用 --report-output 自定义）。
+- 执行日志 `openspec/changes/archive/<日期>-<name>/logs/execution-log.md` 随归档整目录迁移（人读审计层）。
+
+如果该命令失败，以失败状态结束 telemetry：
+
+```bash
+node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=failure --summary="归档失败：<失败原因>"
+```
+
+失败时不要输出“归档完成”。
+
+### 6. 输出给用户
+
+成功时只输出真实产物路径：
+
+> 变更 `<name>` 已真实归档。
+> - 归档目录：`openspec/changes/archive/<日期>-<name>/`
+> - 最终报告：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`openspec/changes/archive/<日期>-<name>/reports/<name>-report.html`
+> - 执行日志：`openspec/changes/archive/<日期>-<name>/logs/execution-log.md`
+> - 未勾选任务：X 项，已记录到报告，不阻断归档
+> - 正式 specs：`openspec/specs/`
+
+被 doctor 阻断、真实归档失败或报告生成失败时，不要说“归档完成”。
+
+---
+
+## 可选补录
+
+如用户愿意提供反馈，可补录问卷结果：
+
+```bash
+node skywalk-sdd/log.cjs record --type=survey_result --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="SDD 人工反馈" --details-json="{\"survey_result\":{\"nps\":9,\"cognitive_load\":3,\"spec_fatigue_index\":2,\"satisfaction\":8,\"respondent_role\":\"developer\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
+```
+
+如团队有传统方式工时基线，可补录 baseline：
+
+```bash
+node skywalk-sdd/log.cjs record --type=baseline_record --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="传统工时基线" --details-json="{\"baseline_record\":{\"traditional_hours\":10,\"sdd_hours\":6,\"task_type\":\"feature\",\"baseline_source\":\"manual-estimate\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
+```
+
+---
+
+## Guardrails
+
+- 归档操作执行前必须让用户确认归档原因。
+- 不要调用 OpenSpec 自带归档命令；统一由 `archive-docs` 负责真实归档、阶段结束和报告生成。
+- “完成实施”归档允许 tasks 未全部勾选；未勾选项必须进入 archive details 和最终报告。
+- 最终报告由 `archive-docs` 自动生成（md+html 双产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。
+- 已归档变更不要重复移动；展示已有 archive 目录和 report 路径。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 archive 前后自检时（产物完整性、状态标记、归档迁移）。

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

@@ -0,0 +1,33 @@
+---
+name: opsx-archive-checklist
+description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive 自检时读取"
+---
+
+# opsx-archive 自检清单
+
+> 仅在执行 archive 前后做产物/日志自检时读取。日常归档流程见 `SKILL.md`。
+
+## A. 归档前自检
+
+- [ ] `node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>` 无 `severe_issues`（`superseded_open_stages`/`rework_summary` 仅展示，不阻断）
+- [ ] `node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>` 已运行；未勾选项将进入 `archive_result.task_completion`，不阻断归档但必须如实记录
+- [ ] `openspec/changes/<变更名称>/logs/execution-log.md` 各阶段条目齐全：propose/spec/design/task/check/apply/test/archive 的 `stage_start`/`stage_end` 闭环
+- [ ] execution-log 状态标记规范：成功 `✅OK`、部分 `🟡WARN`、失败 `❌FAIL`；未闭环阶段已修复或标记 partial
+- [ ] 无残留 Apply worktree（`git worktree list` 仅主工作区，或 telemetry 存在 `worktree_finish`+success 事件）
+
+## B. 归档后自检
+
+- [ ] 归档目录 `openspec/changes/archive/<日期>-<变更名称>/` 存在
+- [ ] `openspec/changes/archive/<日期>-<变更名称>/archive-manifest.json` 存在
+- [ ] 最终报告 `openspec/changes/archive/<日期>-<变更名称>/reports/<变更名称>-report.md` 存在且含「归档结果」段
+- [ ] `reports/<变更名称>-report.md` 与 `reports/<变更名称>-report.html` 都已生成（md+html 双产物）
+- [ ] html 报告含 `SDD 效果度量报告` 标题与各度量章节（执行摘要/效率/质量/过程/归档结果/说明）
+- [ ] 执行日志 `openspec/changes/archive/<日期>-<变更名称>/logs/execution-log.md` 随 change 整目录迁移到 archive（含 archive 阶段 stage_start+stage_end+✅OK）
+- [ ] 正式 specs 同步到 `openspec/specs/<capability>/spec.md`
+- [ ] `skywalk-sdd/reports/` 不再写入新报告（最终报告落 archive 目录）
+
+## C. 状态标记规范
+
+- execution-log.md 用 `✅OK` / `🟡WARN` / `❌FAIL` 三态标记
+- 未闭环阶段必须修复或标记 `partial`，不得静默留空
+- 报告「归档结果」段如实反映 `task_completion.incomplete` 数量

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

@@ -0,0 +1,197 @@
+---
+name: opsx-check
+description: "质量检查技能 - 验证文档完整性、一致性、算法正确性及可执行性"
+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）质量检查专家。激活本技能后，你将对文档链执行全面的质量门禁检查。
+
+> **⚠️ 阶段边界约束**
+>
+> 当前处于 **Check（检查）阶段**：
+> - ✅ **允许**：读取并检查文档、读取代码作为验证参考
+> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
+>
+> 即使检查发现代码相关问题，也只记录在检查报告中，**不自动修复代码**。
+> 代码修复将在 `/opsx-apply` 阶段进行。
+
+
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 检查报告生成后，必须先记录结构化检查结果：`node skywalk-sdd/log.cjs record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
+> - `check_result` 记录成功后，才允许阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="摘要"`
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | 文档链质量是否达标 |
+| 关键输出 | 检查报告（通过/警告/失败） |
+| 检查维度 | 完整性、一致性、算法正确性、可执行性 |
+| 上游依赖 | proposal → specs → design → tasks 全文档链 |
+
+---
+
+## 启动流程
+
+### 1. 【交互引导】确认变更名称
+
+若未提供，列出当前所有变更供用户选择：
+```bash
+openspec list
+```
+
+若变更不存在，提示用户先运行 `/opsx-propose <name>` 创建变更。
+
+### 2. 读取完整文档链
+
+按顺序读取以下文档（如存在）：
+- `proposal.md`（或 propose.md，兼容旧格式）（业务意图）
+- `specs/<capability>/spec.md`（技术契约）
+- `specs/<capability>/design.md`（实现方案）
+- `specs/<capability>/tasks.md`（或 task.md，兼容旧格式）（任务拆解）
+
+### 3. 【上下文加载】识别并读取用户提供的文件
+
+**自动识别上下文文件**：
+若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
+
+**上下文类型与检查维度**：
+| 上下文类型 | 检查用途 | 对应检查维度 |
+|------------|---------|----------|
+| 需求文档 | 验证 spec 是否完整覆盖需求 | 完整性 |
+| 代码文件 | 验证 design 可行性、锚点准确性 | 可执行性 |
+| 算法文档 | 验证算法设计正确性 | 算法正确性 |
+
+### 4. 执行四维质量检查
+
+#### 4.1 完整性检查
+
+- [ ] proposal.md 存在且包含完整章节
+- [ ] 每个 Capability 都有 spec.md
+- [ ] 每个 spec.md 都有对应 design.md
+- [ ] 每个 design.md 都有对应 tasks.md
+- [ ] 所有文档符合模板结构
+
+#### 4.2 一致性检查
+
+- [ ] proposal.md 的能力列表与 specs/ 目录一致
+- [ ] spec.md 的需求项在 design.md 中 100% 被覆盖
+- [ ] design.md 的设计点在 tasks.md 中 100% 被拆解
+- [ ] 跨文档引用路径正确
+
+#### 4.3 算法正确性检查
+
+- [ ] 数据流转逻辑无矛盾
+- [ ] 异常处理覆盖所有边界
+- [ ] 性能设计满足 spec 约束
+
+#### 4.4 可执行性检查
+
+- [ ] tasks.md 中每个任务颗粒度 ≤ 5 分钟
+- [ ] DAG 无循环依赖
+- [ ] 所有外部依赖已明确状态
+- [ ] 代码锚点存在且可访问
+
+#### 4.5 任务完成状态检查（实现后 / 归档前）
+
+`task` 阶段允许 `tasks.md` 出现未完成项；这只是计划状态。但如果当前变更已经进入 apply 之后，或本次 check 发现实现代码、测试报告、`build_result/test_result/task_update/conformance_review` 等实施证据，必须检查任务勾选状态：
+
+```bash
+node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
+```
+
+判定规则：
+- 尚未进入 apply：未勾选任务只作为计划状态展示，不计入错误。
+- 已进入 apply/test/archive readiness：未勾选项至少记为 warning。
+- 若用户准备归档“变更已完成实施”：未勾选项仍只作为 warning/待确认事实展示，不阻断归档。
+- Check 阶段只读，不自动勾选；报告中必须说明这是“任务可能已执行但文档未同步”或“任务真实未完成”的待确认项。
+
+### 5. 输出检查报告
+
+> "📋 **质量检查报告**
+> 
+> | 维度 | 状态 | 详情 |
+> |------|------|------|
+> | 完整性 | ✅/⚠️/❌ | [具体问题] |
+> | 一致性 | ✅/⚠️/❌ | [具体问题] |
+> | 算法正确性 | ✅/⚠️/❌ | [具体问题] |
+> | 可执行性 | ✅/⚠️/❌ | [具体问题] |
+>
+> **总体结果**：✅ 通过 / ⚠️ 有警告 / ❌ 未通过
+>
+> **建议操作**：
+> - [具体修复建议及对应命令]"
+
+### 5.1 【Telemetry 必做】记录结构化检查结果
+
+输出检查报告后，必须把检查结果转换为 `check_result` 事件，并在 `stage_end` 之前执行成功。禁止只记录阶段结束。
+
+字段口径：
+- `total`: 本次检查项总数。
+- `errors`: 必须修复的问题数。
+- `warnings`: 建议修复的问题数。
+- `suggestions`: 可选优化建议数。
+- `fixed_before_apply`: 进入 apply 前已通过或已确认满足质量门禁的检查项数。
+- `consistency_score`: 跨文档一致性评分，取值 0-1；无法评分时填 `null`。
+- `categories`: 至少包含 `completeness`、`consistency`、`executability`。
+- `task_completion`: 从 `tasks-status` 输出整理而来；未进入 apply 时 `checked_for_archive_readiness=false`。
+
+在终端执行（必须成功）：
+```bash
+node skywalk-sdd/log.cjs record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
+```
+
+若当前已有实现代码，并且能够验证 spec 断言，还应记录 `conformance_review`（用于 Q1 规约符合度）：
+```bash
+node skywalk-sdd/log.cjs record --type=conformance_review --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="规约符合度人工确认" --details-json="{\"conformance_review\":{\"method\":\"llm-as-judge+manual\",\"manual_confirmed\":true,\"assertions\":[{\"id\":\"ASSERT-001\",\"description\":\"规约中的可验证断言\",\"judge_status\":\"matched\",\"human_status\":\"matched\",\"evidence\":\"代码、测试或文档证据摘要\",\"files\":[],\"notes\":\"\"}]}}"
+```
+
+### 6. 【交互引导】根据结果引导下一步
+
+**全部通过**：
+> "✅ 质量检查通过！建议下一步：
+> - A. 运行 `/opsx-apply` 开始实施
+> - B. 再次确认某个文档细节"
+
+**有问题**：
+> "❌ 发现 [N] 个问题需要修复：
+> - 问题 1：[描述] → 建议运行 `/opsx-spec` 修复
+> - 问题 2：[描述] → 建议运行 `/opsx-design` 修复
+>
+> 请选择：
+> - A. 逐个修复（引导到对应命令）
+> - B. 忽略警告继续"
+
+---
+
+## Guardrails
+
+- Check 是**只读检查**操作，不修改任何文档内容
+- 发现问题时推荐修复命令但不自动执行
+- 检查报告必须结构化、可操作
+- 支持增量检查（只检查指定 Capability）
+- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在 check 阶段日志自检时（check_result 记录、execution-log 状态标记、字段口径）。

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

@@ -0,0 +1,35 @@
+---
+name: opsx-check-checklist
+description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读取"
+---
+
+# opsx-check 自检清单
+
+> 仅在 check 阶段做日志/结果自检时读取。日常检查流程见 `SKILL.md`。
+
+## A. check_result 事件记录
+
+- [ ] `check_result` 事件已记录：`skywalk-sdd/events/<变更名称>/*.jsonl` 含 `type=check_result` 条目
+- [ ] `openspec/changes/<变更名称>/logs/execution-log.md` 含 check 阶段条目（`stage_start` / `check_result` / `stage_end`）
+- [ ] `check_result` 在 `stage_end` 之前记录成功（禁止只记录阶段结束）
+
+## B. check_result 字段口径
+
+- [ ] `total`: 本次检查项总数（非 0 占位）
+- [ ] `errors`: 必须修复的问题数
+- [ ] `warnings`: 建议修复的问题数
+- [ ] `suggestions`: 可选优化建议数
+- [ ] `fixed_before_apply`: 进入 apply 前已通过/已确认满足门禁的检查项数
+- [ ] `consistency_score`: 跨文档一致性评分 0-1；无法评分填 `null`
+- [ ] `categories`: 至少含 `completeness` / `consistency` / `executability`
+- [ ] `task_completion`: 从 `tasks-status` 整理；未进入 apply 时 `checked_for_archive_readiness=false`
+
+## C. execution-log 状态标记
+
+- [ ] execution-log.md 状态标记规范：`✅OK` / `🟡WARN` / `❌FAIL`
+- [ ] check 阶段结果与 `check_result.result` 一致（success→✅OK / partial→🟡WARN / failure→❌FAIL）
+
+## D. 检查报告四维
+
+- [ ] 完整性、一致性、算法正确性、可执行性四维均已输出
+- [ ] 报告问题对应修复建议（spec/design/task）

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

@@ -0,0 +1,166 @@
+---
+name: opsx-design
+description: "技术设计文档技能 - 针对单一 Capability 创建局部技术实现方案"
+argument-hint: "[change-name] [capability-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** 创建 **design.md** 文档。
+
+> **⚠️ 阶段边界约束**
+>
+> 当前处于 **Design（设计）阶段**：
+> - ✅ **允许**：创建/编辑 design.md 文档、读取代码/文档作为上下文分析
+> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
+> - ⛔ **单阶段原则**：完成 design.md 后**必须立即停止**，等待用户主动触发下一阶段
+>
+> 代码实现将在 `/opsx-apply` 阶段进行。
+> **完成本阶段后，绝对禁止自动继续执行 task 等后续阶段。**
+> 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
+
+> **⚠️ 渐进式上下文加载原则**
+>
+> - 本技能针对**单一 Capability** 执行设计
+> - **输入路径**：`changes/<name>/specs/<capability>/spec.md`
+> - **输出路径**：`changes/<name>/specs/<capability>/design.md`
+> - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design
+
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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 命令模板」。
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | How - 单一 Capability 如何实现 |
+| 关键输出 | specs/<capability>/design.md |
+| 上游依赖 | overview.md → proposal.md → 当前 capability 的 spec.md |
+| 下游依赖 | tasks.md |
+
+---
+
+## 启动流程
+
+### 1. 【交互引导】确认变更名称和 Capability
+
+**步骤 1a - 确认变更名称**：
+若未提供 change-name，列出当前所有变更供用户选择：
+```bash
+openspec list
+```
+
+**步骤 1b - 确认 Capability**：
+若未提供 capability-name，读取 `proposal.md` 中定义的 Capabilities 列表：
+
+使用 **AskUserQuestion** 让用户选择要设计的 Capability：
+> "请选择要设计的 Capability：
+> - A. `user-auth`（用户认证）- spec.md ✅ 已就绪
+> - B. `data-export`（数据导出）- spec.md ✅ 已就绪
+> - C. `notification`（通知）- spec.md ❌ 未创建"
+
+**路径确认**：
+> "📍 当前操作目标：
+> - **变更**：`<change-name>`
+> - **Capability**：`<capability-name>`
+> - **输入**：`changes/<name>/specs/<capability>/spec.md`
+> - **输出**：`changes/<name>/specs/<capability>/design.md`"
+
+### 2. 【上下文加载】识别并读取用户提供的文件
+
+**自动识别上下文文件**：若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
+
+> 上下文类型（代码文件 / 架构文档 / 数据库 Schema）与用途见 `./reference.md`「§2 上下文类型与用途」。
+
+**【可选】业务知识库检索**：
+设计涉及 MM/CO 领域概念且 spec 未充分定义时，可调用 **opsx-knowledge** skill。
+仅作背景参考，不得覆盖 spec；内网不可达时跳过并继续 design。
+
+### 3. 渐进式上下文加载
+
+> ⛔ 必须严格按 overview.md → proposal.md → 当前 capability spec.md 顺序加载；隔离红线：禁止读取其他 Capability 的文档。**完整层级图见 `./reference.md`「§3 渐进式上下文加载层级图」**。
+
+### 4. 【关键步骤】读取本地模板文件
+
+**必须先读取** `openspec-templates/design.md` 作为文档结构模板：
+```
+使用 Read 工具读取：openspec-templates/design.md
+```
+
+**【重要】不得使用 `openspec instructions` 返回的简化 template，必须以 `openspec-templates/design.md` 为准。**
+
+### 5. 【交互引导】代码锚点分析
+
+**主动询问用户现有代码情况**：
+> "🔍 **代码锚点分析**：
+> 1. 是否有现有代码需要修改？请提供文件路径
+> 2. 是否需要我读取项目中的相关代码？
+> 3. 是否有第三方库/框架约束？"
+
+读取用户指定的代码文件，分析：
+- 现有类/方法结构
+- 扩展点和修改点
+- 接口约束
+
+### 6. 创建 design.md
+
+**以 `openspec-templates/design.md` 的结构为骨架**，填充内容。
+
+**输出路径**：`changes/<name>/specs/<capability>/design.md`
+
+### 7. 质量红线自检
+
+> 写入文档前逐项确认，完整 7 项自检清单见 `./checklist.md`「§7 质量红线自检」。如有任意一项未满足，重新生成对应章节，直至全部通过。
+
+### 8. 【交互引导】确认文档并输出结果
+
+生成文档后，向用户展示概要：
+> "已生成 design.md，概要如下：
+> - Capability：[name]
+> - 核心模块：[模块列表]
+> - 设计模式：[使用的设计模式]
+> - 预估复杂度：[高/中/低]
+>
+> 请确认：
+> - A. 确认无误，继续创建 tasks.md
+> - B. 需要修改设计方案
+> - C. 补充更多代码上下文"
+
+最终输出：
+- 文档路径
+- 下一步提示："运行 `/opsx-task <name> <capability>` 创建任务拆解文档"
+
+---
+
+## Guardrails
+
+> 完整 ⛔ 强制项勾选清单见 `./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 等后续阶段。每个阶段必须由用户主动触发。