specops 0.2.4 → 0.3.0

package/.opencode/workflows/verify-work.md

@@ -0,0 +1,569 @@
+<purpose>
+通过对话式测试验证已构建的功能，带有持久化状态。创建 UAT.md 跟踪测试进度，在 /clear 后仍然有效，并将缺口反馈到 /specops:plan-phase --gaps。
+
+用户测试，Claude 记录。一次一个测试。纯文本响应。
+</purpose>
+
+<philosophy>
+**展示预期，询问现实是否匹配。**
+
+Claude 展示应该发生什么。用户确认或描述不同之处。
+- "yes" / "y" / "next" / 空 → 通过
+- 其他任何内容 → 记录为问题，推断严重程度
+
+没有通过/失败按钮。没有严重程度问题。只是："这是应该发生的。是这样吗？"
+</philosophy>
+
+<template>
+@.opencode/templates/UAT.md
+</template>
+
+<process>
+
+<step name="initialize" priority="first">
+如果 $ARGUMENTS 包含阶段编号，加载上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init verify-work "${PHASE_ARG}")
+```
+
+解析 JSON 获取：`planner_model`、`checker_model`、`commit_docs`、`phase_found`、`phase_dir`、`phase_number`、`phase_name`、`has_verification`。
+</step>
+
+<step name="check_active_session">
+**首先：检查活跃的 UAT 会话**
+
+```bash
+find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
+```
+
+**如果存在活跃会话且未提供 $ARGUMENTS：**
+
+读取每个文件的前置信息（status、phase）和 Current Test 部分。
+
+内联显示：
+
+```
+## 活跃的 UAT 会话
+
+| # | 阶段 | 状态 | 当前测试 | 进度 |
+|---|------|------|----------|------|
+| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 |
+| 2 | 05-auth | testing | 1. Login Form | 0/4 |
+
+回复编号以恢复，或提供阶段编号开始新会话。
+```
+
+等待用户响应。
+
+- 如果用户回复编号（1、2）→ 加载该文件，转到 `resume_from_file`
+- 如果用户回复阶段编号 → 视为新会话，转到 `create_uat_file`
+
+**如果存在活跃会话且提供了 $ARGUMENTS：**
+
+检查该阶段是否已有会话。如果有，提供恢复或重新开始的选项。
+如果没有，继续到 `create_uat_file`。
+
+**如果没有活跃会话且未提供 $ARGUMENTS：**
+
+```
+没有活跃的 UAT 会话。
+
+提供阶段编号开始测试（例如 /specops:verify-work 4）
+```
+
+**如果没有活跃会话且提供了 $ARGUMENTS：**
+
+继续到 `create_uat_file`。
+</step>
+
+<step name="find_summaries">
+**查找要测试的内容：**
+
+使用 init 返回的 `phase_dir`（如果尚未运行 init 则运行）。
+
+```bash
+ls "$phase_dir"/*-SUMMARY.md 2>/dev/null
+```
+
+读取每个 SUMMARY.md 以提取可测试的交付物。
+</step>
+
+<step name="extract_tests">
+**从 SUMMARY.md 提取可测试的交付物：**
+
+解析以下内容：
+1. **成果** - 添加的功能/特性
+2. **面向用户的变更** - UI、工作流、交互
+
+聚焦于用户可观察的结果，而不是实现细节。
+
+对于每个交付物，创建一个测试：
+- name：简短的测试名称
+- expected：用户应该看到/体验到什么（具体、可观察）
+
+示例：
+- 成果："添加了无限嵌套的评论线程"
+  → 测试："回复评论"
+  → 预期："点击回复在评论下方打开内联编辑器。提交后显示回复嵌套在父评论下方，带有视觉缩进。"
+
+跳过内部/不可观察的项目（重构、类型变更等）。
+</step>
+
+<step name="create_uat_file">
+**创建包含所有测试的 UAT 文件：**
+
+```bash
+mkdir -p "$PHASE_DIR"
+```
+
+从提取的交付物构建测试列表。
+
+创建文件：
+
+```markdown
+---
+status: testing
+phase: XX-name
+source: [SUMMARY.md 文件列表]
+started: [ISO 时间戳]
+updated: [ISO 时间戳]
+---
+
+## Current Test
+<!-- 每个测试覆盖写入 - 显示当前位置 -->
+
+number: 1
+name: [第一个测试名称]
+expected: |
+  [用户应观察到的内容]
+awaiting: user response
+
+## Tests
+
+### 1. [测试名称]
+expected: [可观察的行为]
+result: [pending]
+
+### 2. [测试名称]
+expected: [可观察的行为]
+result: [pending]
+
+...
+
+## Summary
+
+total: [N]
+passed: 0
+issues: 0
+pending: [N]
+skipped: 0
+
+## Gaps
+
+[暂无]
+```
+
+写入 `.planning/phases/XX-name/{phase_num}-UAT.md`
+
+继续到 `present_test`。
+</step>
+
+<step name="present_test">
+**向用户展示当前测试：**
+
+从 UAT 文件读取 Current Test 部分。
+
+使用检查点框格式显示：
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: 需要验证                                        ║
+╚══════════════════════════════════════════════════════════════╝
+
+**测试 {number}: {name}**
+
+{expected}
+
+──────────────────────────────────────────────────────────────
+→ 输入"pass"或描述问题
+──────────────────────────────────────────────────────────────
+```
+
+等待用户响应（纯文本，不使用 AskUserQuestion）。
+</step>
+
+<step name="process_response">
+**处理用户响应并更新文件：**
+
+**如果响应表示通过：**
+- 空响应、"yes"、"y"、"ok"、"pass"、"next"、"approved"、"✓"
+
+更新 Tests 部分：
+```
+### {N}. {name}
+expected: {expected}
+result: pass
+```
+
+**如果响应表示跳过：**
+- "skip"、"can't test"、"n/a"
+
+更新 Tests 部分：
+```
+### {N}. {name}
+expected: {expected}
+result: skipped
+reason: [用户的原因（如提供）]
+```
+
+**如果响应是其他任何内容：**
+- 视为问题描述
+
+从描述推断严重程度：
+- 包含：crash、error、exception、fails、broken、unusable → blocker
+- 包含：doesn't work、wrong、missing、can't → major
+- 包含：slow、weird、off、minor、small → minor
+- 包含：color、font、spacing、alignment、visual → cosmetic
+- 不确定时默认：major
+
+更新 Tests 部分：
+```
+### {N}. {name}
+expected: {expected}
+result: issue
+reported: "{用户响应原文}"
+severity: {推断的}
+```
+
+追加到 Gaps 部分（结构化 YAML 供 plan-phase --gaps 使用）：
+```yaml
+- truth: "{测试中的预期行为}"
+  status: failed
+  reason: "User reported: {用户响应原文}"
+  severity: {推断的}
+  test: {N}
+  artifacts: []  # 由诊断填充
+  missing: []    # 由诊断填充
+```
+
+**任何响应后：**
+
+更新 Summary 计数。
+更新前置信息的 updated 时间戳。
+
+如果还有更多测试 → 更新 Current Test，转到 `present_test`
+如果没有更多测试 → 转到 `complete_session`
+</step>
+
+<step name="resume_from_file">
+**从 UAT 文件恢复测试：**
+
+读取完整的 UAT 文件。
+
+找到第一个 `result: [pending]` 的测试。
+
+宣布：
+```
+恢复：Phase {phase} UAT
+进度：{passed + issues + skipped}/{total}
+已发现的问题：{issues count}
+
+从测试 {N} 继续...
+```
+
+用待处理的测试更新 Current Test 部分。
+继续到 `present_test`。
+</step>
+
+<step name="complete_session">
+**完成测试并提交：**
+
+更新前置信息：
+- status: complete
+- updated: [现在]
+
+清除 Current Test 部分：
+```
+## Current Test
+
+[测试完成]
+```
+
+提交 UAT 文件：
+```bash
+node .opencode/bin/specops-tools.cjs commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
+```
+
+展示摘要：
+```
+## UAT 完成：Phase {phase}
+
+| 结果 | 数量 |
+|------|------|
+| 通过 | {N}  |
+| 问题 | {N}  |
+| 跳过 | {N}  |
+
+[如果 issues > 0：]
+### 发现的问题
+
+[来自 Issues 部分的列表]
+```
+
+**如果 issues > 0：** 继续到 `diagnose_issues`
+
+**如果 issues == 0：**
+```
+所有测试通过。准备继续。
+
+- `/specops:plan-phase {next}` — 规划下一阶段
+- `/specops:execute-phase {next}` — 执行下一阶段
+```
+</step>
+
+<step name="diagnose_issues">
+**在规划修复之前诊断根本原因：**
+
+```
+---
+
+发现 {N} 个问题。正在诊断根本原因...
+
+正在并行生成调试 Agent 调查每个问题。
+```
+
+- 加载 diagnose-issues 工作流
+- 遵循 @.opencode/workflows/diagnose-issues.md
+- 为每个问题并行生成调试 Agent
+- 收集根本原因
+- 用根本原因更新 UAT.md
+- 继续到 `plan_gap_closure`
+
+诊断自动运行——无需用户提示。并行 Agent 同时调查，因此开销最小且修复更准确。
+</step>
+
+<step name="plan_gap_closure">
+**从诊断的缺口自动规划修复：**
+
+显示：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 规划修复
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 正在生成规划器进行缺口修复...
+```
+
+以 --gaps 模式生成 specops-planner：
+
+```
+Task(
+  prompt="""
+<planning_context>
+
+**Phase:** {phase_number}
+**Mode:** gap_closure
+
+<files_to_read>
+- {phase_dir}/{phase_num}-UAT.md (UAT with diagnoses)
+- .planning/STATE.md (Project State)
+- .planning/ROADMAP.md (Roadmap)
+</files_to_read>
+
+</planning_context>
+
+<downstream_consumer>
+Output consumed by /specops:execute-phase
+Plans must be executable prompts.
+</downstream_consumer>
+""",
+  subagent_type="specops-planner",
+  model="{planner_model}",
+  description="Plan gap fixes for Phase {phase}"
+)
+```
+
+返回时：
+- **PLANNING COMPLETE：** 继续到 `verify_gap_plans`
+- **PLANNING INCONCLUSIVE：** 报告并提供手动干预选项
+</step>
+
+<step name="verify_gap_plans">
+**用检查器验证修复计划：**
+
+显示：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 验证修复计划
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 正在生成计划检查器...
+```
+
+初始化：`iteration_count = 1`
+
+生成 specops-plan-checker：
+
+```
+Task(
+  prompt="""
+<verification_context>
+
+**Phase:** {phase_number}
+**Phase Goal:** Close diagnosed gaps from UAT
+
+<files_to_read>
+- {phase_dir}/*-PLAN.md (Plans to verify)
+</files_to_read>
+
+</verification_context>
+
+<expected_output>
+Return one of:
+- ## VERIFICATION PASSED — all checks pass
+- ## ISSUES FOUND — structured issue list
+</expected_output>
+""",
+  subagent_type="specops-plan-checker",
+  model="{checker_model}",
+  description="Verify Phase {phase} fix plans"
+)
+```
+
+返回时：
+- **VERIFICATION PASSED：** 继续到 `present_ready`
+- **ISSUES FOUND：** 继续到 `revision_loop`
+</step>
+
+<step name="revision_loop">
+**迭代规划器 ↔ 检查器直到计划通过（最多 3 次）：**
+
+**如果 iteration_count < 3：**
+
+显示：`正在发回规划器修订...（迭代 {N}/3）`
+
+使用修订上下文生成 specops-planner：
+
+```
+Task(
+  prompt="""
+<revision_context>
+
+**Phase:** {phase_number}
+**Mode:** revision
+
+<files_to_read>
+- {phase_dir}/*-PLAN.md (Existing plans)
+</files_to_read>
+
+**Checker issues:**
+{structured_issues_from_checker}
+
+</revision_context>
+
+<instructions>
+Read existing PLAN.md files. Make targeted updates to address checker issues.
+Do NOT replan from scratch unless issues are fundamental.
+</instructions>
+""",
+  subagent_type="specops-planner",
+  model="{planner_model}",
+  description="Revise Phase {phase} plans"
+)
+```
+
+规划器返回后 → 再次生成检查器（verify_gap_plans 逻辑）
+递增 iteration_count
+
+**如果 iteration_count >= 3：**
+
+显示：`已达最大迭代次数。{N} 个问题仍然存在。`
+
+提供选项：
+1. 强制继续（尽管有问题仍然执行）
+2. 提供指导（用户给出方向，重试）
+3. 放弃（退出，用户手动运行 /specops:plan-phase）
+
+等待用户响应。
+</step>
+
+<step name="present_ready">
+**展示完成和后续步骤：**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 修复就绪 ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {X}: {名称}** — {N} 个缺口已诊断，{M} 个修复计划已创建
+
+| 缺口 | 根本原因 | 修复计划 |
+|------|----------|----------|
+| {truth 1} | {root_cause} | {phase}-04 |
+| {truth 2} | {root_cause} | {phase}-04 |
+
+计划已验证，准备执行。
+
+───────────────────────────────────────────────────────────────
+
+## ▶ 下一步
+
+**执行修复** — 运行修复计划
+
+`/clear` 然后 `/specops:execute-phase {phase} --gaps-only`
+
+───────────────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<update_rules>
+**批量写入以提高效率：**
+
+将结果保存在内存中。仅在以下情况写入文件：
+1. **发现问题** — 立即保存问题
+2. **会话完成** — 提交前最终写入
+3. **检查点** — 每 5 个通过的测试（安全网）
+
+| 部分 | 规则 | 写入时机 |
+|------|------|----------|
+| Frontmatter.status | 覆盖 | 开始、完成 |
+| Frontmatter.updated | 覆盖 | 任何文件写入时 |
+| Current Test | 覆盖 | 任何文件写入时 |
+| Tests.{N}.result | 覆盖 | 任何文件写入时 |
+| Summary | 覆盖 | 任何文件写入时 |
+| Gaps | 追加 | 发现问题时 |
+
+上下文重置时：文件显示最后一个检查点。从那里恢复。
+</update_rules>
+
+<severity_inference>
+**从用户的自然语言推断严重程度：**
+
+| 用户说 | 推断 |
+|--------|------|
+| "crashes"、"error"、"exception"、"fails completely" | blocker |
+| "doesn't work"、"nothing happens"、"wrong behavior" | major |
+| "works but..."、"slow"、"weird"、"minor issue" | minor |
+| "color"、"spacing"、"alignment"、"looks off" | cosmetic |
+
+不确定时默认为 **major**。用户可以在需要时纠正。
+
+**永远不要问"这有多严重？"** - 直接推断并继续。
+</severity_inference>
+
+<success_criteria>
+- [ ] UAT 文件已创建，包含来自 SUMMARY.md 的所有测试
+- [ ] 测试逐个展示，附带预期行为
+- [ ] 用户响应处理为通过/问题/跳过
+- [ ] 严重程度从描述推断（从不询问）
+- [ ] 批量写入：发现问题时、每 5 个通过时或完成时
+- [ ] 完成时已提交
+- [ ] 如有问题：并行调试 Agent 诊断根本原因
+- [ ] 如有问题：specops-planner 创建修复计划（gap_closure 模式）
+- [ ] 如有问题：specops-plan-checker 验证修复计划
+- [ ] 如有问题：修订循环直到计划通过（最多 3 次迭代）
+- [ ] 完成后准备好运行 `/specops:execute-phase --gaps-only`
+</success_criteria>

package/commands/specops/add-phase.md

@@ -0,0 +1,43 @@
+---
+name: specops:add-phase
+description: 在路线图中当前里程碑的末尾添加阶段
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+在路线图中当前里程碑的末尾添加一个新的整数阶段。
+
+路由到 add-phase 工作流，该工作流处理：
+- 阶段编号计算（下一个顺序整数）
+- 目录创建及 slug 生成
+- 路线图结构更新
+- STATE.md 路线图演进追踪
+</objective>
+
+<execution_context>
+@.opencode/workflows/add-phase.md
+</execution_context>
+
+<context>
+参数：$ARGUMENTS（阶段描述）
+
+路线图和状态在工作流中通过 `init phase-op` 和定向工具调用解析。
+</context>
+
+<process>
+**遵循 add-phase 工作流**，来自 `@.opencode/workflows/add-phase.md`。
+
+该工作流处理所有逻辑，包括：
+1. 参数解析和验证
+2. 路线图存在性检查
+3. 当前里程碑识别
+4. 下一个阶段编号计算（忽略小数）
+5. 从描述生成 slug
+6. 阶段目录创建
+7. 路线图条目插入
+8. STATE.md 更新
+</process>

package/commands/specops/add-tests.md

@@ -0,0 +1,41 @@
+---
+name: specops:add-tests
+description: 根据 UAT 标准和实现为已完成的阶段生成测试
+argument-hint: "<phase> [additional instructions]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+argument-instructions: |
+  将参数解析为阶段编号（整数、小数或字母后缀），加上可选的自由文本指令。
+  示例：/specops:add-tests 12
+  示例：/specops:add-tests 12 focus on edge cases in the pricing module
+---
+<objective>
+为已完成的阶段生成单元测试和 E2E 测试，使用其 SUMMARY.md、CONTEXT.md 和 VERIFICATION.md 作为规格说明。
+
+分析实现文件，将它们分类为 TDD（单元测试）、E2E（浏览器测试）或 Skip 类别，向用户展示测试计划以获取批准，然后按照 RED-GREEN 规范生成测试。
+
+输出：测试文件以消息 `test(phase-{N}): add unit and E2E tests from add-tests command` 提交
+</objective>
+
+<execution_context>
+@.opencode/workflows/add-tests.md
+</execution_context>
+
+<context>
+阶段：$ARGUMENTS
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/add-tests.md 中的 add-tests 工作流。
+保留所有工作流门控（分类审批、测试计划审批、RED-GREEN 验证、缺口报告）。
+</process>

package/commands/specops/add-todo.md

@@ -0,0 +1,47 @@
+---
+name: specops:add-todo
+description: 从当前对话上下文中捕获想法或任务作为待办事项
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+将 SpecOps 会话中浮现的想法、任务或问题捕获为结构化的待办事项，供后续处理。
+
+路由到 add-todo 工作流，该工作流处理：
+- 目录结构创建
+- 从参数或对话中提取内容
+- 从文件路径推断领域
+- 重复检测和解决
+- 创建带 frontmatter 的待办文件
+- STATE.md 更新
+- Git 提交
+</objective>
+
+<execution_context>
+@.opencode/workflows/add-todo.md
+</execution_context>
+
+<context>
+参数：$ARGUMENTS（可选的待办描述）
+
+状态在工作流中通过 `init todos` 和定向读取解析。
+</context>
+
+<process>
+**遵循 add-todo 工作流**，来自 `@.opencode/workflows/add-todo.md`。
+
+该工作流处理所有逻辑，包括：
+1. 目录确保
+2. 现有领域检查
+3. 内容提取（参数或对话）
+4. 领域推断
+5. 重复检查
+6. 文件创建及 slug 生成
+7. STATE.md 更新
+8. Git 提交
+</process>