specops 0.2.5 → 0.3.2

package/.opencode/workflows/add-tests.md

@@ -0,0 +1,350 @@
+<purpose>
+基于已完成阶段的 SUMMARY.md、CONTEXT.md 和实现代码，生成单元测试和 E2E 测试。将每个变更文件分类为 TDD（单元）、E2E（浏览器）或跳过类别，向用户展示测试计划以获取批准，然后按照 RED-GREEN 规范生成测试。
+
+用户目前在每个阶段完成后手动编写 `/specops:quick` 提示来生成测试。此工作流通过适当的分类、质量门控和缺口报告来标准化这一过程。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+解析 `$ARGUMENTS`：
+- 阶段编号（整数、小数或字母后缀）→ 存储为 `$PHASE_ARG`
+- 阶段编号后的剩余文本 → 存储为 `$EXTRA_INSTRUCTIONS`（可选）
+
+示例：`/specops:add-tests 12 focus on edge cases` → `$PHASE_ARG=12`，`$EXTRA_INSTRUCTIONS="focus on edge cases"`
+
+如果未提供阶段参数：
+
+```
+错误：需要提供阶段编号
+用法：/specops:add-tests <阶段> [附加说明]
+示例：/specops:add-tests 12
+示例：/specops:add-tests 12 focus on edge cases in the pricing module
+```
+
+退出。
+</step>
+
+<step name="init_context">
+加载阶段操作上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "${PHASE_ARG}")
+```
+
+从初始化 JSON 中提取：`phase_dir`、`phase_number`、`phase_name`。
+
+验证阶段目录是否存在。如果不存在：
+```
+错误：未找到阶段 ${PHASE_ARG} 的目录
+请确保阶段存在于 .planning/phases/ 中
+```
+退出。
+
+按优先级读取阶段产物：
+1. `${phase_dir}/*-SUMMARY.md` — 实现了什么，变更了哪些文件
+2. `${phase_dir}/CONTEXT.md` — 验收标准，决策
+3. `${phase_dir}/*-VERIFICATION.md` — 用户验证的场景（如果做了 UAT）
+
+如果没有 SUMMARY.md：
+```
+错误：未找到阶段 ${PHASE_ARG} 的 SUMMARY.md
+此命令适用于已完成的阶段。请先运行 /specops:execute-phase。
+```
+退出。
+
+展示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 添加测试 — 阶段 ${phase_number}：${phase_name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="analyze_implementation">
+从 SUMMARY.md 的"Files Changed"或等效部分提取阶段修改的文件列表。
+
+对于每个文件，分类为以下三个类别之一：
+
+| 类别 | 标准 | 测试类型 |
+|------|------|----------|
+| **TDD** | 纯函数，可以编写 `expect(fn(input)).toBe(output)` | 单元测试 |
+| **E2E** | 可通过浏览器自动化验证的 UI 行为 | Playwright/E2E 测试 |
+| **跳过** | 无法有意义地测试或已被覆盖 | 无 |
+
+**TDD 分类——适用于：**
+- 业务逻辑：计算、定价、税务规则、验证
+- 数据转换：映射、过滤、聚合、格式化
+- 解析器：CSV、JSON、XML、自定义格式解析
+- 验证器：输入验证、schema 验证、业务规则
+- 状态机：状态转换、工作流步骤
+- 工具函数：字符串操作、日期处理、数字格式化
+
+**E2E 分类——适用于：**
+- 键盘快捷键：按键绑定、修饰键、组合键序列
+- 导航：页面跳转、路由、面包屑、前进/后退
+- 表单交互：提交、验证错误、字段焦点、自动完成
+- 选择：行选择、多选、Shift+点击范围
+- 拖放：重新排序、在容器间移动
+- 模态对话框：打开、关闭、确认、取消
+- 数据网格：排序、过滤、内联编辑、列调整
+
+**跳过分类——适用于：**
+- UI 布局/样式：CSS 类、视觉外观、响应式断点
+- 配置：配置文件、环境变量、功能开关
+- 胶水代码：依赖注入设置、中间件注册、路由表
+- 迁移：数据库迁移、schema 变更
+- 简单 CRUD：无业务逻辑的基本增删改查
+- 类型定义：无逻辑的 record、DTO、interface
+
+阅读每个文件以验证分类。不要仅根据文件名分类。
+</step>
+
+<step name="present_classification">
+在继续之前向用户展示分类以获取确认：
+
+```
+AskUserQuestion(
+  header: "测试分类",
+  question: |
+    ## 已分类的测试文件
+
+    ### TDD（单元测试）— {N} 个文件
+    {文件列表及简要原因}
+
+    ### E2E（浏览器测试）— {M} 个文件
+    {文件列表及简要原因}
+
+    ### 跳过 — {K} 个文件
+    {文件列表及简要原因}
+
+    {如果有 $EXTRA_INSTRUCTIONS："附加说明：${EXTRA_INSTRUCTIONS}"}
+
+    你希望如何继续？
+  options:
+    - "批准并生成测试计划"
+    - "调整分类（我来指定变更）"
+    - "取消"
+)
+```
+
+如果用户选择"调整分类"：应用其变更并重新展示。
+如果用户选择"取消"：优雅退出。
+</step>
+
+<step name="discover_test_structure">
+在生成测试计划之前，发现项目现有的测试结构：
+
+```bash
+# 查找现有测试目录
+find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
+# 查找现有测试文件以匹配命名规范
+find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*Tests.fs" -o -name "*Test.fs" \) 2>/dev/null | head -20
+# 检查测试运行器
+ls package.json *.sln 2>/dev/null
+```
+
+识别：
+- 测试目录结构（单元测试在哪里，E2E 测试在哪里）
+- 命名规范（`.test.ts`、`.spec.ts`、`*Tests.fs` 等）
+- 测试运行命令（如何执行单元测试，如何执行 E2E 测试）
+- 测试框架（xUnit、NUnit、Jest、Playwright 等）
+
+如果测试结构不明确，询问用户：
+```
+AskUserQuestion(
+  header: "测试结构",
+  question: "我发现了多个测试位置。应该在哪里创建测试？",
+  options: [列出发现的位置]
+)
+```
+</step>
+
+<step name="generate_test_plan">
+为每个已批准的文件创建详细的测试计划。
+
+**对于 TDD 文件**，按照 RED-GREEN-REFACTOR 规划测试：
+1. 识别文件中可测试的函数/方法
+2. 对于每个函数：列出输入场景、预期输出、边界情况
+3. 注意：由于代码已存在，测试可能立即通过——这没问题，但要验证它们测试的是正确的行为
+
+**对于 E2E 文件**，按照 RED-GREEN 门控规划测试：
+1. 从 CONTEXT.md/VERIFICATION.md 识别用户场景
+2. 对于每个场景：描述用户操作、预期结果、断言
+3. 注意：RED 门控意味着确认如果功能损坏测试会失败
+
+展示完整的测试计划：
+
+```
+AskUserQuestion(
+  header: "测试计划",
+  question: |
+    ## 测试生成计划
+
+    ### 单元测试（{N} 个测试，跨 {M} 个文件）
+    {对于每个文件：测试文件路径，测试用例列表}
+
+    ### E2E 测试（{P} 个测试，跨 {Q} 个文件）
+    {对于每个文件：测试文件路径，测试场景列表}
+
+    ### 测试命令
+    - 单元：{发现的测试命令}
+    - E2E：{发现的 E2E 命令}
+
+    准备好生成了吗？
+  options:
+    - "全部生成"
+    - "挑选（我来指定）"
+    - "调整计划"
+)
+```
+
+如果选择"挑选"：询问用户要包含哪些测试。
+如果选择"调整计划"：应用变更并重新展示。
+</step>
+
+<step name="execute_tdd_generation">
+对于每个已批准的 TDD 测试：
+
+1. **创建测试文件**，遵循发现的项目规范（目录、命名、导入）
+
+2. **编写测试**，使用清晰的 arrange/act/assert 结构：
+   ```
+   // Arrange — 设置输入和预期输出
+   // Act — 调用被测函数
+   // Assert — 验证输出符合预期
+   ```
+
+3. **运行测试**：
+   ```bash
+   {discovered test command}
+   ```
+
+4. **评估结果：**
+   - **测试通过**：好——实现满足测试。验证测试检查的是有意义的行为（不仅仅是能编译）。
+   - **测试因断言错误失败**：这可能是测试发现的真正 bug。标记它：
+     ```
+     ⚠️ 发现潜在 bug：{测试名称}
+     预期：{expected}
+     实际：{actual}
+     文件：{实现文件}
+     ```
+     不要修复实现——这是测试生成命令，不是修复命令。记录发现。
+   - **测试因错误失败（导入、语法等）**：这是测试错误。修复测试并重新运行。
+</step>
+
+<step name="execute_e2e_generation">
+对于每个已批准的 E2E 测试：
+
+1. **检查是否有覆盖相同场景的现有测试**：
+   ```bash
+   grep -r "{scenario keyword}" {e2e test directory} 2>/dev/null
+   ```
+   如果找到，扩展而非重复。
+
+2. **创建测试文件**，针对 CONTEXT.md/VERIFICATION.md 中的用户场景
+
+3. **运行 E2E 测试**：
+   ```bash
+   {discovered e2e command}
+   ```
+
+4. **评估结果：**
+   - **GREEN（通过）**：记录成功
+   - **RED（失败）**：判断是测试问题还是真正的应用 bug。标记 bug：
+     ```
+     ⚠️ E2E 失败：{测试名称}
+     场景：{描述}
+     错误：{错误消息}
+     ```
+   - **无法运行**：报告阻塞。不要标记为完成。
+     ```
+     🛑 E2E 阻塞：{测试无法运行的原因}
+     ```
+
+**不可跳过规则：** 如果 E2E 测试无法执行（缺少依赖、环境问题），报告阻塞并将测试标记为未完成。永远不要在未实际运行测试的情况下标记成功。
+</step>
+
+<step name="summary_and_commit">
+创建测试覆盖率报告并展示给用户：
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 测试生成完成
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 结果
+
+| 类别 | 已生成 | 通过 | 失败 | 阻塞 |
+|------|--------|------|------|------|
+| 单元 | {N}    | {n1} | {n2} | {n3} |
+| E2E  | {M}    | {m1} | {m2} | {m3} |
+
+## 创建/修改的文件
+{测试文件列表及路径}
+
+## 覆盖缺口
+{无法测试的区域及原因}
+
+## 发现的 Bug
+{表明实现 bug 的断言失败}
+```
+
+在项目状态中记录测试生成：
+```bash
+node .opencode/bin/specops-tools.cjs state-snapshot
+```
+
+如果有通过的测试需要提交：
+
+```bash
+git add {test files}
+git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+```
+
+展示后续步骤：
+
+```
+---
+
+## ▶ 下一步
+
+{如果发现了 bug：}
+**修复发现的 bug：** `/specops:quick fix the {N} test failures discovered in phase ${phase_number}`
+
+{如果有阻塞的测试：}
+**解决测试阻塞：** {需要什么的描述}
+
+{否则：}
+**所有测试通过！** 阶段 ${phase_number} 已完全测试。
+
+---
+
+**其他可用操作：**
+- `/specops:add-tests {next_phase}` — 测试另一个阶段
+- `/specops:verify-work {phase_number}` — 运行 UAT 验证
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] 已加载阶段产物（SUMMARY.md、CONTEXT.md，可选 VERIFICATION.md）
+- [ ] 所有变更文件已分类为 TDD/E2E/跳过类别
+- [ ] 分类已展示给用户并获得批准
+- [ ] 已发现项目测试结构（目录、规范、运行器）
+- [ ] 测试计划已展示给用户并获得批准
+- [ ] 已生成具有 arrange/act/assert 结构的 TDD 测试
+- [ ] 已生成针对用户场景的 E2E 测试
+- [ ] 所有测试已执行——没有未运行的测试被标记为通过
+- [ ] 测试发现的 bug 已标记（未修复）
+- [ ] 测试文件已用正确的消息提交
+- [ ] 覆盖缺口已记录
+- [ ] 已向用户展示后续步骤
+</success_criteria>

package/.opencode/workflows/add-todo.md

@@ -0,0 +1,157 @@
+<purpose>
+在 SpecOps 会话中捕获浮现的想法、任务或问题，作为结构化的待办事项供后续处理。实现"想法 → 捕获 → 继续"的流程，不丢失上下文。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="init_context">
+加载待办事项上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init todos)
+```
+
+从 init JSON 中提取：`commit_docs`、`date`、`timestamp`、`todo_count`、`todos`、`pending_dir`、`todos_dir_exists`。
+
+确保目录存在：
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+
+记录 todos 数组中已有的领域，以便在 infer_area 步骤中保持一致性。
+</step>
+
+<step name="extract_content">
+**有参数时：** 使用参数作为标题/焦点。
+- `/specops:add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**无参数时：** 分析最近的对话以提取：
+- 讨论的具体问题、想法或任务
+- 提到的相关文件路径
+- 技术细节（错误消息、行号、约束条件）
+
+整理：
+- `title`：3-10 个词的描述性标题（优先使用动词开头）
+- `problem`：问题是什么或为什么需要这个
+- `solution`：方法提示或"TBD"（如果只是一个想法）
+- `files`：对话中提到的相关路径及行号
+</step>
+
+<step name="infer_area">
+从文件路径推断领域：
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| 无文件或不明确 | `general` |
+
+如果存在类似匹配，使用步骤 2 中已有的领域。
+</step>
+
+<step name="check_duplicates">
+```bash
+# Search for key words from title in existing todos
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+如果发现潜在重复：
+1. 读取已有的待办事项
+2. 比较范围
+
+如果有重叠，使用 AskUserQuestion：
+- header："Duplicate?"
+- question："存在类似的待办事项：[title]。你想怎么做？"
+- options：
+  - "Skip" — 保留已有的待办事项
+  - "Replace" — 用新上下文更新已有的
+  - "Add anyway" — 创建为单独的待办事项
+</step>
+
+<step name="create_file">
+使用 init 上下文中的值：`timestamp` 和 `date` 已经可用。
+
+为标题生成 slug：
+```bash
+slug=$(node .opencode/bin/specops-tools.cjs generate-slug "$title" --raw)
+```
+
+写入 `.planning/todos/pending/${date}-${slug}.md`：
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Claude to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+如果 `.planning/STATE.md` 存在：
+
+1. 使用 init 上下文中的 `todo_count`（如果计数已变化则重新运行 `init todos`）
+2. 更新 "## Accumulated Context" 下的 "### Pending Todos"
+</step>
+
+<step name="git_commit">
+提交待办事项和任何更新的状态：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+```
+
+工具会自动遵循 `commit_docs` 配置和 gitignore。
+
+确认："Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/specops:check-todos)
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] 目录结构已存在
+- [ ] 待办事项文件已创建，包含有效的 frontmatter
+- [ ] Problem 部分有足够的上下文供未来的 Claude 理解
+- [ ] 已检查并解决重复项
+- [ ] 领域与已有待办事项保持一致
+- [ ] STATE.md 已更新（如果存在）
+- [ ] 待办事项和状态已提交到 git
+</success_criteria>