specops 0.2.5 → 0.3.2

package/.opencode/templates/continue-here.md

@@ -0,0 +1,78 @@
+# 继续点模板
+
+复制并填写此结构到 `.planning/phases/XX-name/.continue-here.md`:
+
+```yaml
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<current_state>
+[我们现在确切在哪里？当前的即时上下文是什么？]
+</current_state>
+
+<completed_work>
+[本次会话完成了什么，要具体]
+
+- 任务 1: [名称] - 完成
+- 任务 2: [名称] - 完成
+- 任务 3: [名称] - 进行中, [已完成的部分]
+</completed_work>
+
+<remaining_work>
+[本阶段还剩什么]
+
+- 任务 3: [名称] - [还需要做什么]
+- 任务 4: [名称] - 未开始
+- 任务 5: [名称] - 未开始
+</remaining_work>
+
+<decisions_made>
+[关键决策及原因，这样下次会话不用重新讨论]
+
+- 决定使用 [X] 因为 [原因]
+- 选择 [方案] 而非 [替代方案] 因为 [原因]
+</decisions_made>
+
+<blockers>
+[卡住的或等待外部因素的事项]
+
+- [阻塞 1]: [状态/变通方案]
+</blockers>
+
+<context>
+[心理状态、"感觉"、任何有助于顺利恢复的信息]
+
+[你在想什么？计划是什么？
+这是 "从上次离开的地方精确继续" 的上下文。]
+</context>
+
+<next_action>
+[恢复时要做的第一件事]
+
+从这里开始: [具体操作]
+</next_action>
+```
+
+<yaml_fields>
+必需的 YAML frontmatter:
+
+- `phase`: 目录名 (如 `02-authentication`)
+- `task`: 当前任务编号
+- `total_tasks`: 阶段中的任务总数
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: ISO 时间戳
+</yaml_fields>
+
+<guidelines>
+- 要足够具体，让全新的 Claude 实例能立即理解
+- 包含决策的原因，不只是做了什么
+- `<next_action>` 应该不需要读其他东西就能执行
+- 此文件在恢复后会被删除，不是永久存储
+</guidelines>

package/.opencode/templates/debug-subagent-prompt.md

@@ -0,0 +1,91 @@
+# 调试子代理提示模板
+
+用于生成 specops-debugger 代理的模板。代理包含所有调试专业知识，此模板仅提供问题上下文。
+
+---
+
+## 模板
+
+```markdown
+<objective>
+调查问题: {issue_id}
+
+**摘要:** {issue_summary}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: {true_or_false}
+goal: {find_root_cause_only | find_and_fix}
+</mode>
+
+<debug_file>
+创建: .planning/debug/{slug}.md
+</debug_file>
+```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 | 示例 |
+|--------|------|------|
+| `{issue_id}` | 编排器分配 | `auth-screen-dark` |
+| `{issue_summary}` | 用户描述 | `认证页面太暗` |
+| `{expected}` | 来自症状 | `能清楚看到 logo` |
+| `{actual}` | 来自症状 | `页面很暗` |
+| `{errors}` | 来自症状 | `控制台无错误` |
+| `{reproduction}` | 来自症状 | `打开 /auth 页面` |
+| `{timeline}` | 来自症状 | `最近部署后` |
+| `{goal}` | 编排器设置 | `find_and_fix` |
+| `{slug}` | 生成的 | `auth-screen-dark` |
+
+---
+
+## 用法
+
+**从 /specops:debug:**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="specops-debugger",
+  description="调试 {slug}"
+)
+```
+
+**从 diagnose-issues (UAT):**
+```python
+Task(prompt=template, subagent_type="specops-debugger", description="调试 UAT-001")
+```
+
+---
+
+## 续接
+
+对于检查点，用以下内容生成新代理:
+
+```markdown
+<objective>
+继续调试 {slug}。证据在调试文件中。
+</objective>
+
+<prior_state>
+调试文件: @.planning/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**类型:** {checkpoint_type}
+**响应:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: {goal}
+</mode>
+```

package/.opencode/templates/discovery.md

@@ -0,0 +1,147 @@
+# 发现模板
+
+`.planning/phases/XX-name/DISCOVERY.md` 的模板，用于库/选项决策的浅层研究。
+
+**用途:** 在 plan-phase 的强制发现阶段回答 "应该用哪个库/选项" 的问题。
+
+深度生态系统研究 ("专家如何构建这个") 请使用 `/specops:research-phase`，它会生成 RESEARCH.md。
+
+---
+
+## 文件模板
+
+```markdown
+---
+phase: XX-name
+type: discovery
+topic: [发现主题]
+---
+
+<session_initialization>
+开始发现前，验证今天的日期:
+!`date +%Y-%m-%d`
+
+搜索 "当前" 或 "最新" 信息时使用此日期。
+示例: 如果今天是 2025-11-22，搜索 "2025" 而非 "2024"。
+</session_initialization>
+
+<discovery_objective>
+发现 [主题] 以指导 [阶段名称] 的实现。
+
+目的: [此发现支持什么决策/实现]
+范围: [边界]
+输出: 包含建议的 DISCOVERY.md
+</discovery_objective>
+
+<discovery_scope>
+<include>
+- [需要回答的问题]
+- [需要调查的领域]
+- [需要的具体比较]
+</include>
+
+<exclude>
+- [此次发现范围外的内容]
+- [延后到实现阶段的内容]
+</exclude>
+</discovery_scope>
+
+<discovery_protocol>
+
+**来源优先级:**
+1. **Context7 MCP** - 用于库/框架文档 (当前、权威)
+2. **官方文档** - 用于平台特定或未索引的库
+3. **WebSearch** - 用于比较、趋势、社区模式 (验证所有发现)
+
+**质量检查清单:**
+完成发现前，验证:
+- [ ] 所有声明有权威来源 (Context7 或官方文档)
+- [ ] 否定声明 ("X 不可能") 已用官方文档验证
+- [ ] API 语法/配置来自 Context7 或官方文档 (绝不仅靠 WebSearch)
+- [ ] WebSearch 发现已与权威来源交叉验证
+- [ ] 已检查最近的更新/变更日志中的破坏性变更
+- [ ] 已考虑替代方案 (不只是找到的第一个方案)
+
+**置信度级别:**
+- 高: Context7 或官方文档确认
+- 中: WebSearch + Context7/官方文档确认
+- 低: 仅 WebSearch 或仅训练知识 (标记需验证)
+
+</discovery_protocol>
+
+
+<output_structure>
+创建 `.planning/phases/XX-name/DISCOVERY.md`:
+
+```markdown
+# [主题] 发现
+
+## 摘要
+[2-3 段执行摘要，研究了什么、发现了什么、建议什么]
+
+## 首要建议
+[做什么以及为什么，具体且可操作]
+
+## 考虑过的替代方案
+[还评估了什么以及为什么没选]
+
+## 关键发现
+
+### [类别 1]
+- [发现及来源 URL 和与我们情况的相关性]
+
+### [类别 2]
+- [发现及来源 URL 和相关性]
+
+## 代码示例
+[相关的实现模式（如适用）]
+
+## 元数据
+
+<metadata>
+<confidence level="high|medium|low">
+[为什么是这个置信度级别，基于来源质量和验证]
+</confidence>
+
+<sources>
+- [使用的主要权威来源]
+</sources>
+
+<open_questions>
+[无法确定或需要在实现时验证的内容]
+</open_questions>
+
+<validation_checkpoints>
+[如果置信度为低或中，列出实现时需要验证的具体事项]
+</validation_checkpoints>
+</metadata>
+```
+</output_structure>
+
+<success_criteria>
+- 所有范围内的问题已用权威来源回答
+- 质量检查清单项目已完成
+- 有明确的首要建议
+- 低置信度发现已标记验证检查点
+- 可以指导 PLAN.md 的创建
+</success_criteria>
+
+<guidelines>
+**何时使用发现:**
+- 技术选择不明确 (库 A vs B)
+- 不熟悉的集成需要最佳实践
+- 需要 API/库调查
+- 单个决策待定
+
+**何时不使用:**
+- 已确立的模式 (CRUD、使用已知库的认证)
+- 实现细节 (延后到执行)
+- 可从现有项目上下文回答的问题
+
+**何时改用 RESEARCH.md:**
+- 利基/复杂领域 (3D、游戏、音频、着色器)
+- 需要生态系统知识，不只是库选择
+- "专家如何构建这个" 类问题
+- 使用 `/specops:research-phase` 处理这些
+</guidelines>
+```

package/.opencode/templates/milestone-archive.md

@@ -0,0 +1,123 @@
+# 里程碑归档模板
+
+此模板由 complete-milestone 工作流使用，在 `.planning/milestones/` 中创建归档文件。
+
+---
+
+## 文件模板
+
+# 里程碑 v{{VERSION}}: {{MILESTONE_NAME}}
+
+**状态:** ✅ 已发布 {{DATE}}
+**阶段:** {{PHASE_START}}-{{PHASE_END}}
+**总计划数:** {{TOTAL_PLANS}}
+
+## 概览
+
+{{MILESTONE_DESCRIPTION}}
+
+## 阶段
+
+{{PHASES_SECTION}}
+
+[对此里程碑中的每个阶段，包含:]
+
+### 阶段 {{PHASE_NUM}}: {{PHASE_NAME}}
+
+**目标**: {{PHASE_GOAL}}
+**依赖**: {{DEPENDS_ON}}
+**计划数**: {{PLAN_COUNT}} 个计划
+
+计划:
+
+- [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
+- [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
+      [... 所有计划 ...]
+
+**详情:**
+{{PHASE_DETAILS_FROM_ROADMAP}}
+
+**对于小数阶段，包含 (INSERTED) 标记:**
+
+### 阶段 2.1: 关键安全补丁 (INSERTED)
+
+**目标**: 修复认证绕过漏洞
+**依赖**: 阶段 2
+**计划数**: 1 个计划
+
+计划:
+
+- [x] 02.1-01: 修补认证漏洞
+
+**详情:**
+{{PHASE_DETAILS_FROM_ROADMAP}}
+
+---
+
+## 里程碑总结
+
+**小数阶段:**
+
+- 阶段 2.1: 关键安全补丁 (在阶段 2 后插入用于紧急修复)
+- 阶段 5.1: 性能热修复 (在阶段 5 后插入用于生产问题)
+
+**关键决策:**
+{{DECISIONS_FROM_PROJECT_STATE}}
+[示例:]
+
+- 决策: 使用 ROADMAP.md 拆分 (理由: 恒定的上下文成本)
+- 决策: 小数阶段编号 (理由: 清晰的插入语义)
+
+**已解决的问题:**
+{{ISSUES_RESOLVED_DURING_MILESTONE}}
+[示例:]
+
+- 修复了 100+ 阶段时的上下文溢出
+- 解决了阶段插入的混淆
+
+**延后的问题:**
+{{ISSUES_DEFERRED_TO_LATER}}
+[示例:]
+
+- PROJECT-STATE.md 分层 (延后到决策 > 300 时)
+
+**产生的技术债务:**
+{{SHORTCUTS_NEEDING_FUTURE_WORK}}
+[示例:]
+
+- 部分工作流仍有硬编码路径 (在阶段 5 修复)
+
+---
+
+_当前项目状态请参见 .planning/ROADMAP.md_
+
+---
+
+## 使用指南
+
+<guidelines>
+**何时创建里程碑归档:**
+- 完成里程碑中的所有阶段后 (v1.0, v1.1, v2.0 等)
+- 由 complete-milestone 工作流触发
+- 在规划下一个里程碑工作之前
+
+**如何填写模板:**
+
+- 用实际值替换 {{PLACEHOLDERS}}
+- 从 ROADMAP.md 提取阶段详情
+- 用 (INSERTED) 标记记录小数阶段
+- 包含来自 PROJECT-STATE.md 或 SUMMARY 文件的关键决策
+- 列出已解决 vs 延后的问题
+- 记录技术债务供未来参考
+
+**归档位置:**
+
+- 保存到 `.planning/milestones/v{VERSION}-{NAME}.md`
+- 示例: `.planning/milestones/v1.0-mvp.md`
+
+**归档后:**
+
+- 更新 ROADMAP.md 将已完成的里程碑折叠到 `<details>` 标签中
+- 更新 PROJECT.md 为棕地格式，包含当前状态部分
+- 在下一个里程碑中继续阶段编号 (永远不要从 01 重新开始)
+</guidelines>

package/.opencode/templates/milestone.md

@@ -0,0 +1,115 @@
+# 里程碑条目模板
+
+完成里程碑时将此条目添加到 `.planning/MILESTONES.md`:
+
+```markdown
+## v[X.Y] [名称] (发布: YYYY-MM-DD)
+
+**交付:** [一句话描述发布了什么]
+
+**完成阶段:** [X-Y] (共 [Z] 个计划)
+
+**关键成就:**
+- [主要成就 1]
+- [主要成就 2]
+- [主要成就 3]
+- [主要成就 4]
+
+**统计:**
+- [X] 个文件创建/修改
+- [Y] 行代码 (主要语言)
+- [Z] 个阶段, [N] 个计划, [M] 个任务
+- [D] 天从开始到发布 (或里程碑到里程碑)
+
+**Git 范围:** `feat(XX-XX)` → `feat(YY-YY)`
+
+**下一步:** [下一个里程碑目标的简要描述，或 "项目完成"]
+
+---
+```
+
+<structure>
+如果 MILESTONES.md 不存在，创建时添加头部:
+
+```markdown
+# 项目里程碑: [项目名称]
+
+[按时间倒序排列，最新的在前]
+```
+</structure>
+
+<guidelines>
+**何时创建里程碑:**
+- 初始 v1.0 MVP 发布
+- 主要版本发布 (v2.0, v3.0)
+- 重要功能里程碑 (v1.1, v1.2)
+- 归档规划前 (记录发布了什么)
+
+**不要为以下创建里程碑:**
+- 单个阶段完成 (正常工作流)
+- 进行中的工作 (等到发布)
+- 不构成发布的小 bug 修复
+
+**要包含的统计:**
+- 修改文件数: `git diff --stat feat(XX-XX)..feat(YY-YY) | tail -1`
+- 代码行数: `find . -name "*.swift" -o -name "*.ts" | xargs wc -l` (或相关扩展名)
+- 阶段/计划/任务数量来自 ROADMAP
+- 时间线从第一个阶段提交到最后一个阶段提交
+
+**Git 范围格式:**
+- 里程碑的第一个提交 → 最后一个提交
+- 示例: `feat(01-01)` → `feat(04-01)` 对应阶段 1-4
+</guidelines>
+
+<example>
+```markdown
+# 项目里程碑: WeatherBar
+
+## v1.1 安全与打磨 (发布: 2025-12-10)
+
+**交付:** 安全加固，集成 Keychain 和全面的错误处理
+
+**完成阶段:** 5-6 (共 3 个计划)
+
+**关键成就:**
+- 将 API 密钥存储从明文迁移到 macOS Keychain
+- 实现网络故障的全面错误处理
+- 添加 Sentry 崩溃报告集成
+- 修复自动刷新定时器的内存泄漏
+
+**统计:**
+- 23 个文件修改
+- 650 行 Swift 代码新增
+- 2 个阶段, 3 个计划, 12 个任务
+- 从 v1.0 到 v1.1 共 8 天
+
+**Git 范围:** `feat(05-01)` → `feat(06-02)`
+
+**下一步:** v2.0 SwiftUI 重新设计，支持小组件
+
+---
+
+## v1.0 MVP (发布: 2025-11-25)
+
+**交付:** 菜单栏天气应用，显示当前天气和 3 天预报
+
+**完成阶段:** 1-4 (共 7 个计划)
+
+**关键成就:**
+- 带弹出 UI 的菜单栏应用 (AppKit)
+- OpenWeather API 集成及自动刷新
+- 当前天气显示含天气图标
+- 3 天预报列表含最高/最低温度
+- 代码签名和公证，可分发
+
+**统计:**
+- 47 个文件创建
+- 2,450 行 Swift 代码
+- 4 个阶段, 7 个计划, 28 个任务
+- 从开始到发布共 12 天
+
+**Git 范围:** `feat(01-01)` → `feat(04-01)`
+
+**下一步:** v1.1 安全审计和加固
+```
+</example>