specops 0.2.5 → 0.3.2

package/.opencode/templates/roadmap.md

@@ -0,0 +1,202 @@
+# 路线图模板
+
+`.planning/ROADMAP.md` 的模板。
+
+## 初始路线图 (v1.0 全新项目)
+
+```markdown
+# 路线图: [项目名称]
+
+## 概览
+
+[一段话描述从开始到完成的旅程]
+
+## 阶段
+
+**阶段编号:**
+- 整数阶段 (1, 2, 3): 计划中的里程碑工作
+- 小数阶段 (2.1, 2.2): 紧急插入 (标记为 INSERTED)
+
+小数阶段按数字顺序出现在相邻整数之间。
+
+- [ ] **阶段 1: [名称]** - [一句话描述]
+- [ ] **阶段 2: [名称]** - [一句话描述]
+- [ ] **阶段 3: [名称]** - [一句话描述]
+- [ ] **阶段 4: [名称]** - [一句话描述]
+
+## 阶段详情
+
+### 阶段 1: [名称]
+**目标**: [本阶段交付什么]
+**依赖**: 无 (第一阶段)
+**需求**: [REQ-01, REQ-02, REQ-03]  <!-- 括号可选，解析器两种格式都支持 -->
+**成功标准** (必须为真):
+  1. [从用户视角可观测的行为]
+  2. [从用户视角可观测的行为]
+  3. [从用户视角可观测的行为]
+**计划数**: [计划数量，如 "3 个计划" 或 "待定"]
+
+计划:
+- [ ] 01-01: [第一个计划的简要描述]
+- [ ] 01-02: [第二个计划的简要描述]
+- [ ] 01-03: [第三个计划的简要描述]
+
+### 阶段 2: [名称]
+**目标**: [本阶段交付什么]
+**依赖**: 阶段 1
+**需求**: [REQ-04, REQ-05]
+**成功标准** (必须为真):
+  1. [从用户视角可观测的行为]
+  2. [从用户视角可观测的行为]
+**计划数**: [计划数量]
+
+计划:
+- [ ] 02-01: [简要描述]
+- [ ] 02-02: [简要描述]
+
+### 阶段 2.1: 紧急修复 (INSERTED)
+**目标**: [在阶段间插入的紧急工作]
+**依赖**: 阶段 2
+**成功标准** (必须为真):
+  1. [修复达成的效果]
+**计划数**: 1 个计划
+
+计划:
+- [ ] 02.1-01: [描述]
+
+### 阶段 3: [名称]
+**目标**: [本阶段交付什么]
+**依赖**: 阶段 2
+**需求**: [REQ-06, REQ-07, REQ-08]
+**成功标准** (必须为真):
+  1. [从用户视角可观测的行为]
+  2. [从用户视角可观测的行为]
+  3. [从用户视角可观测的行为]
+**计划数**: [计划数量]
+
+计划:
+- [ ] 03-01: [简要描述]
+- [ ] 03-02: [简要描述]
+
+### 阶段 4: [名称]
+**目标**: [本阶段交付什么]
+**依赖**: 阶段 3
+**需求**: [REQ-09, REQ-10]
+**成功标准** (必须为真):
+  1. [从用户视角可观测的行为]
+  2. [从用户视角可观测的行为]
+**计划数**: [计划数量]
+
+计划:
+- [ ] 04-01: [简要描述]
+
+## 进度
+
+**执行顺序:**
+阶段按数字顺序执行: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| 阶段 | 计划完成 | 状态 | 完成时间 |
+|------|----------|------|----------|
+| 1. [名称] | 0/3 | 未开始 | - |
+| 2. [名称] | 0/2 | 未开始 | - |
+| 3. [名称] | 0/2 | 未开始 | - |
+| 4. [名称] | 0/1 | 未开始 | - |
+```
+
+<guidelines>
+**初始规划 (v1.0):**
+- 阶段数量取决于深度设置 (quick: 3-5, standard: 5-8, comprehensive: 8-12)
+- 每个阶段交付一个连贯的成果
+- 阶段可以有 1+ 个计划 (如果 >3 个任务或涉及多个子系统则拆分)
+- 计划命名: {phase}-{plan}-PLAN.md (如 01-02-PLAN.md)
+- 不做时间估算 (这不是企业项目管理)
+- 进度表由执行工作流更新
+- 计划数量初始可以是 "待定"，规划时细化
+
+**成功标准:**
+- 每阶段 2-5 个可观测行为 (从用户视角)
+- 路线图创建时与需求交叉检查
+- 向下游传递到 plan-phase 的 `must_haves`
+- 执行后由 verify-phase 验证
+- 格式: "用户可以 [操作]" 或 "[事物] 正常工作/存在"
+
+**里程碑发布后:**
+- 将已完成的里程碑折叠到 `<details>` 标签中
+- 为即将到来的工作添加新里程碑部分
+- 保持连续的阶段编号 (永远不要从 01 重新开始)
+</guidelines>
+
+<status_values>
+- `未开始` - 尚未开始
+- `进行中` - 正在进行
+- `已完成` - 完成 (添加完成日期)
+- `已延后` - 推迟到以后 (附原因)
+</status_values>
+
+## 里程碑分组路线图 (v1.0 发布后)
+
+完成第一个里程碑后，用里程碑分组重新组织:
+
+```markdown
+# 路线图: [项目名称]
+
+## 里程碑
+
+- ✅ **v1.0 MVP** - 阶段 1-4 (已发布 YYYY-MM-DD)
+- 🚧 **v1.1 [名称]** - 阶段 5-6 (进行中)
+- 📋 **v2.0 [名称]** - 阶段 7-10 (已规划)
+
+## 阶段
+
+<details>
+<summary>✅ v1.0 MVP (阶段 1-4) - 已发布 YYYY-MM-DD</summary>
+
+### 阶段 1: [名称]
+**目标**: [本阶段交付什么]
+**计划数**: 3 个计划
+
+计划:
+- [x] 01-01: [简要描述]
+- [x] 01-02: [简要描述]
+- [x] 01-03: [简要描述]
+
+[... 其余 v1.0 阶段 ...]
+
+</details>
+
+### 🚧 v1.1 [名称] (进行中)
+
+**里程碑目标:** [v1.1 交付什么]
+
+#### 阶段 5: [名称]
+**目标**: [本阶段交付什么]
+**依赖**: 阶段 4
+**计划数**: 2 个计划
+
+计划:
+- [ ] 05-01: [简要描述]
+- [ ] 05-02: [简要描述]
+
+[... 其余 v1.1 阶段 ...]
+
+### 📋 v2.0 [名称] (已规划)
+
+**里程碑目标:** [v2.0 交付什么]
+
+[... v2.0 阶段 ...]
+
+## 进度
+
+| 阶段 | 里程碑 | 计划完成 | 状态 | 完成时间 |
+|------|--------|----------|------|----------|
+| 1. 基础 | v1.0 | 3/3 | 已完成 | YYYY-MM-DD |
+| 2. 功能 | v1.0 | 2/2 | 已完成 | YYYY-MM-DD |
+| 5. 安全 | v1.1 | 0/2 | 未开始 | - |
+```
+
+**说明:**
+- 里程碑标记: ✅ 已发布, 🚧 进行中, 📋 已规划
+- 已完成的里程碑折叠在 `<details>` 中提高可读性
+- 当前/未来里程碑展开
+- 连续阶段编号 (01-99)
+- 进度表包含里程碑列

package/.opencode/templates/state.md

@@ -0,0 +1,176 @@
+# 状态模板
+
+`.planning/STATE.md` 的模板，项目的活记忆。
+
+---
+
+## 文件模板
+
+```markdown
+# 项目状态
+
+## 项目引用
+
+参见: .planning/PROJECT.md (更新于 [日期])
+
+**核心价值:** [PROJECT.md 核心价值部分的一句话]
+**当前焦点:** [当前阶段名称]
+
+## 当前位置
+
+阶段: [X] / [Y] ([阶段名称])
+计划: [A] / [B] (当前阶段内)
+状态: [准备规划 / 规划中 / 准备执行 / 执行中 / 阶段完成]
+最近活动: [YYYY-MM-DD] — [发生了什么]
+
+进度: [░░░░░░░░░░] 0%
+
+## 执行指标
+
+**速度:**
+- 已完成计划总数: [N]
+- 平均耗时: [X] 分钟
+- 总执行时间: [X.X] 小时
+
+**按阶段:**
+
+| 阶段 | 计划数 | 总耗时 | 平均/计划 |
+|------|--------|--------|-----------|
+| - | - | - | - |
+
+**近期趋势:**
+- 最近 5 个计划: [耗时]
+- 趋势: [改善 / 稳定 / 下降]
+
+*每次计划完成后更新*
+
+## 累积上下文
+
+### 决策
+
+决策记录在 PROJECT.md 关键决策表中。
+影响当前工作的近期决策:
+
+- [阶段 X]: [决策摘要]
+- [阶段 Y]: [决策摘要]
+
+### 待办事项
+
+[来自 .planning/todos/pending/ 的会话中捕获的想法]
+
+暂无。
+
+### 阻塞/关注
+
+[影响未来工作的问题]
+
+暂无。
+
+## 会话连续性
+
+上次会话: [YYYY-MM-DD HH:MM]
+停在: [最后完成操作的描述]
+恢复文件: [.continue-here*.md 的路径（如存在），否则 "无"]
+```
+
+<purpose>
+
+STATE.md 是项目跨所有阶段和会话的短期记忆。
+
+**解决的问题:** 信息被记录在总结、问题和决策中，但没有被系统性地消费。会话启动时缺乏上下文。
+
+**解决方案:** 一个小型文件:
+- 每个工作流首先读取
+- 每次重要操作后更新
+- 包含累积上下文的摘要
+- 支持即时会话恢复
+
+</purpose>
+
+<lifecycle>
+
+**创建:** ROADMAP.md 创建后 (初始化期间)
+- 引用 PROJECT.md (读取获取当前上下文)
+- 初始化空的累积上下文部分
+- 设置位置为 "阶段 1 准备规划"
+
+**读取:** 每个工作流的第一步
+- progress: 向用户展示状态
+- plan: 指导规划决策
+- execute: 了解当前位置
+- transition: 了解已完成的内容
+
+**写入:** 每次重要操作后
+- execute: SUMMARY.md 创建后
+  - 更新位置 (阶段、计划、状态)
+  - 记录新决策 (详情在 PROJECT.md)
+  - 添加阻塞/关注
+- transition: 阶段标记完成后
+  - 更新进度条
+  - 清除已解决的阻塞
+  - 刷新项目引用日期
+
+</lifecycle>
+
+<sections>
+
+### 项目引用
+指向 PROJECT.md 获取完整上下文。包含:
+- 核心价值 (最重要的一件事)
+- 当前焦点 (哪个阶段)
+- 最后更新日期 (过期时触发重新读取)
+
+Claude 直接读取 PROJECT.md 获取需求、约束和决策。
+
+### 当前位置
+我们现在在哪里:
+- 阶段 X / Y — 哪个阶段
+- 计划 A / B — 阶段内哪个计划
+- 状态 — 当前状态
+- 最近活动 — 最近发生了什么
+- 进度条 — 整体完成度的可视化指标
+
+进度计算: (已完成计划) / (所有阶段的总计划数) × 100%
+
+### 执行指标
+追踪速度以了解执行模式:
+- 已完成计划总数
+- 每个计划的平均耗时
+- 按阶段分解
+- 近期趋势 (改善/稳定/下降)
+
+每次计划完成后更新。
+
+### 累积上下文
+
+**决策:** 引用 PROJECT.md 关键决策表，加上近期决策摘要便于快速访问。完整决策日志在 PROJECT.md 中。
+
+**待办事项:** 通过 /specops:add-todo 捕获的想法
+- 待办事项数量
+- 引用 .planning/todos/pending/
+- 少量时列出，多时显示数量 (如 "5 个待办事项，参见 /specops:check-todos")
+
+**阻塞/关注:** 来自 "下一阶段准备" 部分
+- 影响未来工作的问题
+- 前缀标注来源阶段
+- 解决后清除
+
+### 会话连续性
+支持即时恢复:
+- 上次会话时间
+- 最后完成的内容
+- 是否有 .continue-here 文件可恢复
+
+</sections>
+
+<size_constraint>
+
+保持 STATE.md 在 100 行以内。
+
+它是摘要，不是归档。如果累积上下文增长过大:
+- 只保留 3-5 个近期决策摘要 (完整日志在 PROJECT.md)
+- 只保留活跃的阻塞，移除已解决的
+
+目标是 "读一次，知道我们在哪" — 如果太长，这个目标就失败了。
+
+</size_constraint>

package/.opencode/templates/summary-complex.md

@@ -0,0 +1,59 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [主要类别]
+tags: [可搜索的技术标签]
+requires:
+  - phase: [前置阶段]
+    provides: [该阶段构建的内容]
+provides:
+  - [构建/交付内容的列表]
+affects: [受影响的阶段名称或关键词列表]
+tech-stack:
+  added: [新增的库/工具]
+  patterns: [架构/代码模式]
+key-files:
+  created: [创建的重要文件]
+  modified: [修改的重要文件]
+key-decisions:
+  - "决策 1"
+patterns-established:
+  - "模式 1: 描述"
+duration: X分钟
+completed: YYYY-MM-DD
+---
+
+# 阶段 [X]: [名称] 总结 (复杂版)
+
+**[描述成果的实质性一句话]**
+
+## 执行表现
+- **耗时:** [时间]
+- **任务:** [完成数量]
+- **修改文件:** [数量]
+
+## 完成事项
+- [关键成果 1]
+- [关键成果 2]
+
+## 任务提交
+1. **任务 1: [任务名称]** - `hash`
+2. **任务 2: [任务名称]** - `hash`
+3. **任务 3: [任务名称]** - `hash`
+
+## 创建/修改的文件
+- `path/to/file.ts` - 功能说明
+- `path/to/another.ts` - 功能说明
+
+## 做出的决策
+[关键决策及简要理由]
+
+## 计划偏差（自动修复）
+[按 SpecOps 偏差规则记录的详细自动修复]
+
+## 遇到的问题
+[计划内工作中的问题及解决方式]
+
+## 下一阶段准备
+[为下一阶段准备好了什么]
+[阻塞或关注点]

package/.opencode/templates/summary-minimal.md

@@ -0,0 +1,41 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [主要类别]
+tags: [可搜索的技术标签]
+provides:
+  - [构建/交付内容的列表]
+affects: [受影响的阶段名称或关键词列表]
+tech-stack:
+  added: [新增的库/工具]
+  patterns: [架构/代码模式]
+key-files:
+  created: [创建的重要文件]
+  modified: [修改的重要文件]
+key-decisions: []
+duration: X分钟
+completed: YYYY-MM-DD
+---
+
+# 阶段 [X]: [名称] 总结 (精简版)
+
+**[描述成果的实质性一句话]**
+
+## 执行表现
+- **耗时:** [时间]
+- **任务:** [数量]
+- **修改文件:** [数量]
+
+## 完成事项
+- [最重要的成果]
+- [第二个关键成果]
+
+## 任务提交
+1. **任务 1: [任务名称]** - `hash`
+2. **任务 2: [任务名称]** - `hash`
+
+## 创建/修改的文件
+- `path/to/file.ts` - 功能说明
+
+## 下一阶段准备
+[为下一阶段准备好了什么]

package/.opencode/templates/summary-standard.md

@@ -0,0 +1,48 @@
+---
+phase: XX-name
+plan: YY
+subsystem: [主要类别]
+tags: [可搜索的技术标签]
+provides:
+  - [构建/交付内容的列表]
+affects: [受影响的阶段名称或关键词列表]
+tech-stack:
+  added: [新增的库/工具]
+  patterns: [架构/代码模式]
+key-files:
+  created: [创建的重要文件]
+  modified: [修改的重要文件]
+key-decisions:
+  - "决策 1"
+duration: X分钟
+completed: YYYY-MM-DD
+---
+
+# 阶段 [X]: [名称] 总结
+
+**[描述成果的实质性一句话]**
+
+## 执行表现
+- **耗时:** [时间]
+- **任务:** [完成数量]
+- **修改文件:** [数量]
+
+## 完成事项
+- [关键成果 1]
+- [关键成果 2]
+
+## 任务提交
+1. **任务 1: [任务名称]** - `hash`
+2. **任务 2: [任务名称]** - `hash`
+3. **任务 3: [任务名称]** - `hash`
+
+## 创建/修改的文件
+- `path/to/file.ts` - 功能说明
+- `path/to/another.ts` - 功能说明
+
+## 决策与偏差
+[关键决策或 "无偏差，按计划执行"]
+[轻微偏差（如有），或 "无"]
+
+## 下一阶段准备
+[为下一阶段准备好了什么]