specops 0.2.5 → 0.3.2

package/.opencode/templates/phase-prompt.md

@@ -0,0 +1,333 @@
+# 阶段提示模板
+
+> **注意:** 规划方法论在 `agents/specops-planner.md` 中。
+> 此模板定义代理生成的 PLAN.md 输出格式。
+
+`.planning/phases/XX-name/{phase}-{plan}-PLAN.md` 的模板，为并行执行优化的可执行阶段计划。
+
+**命名:** 使用 `{phase}-{plan}-PLAN.md` 格式 (如 `01-02-PLAN.md` 表示阶段 1, 计划 2)
+
+---
+
+## 文件模板
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: execute
+wave: N                     # 执行波次 (1, 2, 3...)。规划时预计算。
+depends_on: []              # 此计划依赖的计划 ID (如 ["01-01"])。
+files_modified: []          # 此计划修改的文件。
+autonomous: true            # 如果计划有需要用户交互的检查点则为 false
+requirements: []            # 必填 — 此计划对应的 ROADMAP 需求 ID。不能为空。
+user_setup: []              # Claude 无法自动化的人工设置 (见下文)
+
+# 目标反推验证 (规划时推导，执行后验证)
+must_haves:
+  truths: []                # 目标达成必须为真的可观测行为
+  artifacts: []             # 必须存在且有真实实现的文件
+  key_links: []             # 产物间的关键连接
+---
+
+<objective>
+[此计划完成什么]
+
+目的: [为什么这对项目重要]
+输出: [将创建什么产物]
+</objective>
+
+<execution_context>
+@.opencode/workflows/execute-plan.md
+@.opencode/templates/summary.md
+[如果计划包含检查点任务 (type="checkpoint:*")，添加:]
+@.opencode/references/checkpoints.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# 仅在确实需要时引用前置计划的 SUMMARY:
+# - 此计划使用前置计划的类型/导出
+# - 前置计划做了影响此计划的决策
+# 不要条件反射式地链接: 计划 02 引用 01, 计划 03 引用 02...
+
+[相关源文件:]
+@src/path/to/relevant.ts
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>任务 1: [面向操作的名称]</name>
+  <files>path/to/file.ext, another/file.ext</files>
+  <action>[具体实现 — 做什么、怎么做、避免什么以及为什么]</action>
+  <verify>[证明它工作的命令或检查]</verify>
+  <done>[可衡量的验收标准]</done>
+</task>
+
+<task type="auto">
+  <name>任务 2: [面向操作的名称]</name>
+  <files>path/to/file.ext</files>
+  <action>[具体实现]</action>
+  <verify>[命令或检查]</verify>
+  <done>[验收标准]</done>
+</task>
+
+<!-- 检查点任务示例和模式，参见 @.opencode/references/checkpoints.md -->
+<!-- 关键规则: Claude 在 human-verify 检查点之前启动开发服务器。用户只需访问 URL。 -->
+
+<task type="checkpoint:decision" gate="blocking">
+  <decision>[需要决定什么]</decision>
+  <context>[为什么这个决策重要]</context>
+  <options>
+    <option id="option-a"><name>[名称]</name><pros>[优点]</pros><cons>[权衡]</cons></option>
+    <option id="option-b"><name>[名称]</name><pros>[优点]</pros><cons>[权衡]</cons></option>
+  </options>
+  <resume-signal>选择: option-a 或 option-b</resume-signal>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>[Claude 构建了什么] - 服务运行在 [URL]</what-built>
+  <how-to-verify>访问 [URL] 并验证: [仅视觉检查，不要 CLI 命令]</how-to-verify>
+  <resume-signal>输入 "approved" 或描述问题</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+声明计划完成前:
+- [ ] [具体测试命令]
+- [ ] [构建/类型检查通过]
+- [ ] [行为验证]
+</verification>
+
+<success_criteria>
+
+- 所有任务完成
+- 所有验证检查通过
+- 未引入错误或警告
+- [计划特定标准]
+</success_criteria>
+
+<output>
+完成后，创建 `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+</output>
+```
+
+---
+
+## Frontmatter 字段
+
+| 字段 | 必填 | 用途 |
+|------|------|------|
+| `phase` | 是 | 阶段标识 (如 `01-foundation`) |
+| `plan` | 是 | 阶段内的计划编号 (如 `01`, `02`) |
+| `type` | 是 | 标准计划始终为 `execute`，TDD 计划为 `tdd` |
+| `wave` | 是 | 执行波次编号 (1, 2, 3...)。规划时预计算。 |
+| `depends_on` | 是 | 此计划依赖的计划 ID 数组。 |
+| `files_modified` | 是 | 此计划涉及的文件。 |
+| `autonomous` | 是 | 无检查点为 `true`，有检查点为 `false` |
+| `requirements` | 是 | **必须**列出 ROADMAP 中的需求 ID。每个路线图需求必须出现在至少一个计划中。 |
+| `user_setup` | 否 | 人工设置项数组 (外部服务) |
+| `must_haves` | 是 | 目标反推验证标准 (见下文) |
+
+**波次是预计算的:** 波次编号在 `/specops:plan-phase` 期间分配。Execute-phase 直接从 frontmatter 读取 `wave` 并按波次编号分组计划。无需运行时依赖分析。
+
+**Must-haves 支持验证:** `must_haves` 字段将目标反推需求从规划传递到执行。所有计划完成后，execute-phase 生成验证子代理，根据实际代码库检查这些标准。
+
+---
+
+## 并行 vs 顺序
+
+<parallel_examples>
+
+**波次 1 候选 (并行):**
+
+```yaml
+# 计划 01 - 用户功能
+wave: 1
+depends_on: []
+files_modified: [src/models/user.ts, src/api/users.ts]
+autonomous: true
+
+# 计划 02 - 产品功能 (与计划 01 无重叠)
+wave: 1
+depends_on: []
+files_modified: [src/models/product.ts, src/api/products.ts]
+autonomous: true
+
+# 计划 03 - 订单功能 (无重叠)
+wave: 1
+depends_on: []
+files_modified: [src/models/order.ts, src/api/orders.ts]
+autonomous: true
+```
+
+三个都在波次 1 并行运行，无依赖，无文件冲突。
+
+**顺序 (真正的依赖):**
+
+```yaml
+# 计划 01 - 认证基础
+wave: 1
+depends_on: []
+files_modified: [src/lib/auth.ts, src/middleware/auth.ts]
+autonomous: true
+
+# 计划 02 - 受保护功能 (需要认证)
+wave: 2
+depends_on: ["01"]
+files_modified: [src/features/dashboard.ts]
+autonomous: true
+```
+
+计划 02 在波次 2 等待波次 1 的计划 01 完成，因为真正依赖认证类型/中间件。
+
+**检查点计划:**
+
+```yaml
+# 计划 03 - 带验证的 UI
+wave: 3
+depends_on: ["01", "02"]
+files_modified: [src/components/Dashboard.tsx]
+autonomous: false  # 有 checkpoint:human-verify
+```
+
+波次 3 在波次 1 和 2 之后运行。在检查点暂停，编排器呈现给用户，用户批准后恢复。
+
+</parallel_examples>
+
+---
+
+## 范围指导
+
+**计划大小:**
+
+- 每个计划 2-3 个任务
+- 最多 ~50% 上下文使用量
+- 复杂阶段: 多个聚焦的计划，而非一个大计划
+
+**何时拆分:**
+
+- 不同子系统 (认证 vs API vs UI)
+- >3 个任务
+- 上下文溢出风险
+- TDD 候选，单独计划
+
+**优先垂直切片:**
+
+```
+推荐: 计划 01 = 用户 (模型 + API + UI)
+      计划 02 = 产品 (模型 + API + UI)
+
+避免: 计划 01 = 所有模型
+      计划 02 = 所有 API
+      计划 03 = 所有 UI
+```
+
+---
+
+## 任务类型
+
+| 类型 | 用途 | 自主性 |
+|------|------|--------|
+| `auto` | Claude 能独立完成的一切 | 完全自主 |
+| `checkpoint:human-verify` | 视觉/功能验证 | 暂停，返回编排器 |
+| `checkpoint:decision` | 实现选择 | 暂停，返回编排器 |
+| `checkpoint:human-action` | 真正不可避免的手动步骤 (罕见) | 暂停，返回编排器 |
+
+---
+
+## 指南
+
+- 始终使用 XML 结构便于 Claude 解析
+- 每个计划都包含 `wave`, `depends_on`, `files_modified`, `autonomous`
+- 优先垂直切片而非水平分层
+- 仅在确实需要时引用前置 SUMMARY
+- 将检查点与相关自动任务放在同一计划中
+- 每个计划 2-3 个任务，最多 ~50% 上下文
+
+---
+
+## 用户设置 (外部服务)
+
+当计划引入需要人工配置的外部服务时，在 frontmatter 中声明:
+
+```yaml
+user_setup:
+  - service: stripe
+    why: "支付处理需要 API 密钥"
+    env_vars:
+      - name: STRIPE_SECRET_KEY
+        source: "Stripe 控制台 → Developers → API keys → Secret key"
+      - name: STRIPE_WEBHOOK_SECRET
+        source: "Stripe 控制台 → Developers → Webhooks → Signing secret"
+    dashboard_config:
+      - task: "创建 webhook 端点"
+        location: "Stripe 控制台 → Developers → Webhooks → Add endpoint"
+        details: "URL: https://[your-domain]/api/webhooks/stripe"
+    local_dev:
+      - "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+```
+
+**自动化优先原则:** `user_setup` 只包含 Claude 确实无法完成的操作:
+- 账户创建 (需要人工注册)
+- 密钥获取 (需要控制台访问)
+- 控制台配置 (需要人工在浏览器中操作)
+
+**不包含:** 包安装、代码修改、文件创建、Claude 能运行的 CLI 命令。
+
+**结果:** Execute-plan 生成 `{phase}-USER-SETUP.md` 作为用户的检查清单。
+
+参见 `.opencode/templates/user-setup.md` 获取完整结构和示例
+
+---
+
+## Must-Haves (目标反推验证)
+
+`must_haves` 字段定义阶段目标达成必须为真的条件。规划时推导，执行后验证。
+
+**结构:**
+
+```yaml
+must_haves:
+  truths:
+    - "用户可以看到已有消息"
+    - "用户可以发送消息"
+    - "消息在刷新后持久化"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "消息列表渲染"
+      min_lines: 30
+    - path: "src/app/api/chat/route.ts"
+      provides: "消息 CRUD 操作"
+      exports: ["GET", "POST"]
+    - path: "prisma/schema.prisma"
+      provides: "Message 模型"
+      contains: "model Message"
+  key_links:
+    - from: "src/components/Chat.tsx"
+      to: "/api/chat"
+      via: "useEffect 中的 fetch"
+      pattern: "fetch.*api/chat"
+    - from: "src/app/api/chat/route.ts"
+      to: "prisma.message"
+      via: "数据库查询"
+      pattern: "prisma\\.message\\.(find|create)"
+```
+
+**为什么重要:**
+
+任务完成 ≠ 目标达成。一个 "创建聊天组件" 的任务可以通过创建占位内容来完成。`must_haves` 字段捕获必须实际工作的内容，使验证能在缺口累积之前发现它们。
+
+**验证流程:**
+
+1. Plan-phase 从阶段目标推导 must_haves (目标反推)
+2. Must_haves 写入 PLAN.md frontmatter
+3. Execute-phase 运行所有计划
+4. 验证子代理根据代码库检查 must_haves
+5. 发现缺口 → 创建修复计划 → 执行 → 重新验证
+6. 所有 must_haves 通过 → 阶段完成

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

@@ -0,0 +1,117 @@
+# 规划子代理提示模板
+
+用于生成 specops-planner 代理的模板。代理包含所有规划专业知识，此模板仅提供规划上下文。
+
+---
+
+## 模板
+
+```markdown
+<planning_context>
+
+**阶段:** {phase_number}
+**模式:** {standard | gap_closure}
+
+**项目状态:**
+@.planning/STATE.md
+
+**路线图:**
+@.planning/ROADMAP.md
+
+**需求 (如存在):**
+@.planning/REQUIREMENTS.md
+
+**阶段上下文 (如存在):**
+@.planning/phases/{phase_dir}/{phase_num}-CONTEXT.md
+
+**研究 (如存在):**
+@.planning/phases/{phase_dir}/{phase_num}-RESEARCH.md
+
+**缺口修复 (如 --gaps 模式):**
+@.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+@.planning/phases/{phase_dir}/{phase_num}-UAT.md
+
+</planning_context>
+
+<downstream_consumer>
+输出由 /specops:execute-phase 消费
+计划必须是可执行的提示，包含:
+- Frontmatter (wave, depends_on, files_modified, autonomous)
+- XML 格式的任务
+- 验证标准
+- 用于目标反推验证的 must_haves
+</downstream_consumer>
+
+<quality_gate>
+返回 PLANNING COMPLETE 之前:
+- [ ] PLAN.md 文件已在阶段目录中创建
+- [ ] 每个计划有有效的 frontmatter
+- [ ] 任务具体且可操作
+- [ ] 依赖关系正确识别
+- [ ] 已分配波次用于并行执行
+- [ ] must_haves 从阶段目标推导
+</quality_gate>
+```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 | 示例 |
+|--------|------|------|
+| `{phase_number}` | 来自路线图/参数 | `5` 或 `2.1` |
+| `{phase_dir}` | 阶段目录名 | `05-user-profiles` |
+| `{phase}` | 阶段前缀 | `05` |
+| `{standard \| gap_closure}` | 模式标志 | `standard` |
+
+---
+
+## 用法
+
+**从 /specops:plan-phase (标准模式):**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="specops-planner",
+  description="规划阶段 {phase}"
+)
+```
+
+**从 /specops:plan-phase --gaps (缺口修复模式):**
+```python
+Task(
+  prompt=filled_template,  # mode: gap_closure
+  subagent_type="specops-planner",
+  description="规划阶段 {phase} 的缺口修复"
+)
+```
+
+---
+
+## 续接
+
+对于检查点，用以下内容生成新代理:
+
+```markdown
+<objective>
+继续阶段 {phase_number}: {phase_name} 的规划
+</objective>
+
+<prior_state>
+阶段目录: @.planning/phases/{phase_dir}/
+已有计划: @.planning/phases/{phase_dir}/*-PLAN.md
+</prior_state>
+
+<checkpoint_response>
+**类型:** {checkpoint_type}
+**响应:** {user_response}
+</checkpoint_response>
+
+<mode>
+继续: {standard | gap_closure}
+</mode>
+```
+
+---
+
+**注意:** 规划方法论、任务分解、依赖分析、波次分配、TDD 检测和目标反推推导都内置在 specops-planner 代理中。此模板仅传递上下文。

package/.opencode/templates/project.md

@@ -0,0 +1,184 @@
+# PROJECT.md 模板
+
+`.planning/PROJECT.md` 的模板，项目的活上下文文档。
+
+<template>
+
+```markdown
+# [项目名称]
+
+## 这是什么
+
+[当前准确的描述 — 2-3 句话。这个产品做什么，面向谁？
+使用用户的语言和表述方式。当现实偏离此描述时更新。]
+
+## 核心价值
+
+[最重要的一件事。如果其他一切都失败了，这个必须能用。
+一句话，在需要权衡时驱动优先级决策。]
+
+## 需求
+
+### 已验证
+
+<!-- 已发布并确认有价值的。 -->
+
+(暂无 — 发布后验证)
+
+### 活跃
+
+<!-- 当前范围。正在朝这些目标构建。 -->
+
+- [ ] [需求 1]
+- [ ] [需求 2]
+- [ ] [需求 3]
+
+### 超出范围
+
+<!-- 明确的边界。包含理由以防止重新添加。 -->
+
+- [排除 1] — [原因]
+- [排除 2] — [原因]
+
+## 背景
+
+[影响实现的背景信息:
+- 技术环境或生态系统
+- 相关的前期工作或经验
+- 用户研究或反馈主题
+- 需要解决的已知问题]
+
+## 约束
+
+- **[类型]**: [什么] — [为什么]
+- **[类型]**: [什么] — [为什么]
+
+常见类型: 技术栈, 时间线, 预算, 依赖, 兼容性, 性能, 安全
+
+## 关键决策
+
+<!-- 约束未来工作的决策。在项目生命周期中持续添加。 -->
+
+| 决策 | 理由 | 结果 |
+|------|------|------|
+| [选择] | [为什么] | [✓ 正确 / ⚠️ 需重新考虑 / — 待定] |
+
+---
+*最后更新: [日期] 在 [触发事件] 之后*
+```
+
+</template>
+
+<guidelines>
+
+**这是什么:**
+- 产品的当前准确描述
+- 2-3 句话说明它做什么、面向谁
+- 使用用户的语言和表述
+- 产品演进超出此描述时更新
+
+**核心价值:**
+- 最重要的一件事
+- 其他一切可以失败；这个不行
+- 需要权衡时驱动优先级
+- 很少变化；如果变了，说明是重大转向
+
+**需求 — 已验证:**
+- 已发布并证明有价值的需求
+- 格式: `- ✓ [需求] — [版本/阶段]`
+- 这些是锁定的，修改需要明确讨论
+
+**需求 — 活跃:**
+- 当前正在构建的范围
+- 这些是假设，直到发布并验证
+- 发布后移到已验证，失效后移到超出范围
+
+**需求 — 超出范围:**
+- 明确的边界，说明我们不构建什么
+- 始终包含理由 (防止以后重新添加)
+- 包括: 考虑后拒绝的、延后到未来的、明确排除的
+
+**背景:**
+- 影响实现决策的背景信息
+- 技术环境、前期工作、用户反馈
+- 需要解决的已知问题或技术债务
+- 新上下文出现时更新
+
+**约束:**
+- 实现选择的硬性限制
+- 技术栈、时间线、预算、兼容性、依赖
+- 包含 "为什么" — 没有理由的约束会被质疑
+
+**关键决策:**
+- 影响未来工作的重要选择
+- 在项目过程中做出决策时添加
+- 已知结果时追踪:
+  - ✓ 正确 — 决策被证明正确
+  - ⚠️ 需重新考虑 — 决策可能需要重新评估
+  - — 待定 — 还太早无法评估
+
+**最后更新:**
+- 始终记录何时以及为什么更新了文档
+- 格式: `在阶段 2 之后` 或 `在 v1.0 里程碑之后`
+- 触发审查内容是否仍然准确
+
+</guidelines>
+
+<evolution>
+
+PROJECT.md 在项目生命周期中持续演进。
+
+**每次阶段转换后:**
+1. 需求失效了？→ 移到超出范围并附原因
+2. 需求验证了？→ 移到已验证并附阶段引用
+3. 出现新需求？→ 添加到活跃
+4. 需要记录决策？→ 添加到关键决策
+5. "这是什么" 还准确吗？→ 如有偏差则更新
+
+**每个里程碑后:**
+1. 全面审查所有部分
+2. 核心价值检查 — 还是正确的优先级吗？
+3. 审计超出范围 — 理由还成立吗？
+4. 用当前状态更新背景 (用户、反馈、指标)
+
+</evolution>
+
+<brownfield>
+
+对于已有代码库:
+
+1. **先映射代码库** 通过 `/specops:map-codebase`
+
+2. **从现有代码推断已验证需求:**
+   - 代码库实际做了什么？
+   - 建立了什么模式？
+   - 什么明显在工作且被依赖？
+
+3. **从用户收集活跃需求:**
+   - 展示推断的当前状态
+   - 询问他们接下来想构建什么
+
+4. **初始化:**
+   - 已验证 = 从现有代码推断
+   - 活跃 = 用户本次工作的目标
+   - 超出范围 = 用户指定的边界
+   - 背景 = 包含当前代码库状态
+
+</brownfield>
+
+<state_reference>
+
+STATE.md 引用 PROJECT.md:
+
+```markdown
+## 项目引用
+
+参见: .planning/PROJECT.md (更新于 [日期])
+
+**核心价值:** [核心价值部分的一句话]
+**当前焦点:** [当前阶段名称]
+```
+
+这确保 Claude 读取当前的 PROJECT.md 上下文。
+
+</state_reference>