specops 0.2.4 → 0.3.0

package/.opencode/templates/research-project/STACK.md

@@ -0,0 +1,120 @@
+# 技术栈研究模板
+
+`.planning/research/STACK.md` 的模板，项目领域的推荐技术。
+
+<template>
+
+```markdown
+# 技术栈研究
+
+**领域:** [领域类型]
+**研究时间:** [日期]
+**置信度:** [高/中/低]
+
+## 推荐技术栈
+
+### 核心技术
+
+| 技术 | 版本 | 用途 | 为什么推荐 |
+|------|------|------|-----------|
+| [名称] | [版本] | [功能] | [该领域专家为什么用它] |
+| [名称] | [版本] | [功能] | [该领域专家为什么用它] |
+| [名称] | [版本] | [功能] | [该领域专家为什么用它] |
+
+### 辅助库
+
+| 库 | 版本 | 用途 | 何时使用 |
+|----|------|------|----------|
+| [名称] | [版本] | [功能] | [具体使用场景] |
+| [名称] | [版本] | [功能] | [具体使用场景] |
+| [名称] | [版本] | [功能] | [具体使用场景] |
+
+### 开发工具
+
+| 工具 | 用途 | 备注 |
+|------|------|------|
+| [名称] | [功能] | [配置提示] |
+| [名称] | [功能] | [配置提示] |
+
+## 安装
+
+```bash
+# 核心
+npm install [packages]
+
+# 辅助
+npm install [packages]
+
+# 开发依赖
+npm install -D [packages]
+```
+
+## 考虑过的替代方案
+
+| 推荐 | 替代方案 | 何时使用替代方案 |
+|------|---------|----------------|
+| [我们的选择] | [其他选项] | [替代方案更好的条件] |
+| [我们的选择] | [其他选项] | [替代方案更好的条件] |
+
+## 不要使用
+
+| 避免 | 原因 | 改用 |
+|------|------|------|
+| [技术] | [具体问题] | [推荐替代] |
+| [技术] | [具体问题] | [推荐替代] |
+
+## 按变体的技术栈模式
+
+**如果 [条件]:**
+- 使用 [变体]
+- 因为 [原因]
+
+**如果 [条件]:**
+- 使用 [变体]
+- 因为 [原因]
+
+## 版本兼容性
+
+| 包 A | 兼容 | 备注 |
+|------|------|------|
+| [package@version] | [package@version] | [兼容性说明] |
+
+## 来源
+
+- [Context7 库 ID] — [获取的主题]
+- [官方文档 URL] — [验证了什么]
+- [其他来源] — [置信度级别]
+
+---
+*技术栈研究领域: [领域]*
+*研究时间: [日期]*
+```
+
+</template>
+
+<guidelines>
+
+**核心技术:**
+- 包含具体版本号
+- 解释为什么是标准选择，不只是它做什么
+- 聚焦影响架构决策的技术
+
+**辅助库:**
+- 包含该领域常需的库
+- 注明每个何时需要 (不是所有项目都需要所有库)
+
+**替代方案:**
+- 不要只是否定替代方案
+- 解释替代方案何时有意义
+- 帮助用户在不同意时做出知情决策
+
+**不要使用:**
+- 主动警告过时或有问题的选择
+- 解释具体问题，不只是 "它旧了"
+- 提供推荐的替代方案
+
+**版本兼容性:**
+- 记录已知的兼容性问题
+- 对避免后续调试时间至关重要
+
+</guidelines>

package/.opencode/templates/research-project/SUMMARY.md

@@ -0,0 +1,170 @@
+# 研究摘要模板
+
+`.planning/research/SUMMARY.md` 的模板，项目研究的执行摘要及路线图影响。
+
+<template>
+
+```markdown
+# 项目研究摘要
+
+**项目:** [来自 PROJECT.md 的名称]
+**领域:** [推断的领域类型]
+**研究时间:** [日期]
+**置信度:** [高/中/低]
+
+## 执行摘要
+
+[2-3 段研究发现概述]
+
+- 这是什么类型的产品，专家如何构建它
+- 基于研究的推荐方案
+- 关键风险及缓解方式
+
+## 关键发现
+
+### 推荐技术栈
+
+[STACK.md 的摘要 — 1-2 段]
+
+**核心技术:**
+- [技术]: [用途] — [为什么推荐]
+- [技术]: [用途] — [为什么推荐]
+- [技术]: [用途] — [为什么推荐]
+
+### 预期功能
+
+[FEATURES.md 的摘要]
+
+**必须有 (基本功能):**
+- [功能] — 用户期望这个
+- [功能] — 用户期望这个
+
+**应该有 (竞争性):**
+- [功能] — 差异化
+- [功能] — 差异化
+
+**延后 (v2+):**
+- [功能] — 发布时非必要
+
+### 架构方案
+
+[ARCHITECTURE.md 的摘要 — 1 段]
+
+**主要组件:**
+1. [组件] — [职责]
+2. [组件] — [职责]
+3. [组件] — [职责]
+
+### 关键陷阱
+
+[PITFALLS.md 的前 3-5 个]
+
+1. **[陷阱]** — [如何避免]
+2. **[陷阱]** — [如何避免]
+3. **[陷阱]** — [如何避免]
+
+## 对路线图的影响
+
+基于研究，建议的阶段结构:
+
+### 阶段 1: [名称]
+**理由:** [为什么这个排第一，基于研究]
+**交付:** [本阶段产出什么]
+**涉及:** [FEATURES.md 中的功能]
+**避免:** [PITFALLS.md 中的陷阱]
+
+### 阶段 2: [名称]
+**理由:** [为什么这个顺序]
+**交付:** [本阶段产出什么]
+**使用:** [STACK.md 中的技术栈元素]
+**实现:** [架构组件]
+
+### 阶段 3: [名称]
+**理由:** [为什么这个顺序]
+**交付:** [本阶段产出什么]
+
+[继续建议的阶段...]
+
+### 阶段排序理由
+
+- [为什么这个顺序，基于发现的依赖]
+- [为什么这样分组，基于架构模式]
+- [如何避免研究中的陷阱]
+
+### 研究标记
+
+规划时可能需要更深入研究的阶段:
+- **阶段 [X]:** [原因 — 如 "复杂集成，需要 API 研究"]
+- **阶段 [Y]:** [原因 — 如 "利基领域，文档稀疏"]
+
+有标准模式的阶段 (可跳过 research-phase):
+- **阶段 [X]:** [原因 — 如 "文档完善，模式成熟"]
+
+## 置信度评估
+
+| 领域 | 置信度 | 备注 |
+|------|--------|------|
+| 技术栈 | [高/中/低] | [原因] |
+| 功能 | [高/中/低] | [原因] |
+| 架构 | [高/中/低] | [原因] |
+| 陷阱 | [高/中/低] | [原因] |
+
+**总体置信度:** [高/中/低]
+
+### 待解决的缺口
+
+[研究中不确定或需要在实现时验证的领域]
+
+- [缺口]: [规划/执行时如何处理]
+- [缺口]: [规划/执行时如何处理]
+
+## 来源
+
+### 主要 (高置信度)
+- [Context7 库 ID] — [主题]
+- [官方文档 URL] — [检查了什么]
+
+### 次要 (中置信度)
+- [来源] — [发现]
+
+### 第三方 (低置信度)
+- [来源] — [发现，需验证]
+
+---
+*研究完成: [日期]*
+*可以开始路线图: 是*
+```
+
+</template>
+
+<guidelines>
+
+**执行摘要:**
+- 为只读这一部分的人写
+- 包含关键建议和主要风险
+- 最多 2-3 段
+
+**关键发现:**
+- 总结，不要复制完整文档
+- 链接到详细文档 (STACK.md, FEATURES.md 等)
+- 聚焦对路线图决策重要的内容
+
+**对路线图的影响:**
+- 这是最重要的部分
+- 直接指导路线图创建
+- 明确说明阶段建议和理由
+- 为每个建议的阶段包含研究标记
+
+**置信度评估:**
+- 对不确定性诚实
+- 记录规划时需要解决的缺口
+- 高 = 官方来源验证
+- 中 = 社区共识，多个来源一致
+- 低 = 单一来源或推断
+
+**与路线图创建的集成:**
+- 此文件在路线图创建时作为上下文加载
+- 这里的阶段建议成为路线图的起点
+- 研究标记指导阶段规划
+
+</guidelines>

package/.opencode/templates/research.md

@@ -0,0 +1,278 @@
+# 研究模板
+
+`.planning/phases/XX-name/{phase_num}-RESEARCH.md` 的模板，用于规划前的全面生态系统研究。
+
+**用途:** 记录 Claude 实现某个阶段所需的知识，不仅是 "用哪个库"，更是 "专家如何构建这个"。
+
+---
+
+## 文件模板
+
+```markdown
+# 阶段 [X]: [名称] - 研究
+
+**研究时间:** [日期]
+**领域:** [主要技术/问题领域]
+**置信度:** [高/中/低]
+
+<user_constraints>
+## 用户约束 (来自 CONTEXT.md)
+
+**关键:** 如果 /specops:discuss-phase 生成了 CONTEXT.md，将锁定的决策逐字复制到这里。规划者必须遵守这些决策。
+
+### 锁定的决策
+[从 CONTEXT.md `## 决策` 部分复制，这些是不可协商的]
+- [决策 1]
+- [决策 2]
+
+### Claude 自行决定
+[从 CONTEXT.md 复制，研究者/规划者可以在这些领域自行选择]
+- [领域 1]
+- [领域 2]
+
+### 延后的想法 (超出范围)
+[从 CONTEXT.md 复制，不要研究或规划这些]
+- [延后 1]
+- [延后 2]
+
+**如果没有 CONTEXT.md:** 写 "无用户约束，所有决策由 Claude 自行决定"
+</user_constraints>
+
+<research_summary>
+## 摘要
+
+[2-3 段执行摘要]
+- 研究了什么
+- 标准方法是什么
+- 关键建议
+
+**首要建议:** [一句话可操作的指导]
+</research_summary>
+
+<standard_stack>
+## 标准技术栈
+
+该领域已确立的库/工具:
+
+### 核心
+| 库 | 版本 | 用途 | 为何是标准 |
+|----|------|------|-----------|
+| [名称] | [版本] | [功能] | [专家为何使用它] |
+| [名称] | [版本] | [功能] | [专家为何使用它] |
+
+### 辅助
+| 库 | 版本 | 用途 | 何时使用 |
+|----|------|------|----------|
+| [名称] | [版本] | [功能] | [使用场景] |
+| [名称] | [版本] | [功能] | [使用场景] |
+
+### 考虑过的替代方案
+| 替代 | 可用 | 权衡 |
+|------|------|------|
+| [标准] | [替代方案] | [替代方案何时更合适] |
+
+**安装:**
+```bash
+npm install [packages]
+# 或
+yarn add [packages]
+```
+</standard_stack>
+
+<architecture_patterns>
+## 架构模式
+
+### 推荐项目结构
+```
+src/
+├── [文件夹]/        # [用途]
+├── [文件夹]/        # [用途]
+└── [文件夹]/        # [用途]
+```
+
+### 模式 1: [模式名称]
+**是什么:** [描述]
+**何时使用:** [条件]
+**示例:**
+```typescript
+// [来自 Context7/官方文档的代码示例]
+```
+
+### 模式 2: [模式名称]
+**是什么:** [描述]
+**何时使用:** [条件]
+**示例:**
+```typescript
+// [代码示例]
+```
+
+### 应避免的反模式
+- **[反模式]:** [为什么不好，应该怎么做]
+- **[反模式]:** [为什么不好，应该怎么做]
+</architecture_patterns>
+
+<dont_hand_roll>
+## 不要自己造轮子
+
+看起来简单但已有现成解决方案的问题:
+
+| 问题 | 不要自己写 | 改用 | 原因 |
+|------|-----------|------|------|
+| [问题] | [你会写的东西] | [库] | [边界情况、复杂度] |
+| [问题] | [你会写的东西] | [库] | [边界情况、复杂度] |
+| [问题] | [你会写的东西] | [库] | [边界情况、复杂度] |
+
+**关键洞察:** [为什么在这个领域自定义方案更差]
+</dont_hand_roll>
+
+<common_pitfalls>
+## 常见陷阱
+
+### 陷阱 1: [名称]
+**会出什么问题:** [描述]
+**为什么会发生:** [根本原因]
+**如何避免:** [预防策略]
+**预警信号:** [如何早期发现]
+
+### 陷阱 2: [名称]
+**会出什么问题:** [描述]
+**为什么会发生:** [根本原因]
+**如何避免:** [预防策略]
+**预警信号:** [如何早期发现]
+
+### 陷阱 3: [名称]
+**会出什么问题:** [描述]
+**为什么会发生:** [根本原因]
+**如何避免:** [预防策略]
+**预警信号:** [如何早期发现]
+</common_pitfalls>
+
+<code_examples>
+## 代码示例
+
+来自权威来源的已验证模式:
+
+### [常见操作 1]
+```typescript
+// 来源: [Context7/官方文档 URL]
+[代码]
+```
+
+### [常见操作 2]
+```typescript
+// 来源: [Context7/官方文档 URL]
+[代码]
+```
+
+### [常见操作 3]
+```typescript
+// 来源: [Context7/官方文档 URL]
+[代码]
+```
+</code_examples>
+
+<sota_updates>
+## 技术前沿 (2024-2025)
+
+最近的变化:
+
+| 旧方法 | 当前方法 | 变更时间 | 影响 |
+|--------|---------|---------|------|
+| [旧] | [新] | [日期/版本] | [对实现的意义] |
+
+**值得考虑的新工具/模式:**
+- [工具/模式]: [它能做什么，何时使用]
+- [工具/模式]: [它能做什么，何时使用]
+
+**已弃用/过时:**
+- [事物]: [为什么过时，替代品是什么]
+</sota_updates>
+
+<open_questions>
+## 待解决问题
+
+无法完全解决的事项:
+
+1. **[问题]**
+   - 已知: [部分信息]
+   - 不确定: [缺口]
+   - 建议: [规划/执行时如何处理]
+
+2. **[问题]**
+   - 已知: [部分信息]
+   - 不确定: [缺口]
+   - 建议: [如何处理]
+</open_questions>
+
+<sources>
+## 来源
+
+### 主要 (高置信度)
+- [Context7 库 ID] - [获取的主题]
+- [官方文档 URL] - [检查了什么]
+
+### 次要 (中置信度)
+- [WebSearch 已用官方来源验证] - [发现 + 验证]
+
+### 第三方 (低置信度，需验证)
+- [仅 WebSearch] - [发现，标记为实现时验证]
+</sources>
+
+<metadata>
+## 元数据
+
+**研究范围:**
+- 核心技术: [什么]
+- 生态系统: [探索的库]
+- 模式: [研究的模式]
+- 陷阱: [检查的领域]
+
+**置信度分解:**
+- 标准技术栈: [高/中/低] - [原因]
+- 架构: [高/中/低] - [原因]
+- 陷阱: [高/中/低] - [原因]
+- 代码示例: [高/中/低] - [原因]
+
+**研究日期:** [日期]
+**有效期至:** [估计，稳定技术 30 天，快速变化的 7 天]
+</metadata>
+
+---
+
+*阶段: XX-name*
+*研究完成: [日期]*
+*可以开始规划: [是/否]*
+```
+
+---
+
+## 指南
+
+**何时创建:**
+- 在利基/复杂领域规划阶段之前
+- 当 Claude 的训练数据可能过时或稀疏时
+- 当 "专家如何构建这个" 比 "用哪个库" 更重要时
+
+**结构:**
+- 使用 XML 标签作为章节标记 (匹配 SpecOps 模板)
+- 七个核心章节: summary, standard_stack, architecture_patterns, dont_hand_roll, common_pitfalls, code_examples, sources
+- 所有章节必填 (驱动全面研究)
+
+**内容质量:**
+- 标准技术栈: 具体版本号，不只是名称
+- 架构: 包含来自权威来源的实际代码示例
+- 不要造轮子: 明确说明哪些问题不要自己解决
+- 陷阱: 包含预警信号，不只是 "不要这样做"
+- 来源: 诚实标记置信度
+
+**与规划的集成:**
+- RESEARCH.md 作为 PLAN.md 中的 @context 引用加载
+- 标准技术栈指导库选择
+- 不要造轮子防止自定义方案
+- 陷阱指导验证标准
+- 代码示例可在任务操作中引用
+
+**创建后:**
+- 文件位于阶段目录: `.planning/phases/XX-name/{phase_num}-RESEARCH.md`
+- 在规划工作流中引用
+- plan-phase 存在时自动加载

package/.opencode/templates/retrospective.md

@@ -0,0 +1,54 @@
+# 项目回顾
+
+*每个里程碑完成后更新的活文档。经验教训向前传递到未来规划中。*
+
+## 里程碑: v{version} — {name}
+
+**发布:** {date}
+**阶段:** {count} | **计划:** {count} | **会话:** {count}
+
+### 构建了什么
+- {关键交付物 1}
+- {关键交付物 2}
+- {关键交付物 3}
+
+### 什么做得好
+- {效率提升或成功的模式}
+- {顺利进行的部分}
+
+### 什么效率低
+- {错失的机会}
+- {比预期耗时更长的部分}
+
+### 建立的模式
+- {应该持续使用的新模式或约定}
+
+### 关键教训
+1. {具体、可操作的教训}
+2. {另一个教训}
+
+### 成本观察
+- 模型组合: {X}% opus, {Y}% sonnet, {Z}% haiku
+- 会话数: {count}
+- 值得注意: {效率观察}
+
+---
+
+## 跨里程碑趋势
+
+### 流程演进
+
+| 里程碑 | 会话数 | 阶段数 | 关键变化 |
+|--------|--------|--------|----------|
+| v{X} | {N} | {M} | {流程中的变化} |
+
+### 累积质量
+
+| 里程碑 | 测试数 | 覆盖率 | 零依赖新增 |
+|--------|--------|--------|------------|
+| v{X} | {N} | {Y}% | {count} |
+
+### 顶级教训（跨里程碑验证）
+
+1. {多个里程碑验证的教训}
+2. {另一个交叉验证的教训}