kld-sdd 2.4.19 → 2.5.1

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-rules/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: opsx-rules
+description: "规则生成技能 - 扫描项目生成 5 主题 Agent 规则，或对比现有规则输出更新建议"
+argument-hint: "[generate|review] [--agent <id>]"
+license: MIT
+compatibility: 无外部依赖；opencode 接线需项目存在或可创建 opencode.json。
+metadata:
+  author: sdd-team
+  version: "1.0"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+你是一个 SDD 项目规则生成与维护专家。激活本技能后，你将扫描项目事实，为已部署的 Agent 生成或审查规则文件。
+
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - ${SHELL_GUIDANCE}
+> - **本技能不写入 SkyWalk Telemetry**（与 `opsx-knowledge` 同属辅助技能，不走 `log.cjs start/end`）。
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | 各 Agent 的规则文件在哪里、格式如何、是否与项目事实一致 |
+| 关键输出 | generate：按 Agent 落位的 5 主题规则文件；review：更新建议表 |
+| 操作类型 | generate 写入新规则；review 默认只读，确认后才写入 |
+
+---
+
+## 启动流程
+
+### 1. 检测已部署 Agent 与运行模式
+
+扫描以下目录，记录存在的 Agent（`--agent <id>` 可过滤为单个）：
+
+| Agent id | 检测路径 |
+|----------|----------|
+| cursor | `.cursor/` |
+| claude | `.claude/` |
+| codebuddy | `.codebuddy/` |
+| qoder | `.qoder/` |
+| opencode | `.opencode/` |
+| kunlunzhima | `.kunlunzhima/` |
+| workbuddy | `.workbuddy/` |
+| codex | `.agents/` |
+
+**模式判定**（参数优先，否则自动）：
+- 显式 `generate` → 生成模式
+- 显式 `review` → 审查模式
+- 未指定：任一已选 Agent 的规则目录已有文件 → **review**；否则 → **generate**
+
+规则目录与格式详见 `reference.md` 落位矩阵。**KunlunZhima 注意**：目录是 `.kunlunzhima/.rules/`（点前缀），不是 `rules/`。
+
+### 2. 轻量项目扫描（generate 与 review 共用，不落盘）
+
+借鉴 codebase-map 三视角，只读扫描：
+
+| 视角 | 探测目标 |
+|------|----------|
+| STACK | `package.json` / `pom.xml` / `pyproject.toml` / `go.mod` / `Cargo.toml`；构建命令 |
+| STRUCTURE | 顶层目录职责、入口文件（`bin/`、`src/`、`lib/`、`app/`） |
+| CONVENTIONS | ESLint/Prettier/Ruff 配置；`test/` 目录与框架；`git log --oneline -20` 提交风格 |
+
+扫描结果作为 5 主题规则的正文依据，禁止编造与仓库不符的内容。
+
+### 3a. generate 模式
+
+对 Step 1 检测到的每个 Agent：
+
+1. 读取 `reference.md` 中该 Agent 的 `rulesDir` / `rulesFormat` / `rulesWiring`
+2. 按 5 主题（architecture / coding-style / testing / database-safety / git-commit）生成内容
+3. 按格式模板写入规则文件（见 `reference.md`）
+4. **已有同名文件 → 跳过**，提示用户改用 review 模式
+5. **接线**（仅 wiring ≠ none 的 Agent）：
+   - `opencode-config`：保守合并 `opencode.json` 的 `instructions` 数组（只增不删）；优先指向已有 `.claude/rules/*.md`
+   - `agents-md`：在 `AGENTS.md` 用 `<!-- kld-sdd-rules:start/end -->` marker 追加/替换规则章节
+   - `context-file`：在 WorkBuddy 上下文文件加一行规则目录索引（见 reference.md）
+
+### 3b. review 模式
+
+1. 读取各 Agent 现有规则文件
+2. 与 Step 2 扫描事实对比，输出建议表：
+
+| 文件 | 主题 | 建议类型 | 依据 |
+|------|------|----------|------|
+| （路径） | architecture 等 | 新增 / 修订 / 过期 | 具体扫描证据 |
+
+3. 使用 **AskUserQuestion** 让用户确认要应用的项
+4. **未经确认不写文件**
+
+### 4. 输出报告
+
+```markdown
+## opsx-rules 执行报告
+
+| Agent | 模式 | 写入/建议文件数 | 接线 |
+|-------|------|----------------|------|
+| ... | generate/review | N | 无/opencode.json/AGENTS.md |
+
+### 详情
+- （列出路径与操作摘要）
+
+### 后续
+- 规则内容可手工微调；再次变更后运行 `/opsx-rules review`
+- OpenCode 用户：确认 `opencode.json` instructions 已包含规则路径
+```
+
+---
+
+## Guardrails
+
+- **review 模式未经用户确认不写文件**
+- **generate 模式不覆盖已有同名规则文件**（存在即跳过 + 提示 review）
+- **opencode.json 合并只增不删**；写前提示用户备份已有配置
+- **AGENTS.md 追加用 managed marker**，存在 marker 则整块替换（幂等）
+- **规则内容来自扫描证据**，禁止编造项目不存在的框架或命令
+
+---
+
+## 渐进披露
+
+- **Read `reference.md`** — 落位矩阵、格式模板、5 主题骨架、接线示例
+- **Read `checklist.md`** — generate/review 前后检查项

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

@@ -0,0 +1,27 @@
+# opsx-rules 检查清单
+
+## generate 前
+
+- [ ] 工作目录为项目根
+- [ ] 已检测存在的 Agent 目录
+- [ ] 已完成 Step 2 轻量扫描（STACK / STRUCTURE / CONVENTIONS）
+- [ ] 目标 Agent 规则目录无同名文件（有则改 review）
+
+## generate 写后
+
+- [ ] 5 主题文件均已写入（或按 Agent 格式合并）
+- [ ] frontmatter 符合 reference.md 模板
+- [ ] KunlunZhima 路径为 `.kunlunzhima/.rules/` 而非 `rules/`
+- [ ] opencode.json / AGENTS.md 接线已完成（若 wiring 非 none）
+- [ ] 未覆盖用户已有非受管文件
+
+## review 前
+
+- [ ] 已读取现有规则文件
+- [ ] 已完成 Step 2 扫描
+- [ ] 建议表已输出（文件 / 主题 / 类型 / 依据）
+
+## review 写后
+
+- [ ] 用户已通过 AskUserQuestion 确认
+- [ ] 仅写入确认项

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

@@ -0,0 +1,124 @@
+# opsx-rules 参考 — 落位矩阵与格式模板
+
+> **权威源说明**：本文件是 skill **运行时**的落位矩阵真相源（部署到目标项目后无法 `require` kld-sdd 的 `lib/`）。`lib/tool-profiles.js` 中的 `rulesDir` / `rulesFormat` / `rulesWiring` 为 **init 契约与测试断言**；变更时须与本表同步，以本表为准写入规则文件。
+
+## 落位矩阵
+
+| Agent | rulesDir | 格式 | frontmatter | 原生加载 | 接线 |
+|-------|----------|------|-------------|----------|------|
+| cursor | `.cursor/rules/` | `.mdc` | description / globs / alwaysApply | ✅ | 无 |
+| claude | `.claude/rules/` | `.md` | 可选 paths（glob 列表） | ✅ | 无 |
+| codebuddy | `.codebuddy/rules/` | `.md` | 无 | ✅ | 无 |
+| qoder | `.qoder/rules/` | `.md` | 可选 trigger | ✅ | 无 |
+| kunlunzhima | **`.kunlunzhima/.rules/`** | `.mdc` | description / alwaysApply / enabled / updatedAt / provider | ✅ | 无 |
+| opencode | 无独立目录 | `.md` | 无 | ❌ | `opencode.json` instructions |
+| codex | 无独立目录 | — | — | ✅（读 AGENTS.md） | AGENTS.md managed marker |
+| workbuddy | `.workbuddy/rules/` | `.md` | 无 | ⚠️ 待验证 | 上下文文件索引行兜底 |
+
+> **KunlunZhima 证据**：样例目录 `.kunlunzhima/.rules/*.mdc`，frontmatter 含 IDE 管理字段 `enabled`、`updatedAt`、`provider`（无 `globs`）。
+
+## 格式模板
+
+### mdc（Cursor）
+
+```markdown
+---
+description: <一句话描述>
+globs:
+alwaysApply: true
+---
+
+<正文>
+```
+
+### mdc-kunlun（KunlunZhima）
+
+```markdown
+---
+description: <一句话描述>
+alwaysApply: true
+enabled: true
+updatedAt: <ISO8601 生成时间>
+provider:
+---
+
+<正文>
+```
+
+### md + paths（Claude Code，可选按路径触发）
+
+```markdown
+---
+paths:
+  - "src/**/*.ts"
+---
+
+<正文>
+```
+
+无 paths 时 Claude 会话启动即加载。
+
+### md + trigger（Qoder，可选）
+
+```markdown
+---
+trigger: always_on
+---
+
+<正文>
+```
+
+### 纯 md（CodeBuddy / WorkBuddy）
+
+```markdown
+<正文>
+```
+
+## 5 主题内容骨架
+
+| 主题 | 文件名 | 扫描依据 | 生成要点 |
+|------|--------|----------|----------|
+| 架构规范 | `architecture` | 目录分层、模块边界、入口 | 分层约定、禁止循环依赖、新代码落位 |
+| 编码规范 | `coding-style` | 语言、lint、缩进 | 命名、缩进、注释语言、CommonJS/ESM |
+| 测试约定 | `testing` | test 目录、框架 | 测试命令、命名、TDD 期望 |
+| 数据安全 | `database-safety` | ORM/迁移目录 | 无 DB 时降级为「禁止危险文件操作/敏感数据提交」 |
+| Git 提交 | `git-commit` | git log 风格、CI | 提交前确认、message 风格、禁止 force push |
+
+## OpenCode 接线
+
+优先复用已有 `.claude/rules/`：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".claude/rules/*.md"]
+}
+```
+
+无 Claude 规则时，写入 `.opencode/rules/*.md` 并 instructions 指向该路径。合并：已有 `instructions` 数组去重追加，其他键不动。
+
+## Codex / AGENTS.md 接线
+
+```markdown
+<!-- kld-sdd-rules:start -->
+## 项目规则
+
+### 架构
+...
+
+### 编码
+...
+<!-- kld-sdd-rules:end -->
+```
+
+存在 marker 则整块替换，幂等。
+
+## WorkBuddy 兜底
+
+写入 `.workbuddy/rules/*.md`，并在项目上下文文件（若存在）追加：
+
+```markdown
+项目规则见 `.workbuddy/rules/` 目录。
+```
+
+验证：运行 CodeBuddy `/memory` 或查官方 docs。

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-spec
 description: "技术契约文档技能 - 为每个能力创建 spec.md，定义业务场景与技术规范"
 argument-hint: "[change-name] [上下文文件...]"
@@ -26,16 +26,14 @@ allowed-tools:
 > 即使用户提供了代码作为上下文，也只用于分析现有实现，**不执行任何代码操作**。
 > 代码实现将在 `/opsx-apply` 阶段进行。
 > **完成本阶段后，绝对禁止自动继续执行 design/task 等后续阶段。**
-
+> 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
 > **🖥️ 跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
-> **📊 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="摘要"`
+> **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 
 ---
 
@@ -48,7 +46,7 @@ allowed-tools:
 | 上游依赖 | proposal.md（能力列表） |
 | 下游依赖 | design.md → tasks.md |
 
-**【文件结构】**：每个 capability 生成一个独立的 spec 文件：
+**【文件结构】**（Full 模式，默认）：每个 capability 生成一个独立的 spec 文件：
 ```
 openspec/changes/<name>/
 ├── proposal.md
@@ -62,10 +60,27 @@ openspec/changes/<name>/
 └── tasks.md
 ```
 
+**【文件结构】**（Simple 模式，proposal.md frontmatter `mode: simple`）：文档落变更根目录，不创建 specs/ 子目录：
+```
+openspec/changes/<name>/
+├── proposal.md
+├── spec.md              # 单一 spec 文件
+├── design.md
+└── tasks.md
+```
+
 ---
 
 ## 启动流程
 
+### 0. 【S1 模式检测】读取 proposal.md mode
+
+读取当前变更的 `proposal.md` frontmatter，提取 `mode` 字段：
+- `mode: simple` → Simple 模式（文档落变更根目录）
+- `mode: full` 或未设置 → Full 模式（默认，文档落 specs/<capability>/）
+
+Simple 模式下跳过 Capability 选择，直接在变更根目录创建 `spec.md`。
+
 ### 1. 【交互引导】确认变更名称
 
 若未提供，列出当前所有变更供用户选择：
@@ -88,15 +103,9 @@ openspec list
 
 ### 3. 【上下文加载】识别并读取用户提供的文件
 
-**自动识别上下文文件**：
-若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
+**自动识别上下文文件**：若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
 
-**上下文类型与用途**：
-| 上下文类型 | 用途 | 如何融入 spec |
-|------------|------|--------------|
-| 需求文档 | 提取验收标准、用户故事 | 转化为需求项和场景 |
-| 代码文件 | 了解现有实现约束 | 纳入技术契约和约束条件 |
-| API 文档 | 接口规范参考 | 对齐数据契约和接口格式 |
+> 上下文类型（需求文档 / 代码文件 / API 文档）与用途见 `./reference.md`「§3 上下文类型与用途」。
 
 **【可选】业务知识库检索**：
 术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。
@@ -134,40 +143,19 @@ openspec list
 - 需求项使用 `####`（4个#）
 - 场景使用 `#####`（5个#）
 
-### 7. 质量红线自检
-
-写入文档前，逐项确认：
-- [ ] 文档结构完全符合 `openspec-templates/spec.md` 模板
-- [ ] 需求项格式正确（`#### 需求项：`，4个#）
-- [ ] 场景格式正确（`##### 场景：`，5个#）
-- [ ] 每个需求项都有验收标准
-- [ ] 技术契约章节完整（数据模型、接口契约）
-- [ ] 文档末尾包含质量红线检查清单
-- [ ] 100% 覆盖 proposal.md 中该 Capability 的描述
+### 6.5 【Node 版本约束来源校验】
 
-**如有任意一项未满足，重新生成对应章节，直至全部通过。**
+若 spec.md 中声明了 Node 版本约束（如 `>=14`、`>=18` 等），必须在该需求项或 proposal.md 中**声明来源**：
 
-**【必须输出】质量自检报告**：
+- 来源可为：`package.json` 的 `engines.node`、官方运行时要求、上游框架最低版本等。
+- 若 proposal.md 未声明来源且 spec.md 新增了 Node 版本约束 → 提示用户确认：「spec.md 中 Node 版本约束 `<version>` 未在 proposal.md 声明来源，请确认依据（package.json/运行时/框架要求），避免版本约束无追溯。」
+- 用户确认后在 spec.md 需求项备注来源，或回补 proposal.md 的约束条件章节。
 
-自检完成后，**必须**向用户展示结构化的自检报告：
+> 目的：避免 spec 凭空写入 Node 版本约束而无上下游依据，导致契约不可追溯。
 
-> "### 质量自检结果
->
-> | 检查项 | 状态 | 说明 |
-> |--------|------|------|
-> | 文档结构符合模板 | ✅/❌ | |
-> | 需求项格式正确（4个#） | ✅/❌ | 共 N 个需求项 |
-> | 场景格式正确（5个#） | ✅/❌ | 共 M 个场景 |
-> | 每个需求项有验收标准 | ✅/❌ | |
-> | 技术契约章节完整 | ✅/❌ | |
-> | 质量红线检查清单 | ✅/❌ | |
-> | 覆盖 proposal.md 描述 | ✅/❌ | |
-> | 使用「必须」强制要求 | ✅/⚠️ | |
-> | 技术选型包含版本 | ✅/⚠️ | |
->
-> **结论**：全部通过 ✅ / 存在问题需修复 ❌"
+### 7. 质量红线自检
 
-**未通过项处理**：若有 ❌ 项，自动修复后重新输出报告，直至全部 ✅。
+> 写入文档前逐项确认，完整 7 项自检清单见 `./checklist.md`「§7 质量红线自检」。自检完成后**必须**输出结构化自检报告（模板见 `./reference.md`「§7 质量自检报告模板」），未通过项自动修复后重新输出，直至全部 ✅。
 
 ### 8. 确认文档并输出结果
 
@@ -190,10 +178,18 @@ openspec list
 
 ## Guardrails
 
-- **必须以 `openspec-templates/spec.md` 为模板基准**
-- spec.md 聚焦【What】，不写 How（留给 design.md）
-- **需求项格式必须正确**：`####` 需求项、`#####` 场景
-- 每个需求项必须有清晰的验收标准
-- 技术契约必须可执行、无歧义
-- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
-- **⛔ 单阶段原则：完成 spec.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx-design`，**绝对禁止自动执行 design/task 等后续阶段**。每个阶段必须由用户主动触发。
+> 完整 ⛔ 强制项勾选清单见 `./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 描述 | ✅/❌ | |
+> | 使用「必须」强制要求 | ✅/⚠️ | |
+> | 技术选型包含版本 | ✅/⚠️ | |
+>
+> **结论**：全部通过 ✅ / 存在问题需修复 ❌"
+
+**未通过项处理**：若有 ❌ 项，自动修复后重新输出报告，直至全部 ✅。