openspec-sdd-e2e-kit 0.1.0

package/kit/.codex/skills/openspec-continue-change/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: openspec-continue-change
+description: 继续推进一个 OpenSpec 变更，创建下一个 artifact。适用于用户想继续某个变更、生成下一份 artifact 或推进当前工作流时。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+  projectOverlay: "sdd-e2e"
+---
+
+继续处理一个变更，并创建下一个 artifact。
+
+**输入**：可以指定变更名称。如果未指定，先尝试从对话上下文推断；如果含糊或存在歧义，必须让用户从可用变更中选择。
+
+**步骤**
+
+1. **如果未提供变更名称，让用户选择**
+
+   运行 `openspec list --json` 获取可用变更，按最近修改时间排序。然后使用 **AskUserQuestion tool** 让用户选择要继续处理的变更。
+
+   展示最近修改的前 3-4 个变更作为选项，包含：
+   - 变更名称
+   - Schema（如果存在 `schema` 字段则使用该值，否则显示 `"spec-driven"`）
+   - 状态，例如 `"0/5 tasks"`、`"complete"`、`"no tasks"`
+   - 最近修改时间（来自 `lastModified` 字段）
+
+   将最近修改的变更标记为 "(Recommended)"，因为它最可能是用户想继续的对象。
+
+   **重要**：不要猜测或自动选择变更，始终让用户选择。
+
+2. **检查当前状态**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   解析 JSON 以理解当前状态。响应包含：
+   - `schemaName`：当前使用的工作流 schema，例如 `"spec-driven"`
+   - `artifacts`：artifact 数组，每个 artifact 有状态（`"done"`、`"ready"`、`"blocked"`）
+   - `isComplete`：布尔值，表示所有 artifact 是否已完成
+
+   如果 `openspec/changes/<name>/.openspec.yaml` 声明 `schema: sdd-e2e`，同时读取 `openspec/schemas/sdd-e2e/schema.yaml` 和 `openspec/sdd-e2e-flow.md`，并按项目级生命周期理解 artifact 顺序：proposal -> specs -> features -> test-cases -> design -> tasks -> phase acceptance -> final acceptance -> archive。
+
+3. **根据状态执行**
+
+   ---
+
+   **如果所有 artifact 都已完成（`isComplete: true`）**：
+   - 告知用户已经完成
+   - 展示最终状态，包括所使用的 schema
+   - 如果是 `schema: sdd-e2e`，明确说明：OpenSpec artifact 已完成不等于 SDD final acceptance 已通过；归档前仍需 `pnpm sdd:acceptance <name>` 通过
+   - 建议："所有 artifact 已创建，可以开始实现该变更，或在验收通过后归档。"
+   - 停止
+
+   ---
+
+   **如果存在可创建的 artifact**（status 中有 `status: "ready"` 的 artifact）：
+   - 从 status 输出中选择第一个 `status: "ready"` 的 artifact
+   - 获取创建说明：
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+   - 解析 JSON。关键字段包括：
+     - `context`：项目背景（给你的约束，不要写入输出文件）
+     - `rules`：artifact 级规则（给你的约束，不要写入输出文件）
+     - `template`：输出文件应使用的结构
+     - `instruction`：schema 指南
+     - `outputPath`：应写入的位置
+     - `dependencies`：需要读取的已完成依赖 artifact
+   - **创建 artifact 文件**：
+     - 读取所有已完成依赖文件作为上下文
+     - 使用 `template` 作为结构，并填充各节
+     - 写作时遵守 `context` 和 `rules`，但不要把它们复制进文件
+     - 写入 instructions 指定的输出路径
+   - 展示创建了什么，以及现在解锁了什么
+   - 对 `schema: sdd-e2e`，如果下一个 ready artifact 是 `final-acceptance`，但 tasks 尚未全部完成或缺少 phase report，不要提前生成 `acceptance-coverage.md`；提示先进入 apply 阶段
+   - 创建一个 artifact 后停止
+
+   ---
+
+   **如果没有 artifact ready（全部 blocked）**：
+   - 这在合法 schema 中不应该发生
+   - 展示状态，并建议检查配置或依赖问题
+
+4. **创建 artifact 后展示进度**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**输出**
+
+每次调用后展示：
+- 本次创建了哪个 artifact
+- 当前使用的 schema 工作流
+- 当前进度（N/M 已完成）
+- 现在解锁了哪些 artifact
+- 在进入下一个 artifact 前，是否已创建或建议创建项目验证 artifact
+- 提示语："要继续的话，直接让我继续，或告诉我下一步怎么做。"
+
+**Artifact 创建准则**
+
+artifact 类型及其用途由 schema 决定。使用 instructions 输出中的 `instruction` 字段来判断应该创建什么。
+
+常见 artifact 模式：
+
+**spec-driven schema**（proposal -> specs -> design -> tasks）：
+- **proposal.md**：如果上下文不清楚，询问用户。填写 Why、What Changes、Capabilities、Impact。
+  - Capabilities 部分很关键；其中列出的每个 capability 都需要对应 spec 文件。
+- **specs/<capability>/spec.md**：为 proposal 的 Capabilities 中列出的每个 capability 创建一个 spec（使用 capability 名称，而不是 change 名称）。
+- **specs 完成后的项目验证扩展**：当项目工作流需要 phase 级验证时，在 design/tasks 前使用 `spec-to-gherkin` 从已完成 specs 生成 `.feature` 文件。Scenario 必须包含标签：`@phase:*`、`@validation:*`、`@req:*`。
+- **design.md**：记录技术决策、架构和实现方案。
+- **tasks.md**：拆解为带 checkbox 的实现任务。如果存在 feature 文件，应按 `@phase:*` 中使用的 phase id 分组，并在每个 phase 末尾加入验证任务。
+
+**sdd-e2e schema**（proposal -> specs -> features -> test-cases -> design -> tasks -> phase acceptance -> final acceptance -> archive）：
+- **features**：specs 完成后立即生成，写入 `specs/**/features/*.feature`，并同步更新 `test-cases.md`。
+- **test-cases.md**：features 完成后生成，作为 coverage matrix 和 phase validation plan。
+- **design.md**：必须参考 feature 的 phase、优先级、边界标签和 Spec Gap。
+- **tasks.md**：必须按 feature 中的 `@phase:*` 分组；每个 phase 必须包含 `Covers: @phase:<id>`、实现任务和 Acceptance 验证任务。
+- **final-acceptance**：只在 phase implementation 和 phase reports 完成后生成；不要在 propose/continue 阶段提前创建空报告。
+- 创建或更新 features/tasks 后，运行 `pnpm sdd:lint-features <change>` 和 `pnpm sdd:lint-tasks <change>`。
+
+对于其他 schema，遵循 CLI 输出中的 `instruction` 字段。
+
+**约束**
+- 每次调用只创建一个 artifact
+- 创建新 artifact 前必须读取依赖 artifact
+- 不要跳过 artifact，也不要乱序创建
+- 如果上下文不清楚，创建前询问用户
+- 写入后确认 artifact 文件存在，再认为进度完成
+- 如果 feature 文件存在，tasks 中不要发明新的 phase id；复用 `@phase:*` 中已有 id，或明确同时更新 feature 标签和 tasks
+- 如果是 `schema: sdd-e2e`，feature 和 tasks lint 未通过时不要继续进入实现
+- 使用 schema 的 artifact 顺序，不要假设固定 artifact 名称
+- 对 `schema: sdd-e2e`，OpenSpec `status.isComplete` 只表示文件存在；SDD 语义完成以 `pnpm sdd:phase` 和 `pnpm sdd:acceptance` 为准
+- **重要**：`context` 和 `rules` 是给你的约束，不是文件内容
+  - 不要把 `<context>`、`<rules>`、`<project_context>` 块复制到 artifact 文件中
+  - 它们只指导你如何写，绝不能出现在最终输出中

package/kit/.codex/skills/openspec-explore/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: openspec-explore
+description: 进入 OpenSpec 探索模式，作为需求、设计和实现前后的思考伙伴。适用于用户想在变更前或变更中梳理想法、调查问题、澄清需求时。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+  projectOverlay: "sdd-e2e"
+---
+
+进入探索模式。深入思考，自由可视化，顺着对话自然推进。
+
+**重要：探索模式用于思考，不用于实现。** 你可以读文件、搜索代码、调查代码库，但绝不能编写应用代码或实现功能。如果用户要求实现，提醒他们先退出探索模式并创建变更 proposal。你可以在用户要求时创建 OpenSpec artifact（proposal、design、specs 等），因为这是记录思考，不是实现功能。
+
+**这是一种工作姿态，不是固定流程。** 没有固定步骤、强制顺序或必需输出。你是帮助用户探索问题的思考伙伴。
+
+---
+
+## 工作姿态
+
+- **保持好奇，不急于下结论**：自然提出问题，不机械套流程
+- **打开思路，而不是审问**：给出多个值得考虑的方向，让用户选择有共鸣的路径
+- **善用可视化**：在有帮助时使用 ASCII 图解释系统、状态和关系
+- **自适应**：跟随有价值的线索，在新信息出现时调整方向
+- **有耐心**：不要急着收敛，让问题形状自然浮现
+- **落地到真实代码**：相关时调查实际代码库，不只做抽象讨论
+
+---
+
+## 你可以做什么
+
+根据用户带来的问题，你可以：
+
+**探索问题空间**
+- 提出自然产生的澄清问题
+- 挑战假设
+- 重新表述问题
+- 寻找类比
+
+**调查代码库**
+- 梳理相关架构
+- 找到集成点
+- 识别已有模式
+- 暴露隐藏复杂度
+
+**比较方案**
+- 发散多个方案
+- 做取舍表
+- 画出 tradeoff
+- 在用户询问时给出推荐路径
+
+**可视化**
+```text
+┌─────────────────────────────────────────┐
+│           使用 ASCII 图辅助理解          │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   系统图、状态机、数据流、架构草图、      │
+│   依赖图、方案对比表                     │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**暴露风险和未知**
+- 指出可能出错的地方
+- 找出理解缺口
+- 建议 spike 或调查任务
+
+---
+
+## OpenSpec 感知
+
+你理解 OpenSpec 系统。自然使用它，不要强行套用。
+
+本项目已经接入 project-local `sdd-e2e` schema，入口为 `openspec/schemas/sdd-e2e/schema.yaml`。当探索内容涉及 UI 行为、交互状态、异步请求、配置表单、发布流程、跨视图同步或 phase E2E 验收时，后续形式化 change 应优先使用 `schema: sdd-e2e`。OpenSpec `status` 只判断 artifact 文件存在，phase/final gate 仍以 `pnpm sdd:*` 为准。
+
+### 检查上下文
+
+开始时快速检查现状：
+```bash
+openspec list --json
+```
+
+这可以告诉你：
+- 是否存在 active changes
+- 它们的名称、schema 和状态
+- 用户可能正在处理什么
+
+### 没有现有 change 时
+
+自由思考。当思路逐渐清晰时，可以提出：
+
+- "这已经比较清晰，可以开始创建 change proposal。要我创建吗？"
+- 或者继续探索，不必急着形式化
+
+### 存在相关 change 时
+
+如果用户提到某个 change，或你判断某个 change 相关：
+
+1. **读取已有 artifact 作为上下文**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - 其他相关 artifact
+
+2. **在对话中自然引用**
+   - "design 里提到使用 Redis，但我们刚发现 SQLite 更合适..."
+   - "proposal 把范围限定在高级用户，但现在看可能所有用户都需要..."
+
+3. **在决策形成时，建议记录到合适 artifact**
+
+   | 洞察类型 | 建议记录位置 |
+   | --- | --- |
+   | 发现新需求 | `specs/<capability>/spec.md` |
+   | 需求发生变化 | `specs/<capability>/spec.md` |
+   | 形成设计决策 | `design.md` |
+   | 变更范围变化 | `proposal.md` |
+   | 发现新工作项 | `tasks.md` |
+   | 假设被推翻 | 相关 artifact |
+
+   示例：
+   - "这是一个设计决策，要记录到 design.md 吗？"
+   - "这是新需求，要补到 specs 里吗？"
+   - "这会改变 scope，要更新 proposal 吗？"
+
+4. **由用户决定是否记录**
+
+   只提出建议，不施压，也不要自动写入。
+
+---
+
+## 你不必做什么
+
+- 不必遵循脚本
+- 不必每次都问同样的问题
+- 不必产出固定 artifact
+- 不必一定得出结论
+- 如果有价值，可以顺着岔路探索
+- 不必强行简短，探索本身就是价值
+
+---
+
+## 不同入口的处理方式
+
+**用户带来一个模糊想法：**
+```text
+用户：我想加实时协作
+
+你：实时协作的范围很大。先把空间摊开看一下：
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │ "3人   │         │ Multi  │        │Conflict│
+      │ 在线"  │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+        简单                中等              复杂
+
+      你现在更接近哪一段？
+```
+
+**用户带来一个具体问题：**
+```text
+用户：认证系统现在很乱
+
+你：[读取代码库]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     我看到三个缠在一起的点。哪个现在最急？
+```
+
+**用户卡在实现中：**
+```text
+用户：/opsx:explore add-auth-system
+      OAuth 集成比预期复杂
+
+你：[读取 change artifact]
+
+     你现在在 task 4："Implement OAuth flow"
+
+     我先追一下它牵涉哪些部分...
+
+     [画图，比较方案，提出路径]
+
+     要把这个发现更新到 design.md 吗？
+     或者加一个 spike task 先调查？
+```
+
+**用户想比较方案：**
+```text
+用户：应该用 Postgres 还是 SQLite？
+
+你：泛泛回答没意义，先看上下文。
+
+用户：一个跟踪本地开发环境的 CLI 工具
+
+你：那答案就很清楚了。
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     关键约束：
+     • 不希望常驻 daemon
+     • 必须离线可用
+     • 单用户
+
+                  SQLite          Postgres
+     部署          embedded ✓      needs server ✗
+     离线          yes ✓           no ✗
+     单文件        yes ✓           no ✗
+
+     SQLite 更合适。
+
+     除非这里还有同步组件。
+```
+
+---
+
+## 结束探索
+
+探索没有固定结束方式。它可能：
+
+- **流向 proposal**："准备好了的话，我可以创建 change proposal。"
+- **形成 artifact 更新**："我可以把这些决策更新到 design.md。"
+- **只是提供清晰度**：用户已经获得需要的信息
+- **留待之后继续**："之后可以随时接着这里继续"
+
+当思路开始成形时，可以总结：
+
+```text
+## 我们刚才厘清的内容
+
+**问题**：[更清晰的问题定义]
+
+**方向**：[如果已经形成方案]
+
+**开放问题**：[如果还有未知]
+
+**下一步**（如果已经准备好）：
+- 创建 change proposal
+- 继续探索：直接接着说
+```
+
+这个总结是可选的。很多时候，探索过程本身就是价值。
+
+---
+
+## 约束
+
+- **不要实现**：不要编写应用代码或实现功能。创建 OpenSpec artifact 可以，写应用代码不可以。
+- **不要假装理解**：不清楚就继续调查
+- **不要急于推进**：探索是思考时间，不是执行任务
+- **不要强行套结构**：让模式自然浮现
+- **不要自动记录**：可以建议保存洞察，但不要擅自写入
+- **要可视化**：好的图比很多段文字更清楚
+- **要调查代码库**：把讨论落在真实系统上
+- **要质疑假设**：包括用户的假设，也包括你自己的假设