specops 0.2.5 → 0.3.2

package/.opencode/templates/DEBUG.md

@@ -0,0 +1,164 @@
+# 调试模板
+
+`.planning/debug/[slug].md` 的模板，活跃调试会话追踪。
+
+---
+
+## 文件模板
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
+trigger: "[用户原始输入]"
+created: [ISO 时间戳]
+updated: [ISO 时间戳]
+---
+
+## 当前焦点
+<!-- 每次更新时覆盖，始终反映当前状态 -->
+
+hypothesis: [当前正在测试的理论]
+test: [如何测试]
+expecting: [结果为真/假意味着什么]
+next_action: [下一步操作]
+
+## 症状
+<!-- 收集阶段写入，之后不可变 -->
+
+expected: [应该发生什么]
+actual: [实际发生什么]
+errors: [错误信息（如有）]
+reproduction: [如何触发]
+started: [何时出问题 / 一直有问题]
+
+## 已排除
+<!-- 仅追加，防止 /clear 后重复调查 -->
+
+- hypothesis: [被证伪的理论]
+  evidence: [什么证伪了它]
+  timestamp: [排除时间]
+
+## 证据
+<!-- 仅追加，调查中发现的事实 -->
+
+- timestamp: [发现时间]
+  checked: [检查了什么]
+  found: [观察到什么]
+  implication: [这意味着什么]
+
+## 解决方案
+<!-- 随理解深入覆盖 -->
+
+root_cause: [找到前为空]
+fix: [应用前为空]
+verification: [验证前为空]
+files_changed: []
+```
+
+---
+
+<section_rules>
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: 覆盖 - 反映当前阶段
+- `trigger`: 不可变 - 用户原始输入，永不改变
+- `created`: 不可变 - 设置一次
+- `updated`: 覆盖 - 每次变更时更新
+
+**当前焦点:**
+- 每次更新时完全覆盖
+- 始终反映 Claude 当前正在做什么
+- 如果 Claude 在 /clear 后读取此文件，能准确知道从哪里恢复
+- 字段: hypothesis, test, expecting, next_action
+
+**症状:**
+- 初始收集阶段写入
+- 收集完成后不可变
+- 作为我们要修复什么的参考点
+- 字段: expected, actual, errors, reproduction, started
+
+**已排除:**
+- 仅追加，永不删除条目
+- 防止上下文重置后重复调查死胡同
+- 每个条目: 假设、证伪它的证据、时间戳
+- 对跨 /clear 边界的效率至关重要
+
+**证据:**
+- 仅追加，永不删除条目
+- 调查中发现的事实
+- 每个条目: 时间戳、检查了什么、发现了什么、含义
+- 构建根本原因的论据
+
+**解决方案:**
+- 随理解深入覆盖
+- 尝试修复时可能多次更新
+- 最终状态显示确认的根本原因和已验证的修复
+- 字段: root_cause, fix, verification, files_changed
+
+</section_rules>
+
+<lifecycle>
+
+**创建:** /specops:debug 调用时立即创建
+- 用用户输入创建文件作为 trigger
+- 设置 status 为 "gathering"
+- 当前焦点: next_action = "收集症状"
+- 症状: 空，待填写
+
+**症状收集期间:**
+- 用户回答问题时更新症状部分
+- 每个问题更新当前焦点
+- 完成时: status → "investigating"
+
+**调查期间:**
+- 每个假设覆盖当前焦点
+- 每个发现追加到证据
+- 假设被证伪时追加到已排除
+- 更新 frontmatter 中的时间戳
+
+**修复期间:**
+- status → "fixing"
+- 确认时更新 Resolution.root_cause
+- 应用时更新 Resolution.fix
+- 更新 Resolution.files_changed
+
+**验证期间:**
+- status → "verifying"
+- 用结果更新 Resolution.verification
+- 如果验证失败: status → "investigating"，重试
+
+**自我验证通过后:**
+- status -> "awaiting_human_verify"
+- 在检查点中请求用户明确确认
+- 还不要将文件移到 resolved
+
+**解决时:**
+- status → "resolved"
+- 将文件移到 .planning/debug/resolved/ (仅在用户确认修复后)
+
+</lifecycle>
+
+<resume_behavior>
+
+Claude 在 /clear 后读取此文件时:
+
+1. 解析 frontmatter → 了解状态
+2. 读取当前焦点 → 准确知道在做什么
+3. 读取已排除 → 知道不要重试什么
+4. 读取证据 → 知道已经学到了什么
+5. 从 next_action 继续
+
+文件就是调试大脑。Claude 应该能从任何中断点完美恢复。
+
+</resume_behavior>
+
+<size_constraint>
+
+保持调试文件聚焦:
+- 证据条目: 每个 1-2 行，只记录事实
+- 已排除: 简短，假设 + 为什么失败
+- 不要叙述性散文，只要结构化数据
+
+如果证据增长很大 (10+ 条目)，考虑是否在兜圈子。检查已排除确保没有重复。
+
+</size_constraint>

package/.opencode/templates/UAT.md

@@ -0,0 +1,180 @@
+# UAT 模板
+
+`.planning/phases/XX-name/{phase_num}-UAT.md` 的模板，持久化的 UAT 会话追踪。
+
+---
+
+## 文件模板
+
+```markdown
+---
+status: testing | complete | diagnosed
+phase: XX-name
+source: [被测试的 SUMMARY.md 文件列表]
+started: [ISO 时间戳]
+updated: [ISO 时间戳]
+---
+
+## 当前测试
+<!-- 每次测试时覆盖，显示当前位置 -->
+
+number: [N]
+name: [测试名称]
+expected: |
+  [用户应该观察到什么]
+awaiting: 用户响应
+
+## 测试
+
+### 1. [测试名称]
+expected: [可观测行为 — 用户应该看到什么]
+result: [pending]
+
+### 2. [测试名称]
+expected: [可观测行为]
+result: pass
+
+### 3. [测试名称]
+expected: [可观测行为]
+result: issue
+reported: "[用户原话]"
+severity: major
+
+### 4. [测试名称]
+expected: [可观测行为]
+result: skipped
+reason: [跳过原因]
+
+...
+
+## 总结
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+
+## 缺口
+
+<!-- YAML 格式供 plan-phase --gaps 消费 -->
+- truth: "[测试中的预期行为]"
+  status: failed
+  reason: "用户报告: [原话]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # 诊断后填写
+  artifacts: []      # 诊断后填写
+  missing: []        # 诊断后填写
+  debug_session: ""  # 诊断后填写
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: 覆盖 - "testing" 或 "complete"
+- `phase`: 不可变 - 创建时设置
+- `source`: 不可变 - 被测试的 SUMMARY 文件
+- `started`: 不可变 - 创建时设置
+- `updated`: 覆盖 - 每次变更时更新
+
+**当前测试:**
+- 每次测试转换时完全覆盖
+- 显示哪个测试活跃以及等待什么
+- 完成时: "[测试完成]"
+
+**测试:**
+- 每个测试: 用户响应时覆盖 result 字段
+- `result` 值: [pending], pass, issue, skipped
+- 如果 issue: 添加 `reported` (原话) 和 `severity` (推断)
+- 如果 skipped: 添加 `reason` (如提供)
+
+**总结:**
+- 每次响应后覆盖计数
+- 追踪: total, passed, issues, pending, skipped
+
+**缺口:**
+- 发现问题时仅追加 (YAML 格式)
+- 诊断后: 填写 `root_cause`, `artifacts`, `missing`, `debug_session`
+- 此部分直接供 /specops:plan-phase --gaps 使用
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**测试完成后 (status: complete)，如果有缺口:**
+
+1. 用户运行诊断 (从 verify-work 提供或手动)
+2. diagnose-issues 工作流生成并行调试代理
+3. 每个代理调查一个缺口，返回根本原因
+4. UAT.md 缺口部分更新诊断结果:
+   - 每个缺口填写 `root_cause`, `artifacts`, `missing`, `debug_session`
+5. status → "diagnosed"
+6. 准备好用 /specops:plan-phase --gaps 配合根本原因使用
+
+**诊断后:**
+```yaml
+## 缺口
+
+- truth: "评论提交后立即出现"
+  status: failed
+  reason: "用户报告: 可以用但要刷新页面才显示"
+  severity: major
+  test: 2
+  root_cause: "CommentList.tsx 中 useEffect 缺少 commentCount 依赖"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect 缺少依赖"
+  missing:
+    - "将 commentCount 添加到 useEffect 依赖数组"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**创建:** /specops:verify-work 开始新会话时
+- 从 SUMMARY.md 文件提取测试
+- 设置 status 为 "testing"
+- 当前测试指向测试 1
+- 所有测试 result: [pending]
+
+**测试期间:**
+- 从当前测试部分展示测试
+- 用户以通过确认或问题描述响应
+- 更新测试结果 (pass/issue/skipped)
+- 更新总结计数
+- 如果 issue: 追加到缺口部分 (YAML 格式)，推断严重程度
+- 将当前测试移到下一个 pending 测试
+
+**完成时:**
+- status → "complete"
+- 当前测试 → "[测试完成]"
+- 提交文件
+- 展示总结和下一步
+
+**在 /clear 后恢复:**
+1. 读取 frontmatter → 了解阶段和状态
+2. 读取当前测试 → 了解在哪里
+3. 找到第一个 [pending] 结果 → 从那里继续
+4. 总结显示到目前为止的进度
+
+</lifecycle>
+
+<severity_guide>
+
+严重程度从用户的自然语言推断，永远不要询问。
+
+| 用户描述 | 推断 |
+|---------|------|
+| 崩溃、错误、异常、完全失败、无法使用 | blocker |
+| 不工作、没反应、行为错误、缺失 | major |
+| 能用但...、慢、奇怪、小问题 | minor |
+| 颜色、字体、间距、对齐、视觉、看起来不对 | cosmetic |
+
+默认: **major** (安全的默认值，用户可以纠正)
+
+</severity_guide>

package/.opencode/templates/VALIDATION.md

@@ -0,0 +1,76 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: {date}
+---
+
+# 阶段 {N} — 验证策略
+
+> 每阶段的验证契约，用于执行期间的反馈采样。
+
+---
+
+## 测试基础设施
+
+| 属性 | 值 |
+|------|-----|
+| **框架** | {pytest 7.x / jest 29.x / vitest / go test / 其他} |
+| **配置文件** | {路径或 "无 — 波次 0 安装"} |
+| **快速运行命令** | `{quick command}` |
+| **完整套件命令** | `{full command}` |
+| **预估运行时间** | ~{N} 秒 |
+
+---
+
+## 采样频率
+
+- **每次任务提交后:** 运行 `{quick run command}`
+- **每个计划波次后:** 运行 `{full suite command}`
+- **`/specops:verify-work` 之前:** 完整套件必须全绿
+- **最大反馈延迟:** {N} 秒
+
+---
+
+## 每任务验证映射
+
+| 任务 ID | 计划 | 波次 | 需求 | 测试类型 | 自动化命令 | 文件存在 | 状态 |
+|---------|------|------|------|----------|-----------|---------|------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{command}` | ✅ / ❌ W0 | ⬜ 待定 |
+
+*状态: ⬜ 待定 · ✅ 通过 · ❌ 失败 · ⚠️ 不稳定*
+
+---
+
+## 波次 0 要求
+
+- [ ] `{tests/test_file.py}` — REQ-{XX} 的桩
+- [ ] `{tests/conftest.py}` — 共享 fixtures
+- [ ] `{framework install}` — 如果未检测到框架
+
+*如果无需: "现有基础设施覆盖所有阶段需求。"*
+
+---
+
+## 仅手动验证
+
+| 行为 | 需求 | 为何手动 | 测试说明 |
+|------|------|---------|---------|
+| {行为} | REQ-{XX} | {原因} | {步骤} |
+
+*如果无需: "所有阶段行为都有自动化验证。"*
+
+---
+
+## 验证签核
+
+- [ ] 所有任务有 `<automated>` verify 或波次 0 依赖
+- [ ] 采样连续性: 不超过 3 个连续任务无自动化 verify
+- [ ] 波次 0 覆盖所有 MISSING 引用
+- [ ] 无 watch-mode 标志
+- [ ] 反馈延迟 < {N}s
+- [ ] frontmatter 中 `nyquist_compliant: true` 已设置
+
+**批准:** {待定 / 已批准 YYYY-MM-DD}

package/.opencode/templates/codebase/architecture.md

@@ -0,0 +1,255 @@
+# 架构模板
+
+`.planning/codebase/ARCHITECTURE.md` 的模板 - 记录概念层面的代码组织。
+
+**用途：** 记录代码在概念层面的组织方式。与 STRUCTURE.md（展示物理文件位置）互补。
+
+---
+
+## 文件模板
+
+```markdown
+# 架构
+
+**分析日期：** [YYYY-MM-DD]
+
+## 模式概览
+
+**整体：** [模式名称：例如 "单体 CLI"、"Serverless API"、"全栈 MVC"]
+
+**关键特征：**
+- [特征 1：例如 "单一可执行文件"]
+- [特征 2：例如 "无状态请求处理"]
+- [特征 3：例如 "事件驱动"]
+
+## 分层
+
+[描述概念层及其职责]
+
+**[层名称]：**
+- 用途：[这一层做什么]
+- 包含：[代码类型：例如 "路由处理器"、"业务逻辑"]
+- 依赖：[使用什么：例如 "仅数据层"]
+- 被使用：[什么使用它：例如 "API 路由"]
+
+**[层名称]：**
+- 用途：[这一层做什么]
+- 包含：[代码类型]
+- 依赖：[使用什么]
+- 被使用：[什么使用它]
+
+## 数据流
+
+[描述典型的请求/执行生命周期]
+
+**[流程名称]（例如 "HTTP 请求"、"CLI 命令"、"事件处理"）：**
+
+1. [入口点：例如 "用户运行命令"]
+2. [处理步骤：例如 "路由器匹配路径"]
+3. [处理步骤：例如 "控制器验证输入"]
+4. [处理步骤：例如 "服务执行逻辑"]
+5. [输出：例如 "返回响应"]
+
+**状态管理：**
+- [状态如何处理：例如 "无状态 - 无持久状态"、"每请求数据库"、"内存缓存"]
+
+## 关键抽象
+
+[整个代码库中使用的核心概念/模式]
+
+**[抽象名称]：**
+- 用途：[它代表什么]
+- 示例：[例如 "UserService、ProjectService"]
+- 模式：[例如 "单例"、"工厂"、"仓储"]
+
+**[抽象名称]：**
+- 用途：[它代表什么]
+- 示例：[具体示例]
+- 模式：[使用的模式]
+
+## 入口点
+
+[执行从哪里开始]
+
+**[入口点]：**
+- 位置：[简述：例如 "src/index.ts"、"API Gateway 触发"]
+- 触发方式：[什么调用它：例如 "CLI 调用"、"HTTP 请求"]
+- 职责：[它做什么：例如 "解析参数，路由到命令"]
+
+## 错误处理
+
+**策略：** [错误如何处理：例如 "异常冒泡到顶层处理器"、"每路由错误中间件"]
+
+**模式：**
+- [模式：例如 "在控制器层 try/catch"]
+- [模式：例如 "向用户返回错误码"]
+
+## 横切关注点
+
+[影响多个层的方面]
+
+**日志：**
+- [方法：例如 "Winston logger，每请求注入"]
+
+**验证：**
+- [方法：例如 "API 边界使用 Zod schema"]
+
+**认证：**
+- [方法：例如 "受保护路由使用 JWT 中间件"]
+
+---
+
+*架构分析：[date]*
+*主要模式变更时更新*
+```
+
+<good_examples>
+```markdown
+# 架构
+
+**分析日期：** 2025-01-20
+
+## 模式概览
+
+**整体：** 带插件系统的 CLI 应用
+
+**关键特征：**
+- 带子命令的单一可执行文件
+- 基于插件的可扩展性
+- 基于文件的状态（无数据库）
+- 同步执行模型
+
+## 分层
+
+**命令层：**
+- 用途：解析用户输入并路由到适当的处理器
+- 包含：命令定义、参数解析、帮助文本
+- 位置：`src/commands/*.ts`
+- 依赖：服务层提供业务逻辑
+- 被使用：CLI 入口点（`src/index.ts`）
+
+**服务层：**
+- 用途：核心业务逻辑
+- 包含：FileService、TemplateService、InstallService
+- 位置：`src/services/*.ts`
+- 依赖：文件系统工具、外部工具
+- 被使用：命令处理器
+
+**工具层：**
+- 用途：共享辅助函数和抽象
+- 包含：文件 I/O 封装、路径解析、字符串格式化
+- 位置：`src/utils/*.ts`
+- 依赖：仅 Node.js 内置模块
+- 被使用：服务层
+
+## 数据流
+
+**CLI 命令执行：**
+
+1. 用户运行：`specops new-project`
+2. Commander 解析参数和标志
+3. 调用命令处理器（`src/commands/new-project.ts`）
+4. 处理器调用服务方法（`src/services/project.ts` → `create()`）
+5. 服务读取模板、处理文件、写入输出
+6. 结果输出到控制台
+7. 进程以状态码退出
+
+**状态管理：**
+- 基于文件：所有状态存放在 `.planning/` 目录
+- 无持久内存状态
+- 每次命令执行独立
+
+## 关键抽象
+
+**Service：**
+- 用途：封装某个领域的业务逻辑
+- 示例：`src/services/file.ts`、`src/services/template.ts`、`src/services/project.ts`
+- 模式：类单例（作为模块导入，不实例化）
+
+**Command：**
+- 用途：CLI 命令定义
+- 示例：`src/commands/new-project.ts`、`src/commands/plan-phase.ts`
+- 模式：Commander.js 命令注册
+
+**Template：**
+- 用途：可复用的文档结构
+- 示例：PROJECT.md、PLAN.md 模板
+- 模式：带替换变量的 Markdown 文件
+
+## 入口点
+
+**CLI 入口：**
+- 位置：`src/index.ts`
+- 触发方式：用户运行 `specops <command>`
+- 职责：注册命令、解析参数、显示帮助
+
+**命令：**
+- 位置：`src/commands/*.ts`
+- 触发方式：CLI 匹配的命令
+- 职责：验证输入、调用服务、格式化输出
+
+## 错误处理
+
+**策略：** 抛出异常，在命令层捕获，记录日志并退出
+
+**模式：**
+- 服务抛出带描述性消息的 Error
+- 命令处理器捕获，将错误输出到 stderr，exit(1)
+- 验证错误在执行前显示（快速失败）
+
+## 横切关注点
+
+**日志：**
+- Console.log 用于正常输出
+- Console.error 用于错误
+- Chalk 用于彩色输出
+
+**验证：**
+- Zod schema 用于配置文件解析
+- 命令处理器中的手动验证
+- 无效输入时快速失败
+
+**文件操作：**
+- FileService 对 fs-extra 的抽象
+- 所有路径在操作前验证
+- 原子写入（临时文件 + 重命名）
+
+---
+
+*架构分析：2025-01-20*
+*主要模式变更时更新*
+```
+</good_examples>
+
+<guidelines>
+**ARCHITECTURE.md 中应包含的内容：**
+- 整体架构模式（单体、微服务、分层等）
+- 概念层及其关系
+- 数据流/请求生命周期
+- 关键抽象和模式
+- 入口点
+- 错误处理策略
+- 横切关注点（日志、认证、验证）
+
+**不应包含的内容：**
+- 详尽的文件列表（那是 STRUCTURE.md 的内容）
+- 技术选型（那是 STACK.md 的内容）
+- 逐行代码走读（参考代码阅读）
+- 特定功能的实现细节
+
+**欢迎包含文件路径：**
+包含文件路径作为抽象的具体示例。使用反引号格式：`src/services/user.ts`。这使架构文档在 Claude 规划时可操作。
+
+**填写此模板时：**
+- 阅读主入口点（index、server、main）
+- 通过阅读导入/依赖识别分层
+- 追踪典型的请求/命令执行流程
+- 记录反复出现的模式（services、controllers、repositories）
+- 保持描述在概念层面，而非机械层面
+
+**在阶段规划中的用途：**
+- 添加新功能时（它适合哪一层？）
+- 重构时（了解当前模式）
+- 识别代码放置位置（哪一层处理 X？）
+- 了解组件之间的依赖关系
+</guidelines>