specops 0.2.4 → 0.3.0

package/.opencode/workflows/transition.md

@@ -0,0 +1,544 @@
+<required_reading>
+
+**立即阅读以下文件：**
+
+1. `.planning/STATE.md`
+2. `.planning/PROJECT.md`
+3. `.planning/ROADMAP.md`
+4. 当前阶段的计划文件（`*-PLAN.md`）
+5. 当前阶段的摘要文件（`*-SUMMARY.md`）
+
+</required_reading>
+
+<purpose>
+
+标记当前阶段完成并推进到下一阶段。这是进度跟踪和 PROJECT.md 演进自然发生的节点。
+
+"规划下一阶段" = "当前阶段已完成"
+
+</purpose>
+
+<process>
+
+<step name="load_project_state" priority="first">
+
+在过渡之前，读取项目状态：
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+cat .planning/PROJECT.md 2>/dev/null
+```
+
+解析当前位置以验证我们正在过渡正确的阶段。
+记录过渡后可能需要更新的累积上下文。
+
+</step>
+
+<step name="verify_completion">
+
+检查当前阶段是否所有计划摘要都已完成：
+
+```bash
+ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort
+ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
+```
+
+**验证逻辑：**
+
+- 统计 PLAN 文件数量
+- 统计 SUMMARY 文件数量
+- 如果数量匹配：所有计划已完成
+- 如果数量不匹配：未完成
+
+<config-check>
+
+```bash
+cat .planning/config.json 2>/dev/null
+```
+
+</config-check>
+
+**如果所有计划已完成：**
+
+<if mode="yolo">
+
+```
+⚡ 自动批准：过渡 Phase [X] → Phase [X+1]
+Phase [X] 完成——所有 [Y] 个计划已完成。
+
+正在标记完成并推进...
+```
+
+直接进入 cleanup_handoff 步骤。
+
+</if>
+
+<if mode="interactive" OR="custom with gates.confirm_transition true">
+
+询问："Phase [X] 完成——所有 [Y] 个计划已完成。准备好标记完成并转到 Phase [X+1] 了吗？"
+
+等待确认后再继续。
+
+</if>
+
+**如果计划未完成：**
+
+**安全护栏：always_confirm_destructive 在此适用。**
+跳过未完成的计划是破坏性操作——无论模式如何都必须提示。
+
+展示：
+
+```
+Phase [X] 有未完成的计划：
+- {phase}-01-SUMMARY.md ✓ 已完成
+- {phase}-02-SUMMARY.md ✗ 缺失
+- {phase}-03-SUMMARY.md ✗ 缺失
+
+⚠️ 安全护栏：跳过计划需要确认（破坏性操作）
+
+选项：
+1. 继续当前阶段（执行剩余计划）
+2. 仍然标记完成（跳过剩余计划）
+3. 查看剩余内容
+```
+
+等待用户决定。
+
+</step>
+
+<step name="cleanup_handoff">
+
+检查残留的交接文件：
+
+```bash
+ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null
+```
+
+如果找到，删除它们——阶段已完成，交接文件已过时。
+
+</step>
+
+<step name="update_roadmap_and_state">
+
+**将 ROADMAP.md 和 STATE.md 更新委托给 specops-tools：**
+
+```bash
+TRANSITION=$(node .opencode/bin/specops-tools.cjs phase complete "${current_phase}")
+```
+
+CLI 处理：
+- 将阶段复选框标记为 `[x]` 完成并附上今天的日期
+- 将计划数量更新为最终值（例如"3/3 plans complete"）
+- 更新进度表（Status → Complete，添加日期）
+- 将 STATE.md 推进到下一阶段（Current Phase、Status → Ready to plan、Current Plan → Not started）
+- 检测这是否是里程碑中的最后一个阶段
+
+从结果中提取：`completed_phase`、`plans_executed`、`next_phase`、`next_phase_name`、`is_last_phase`。
+
+</step>
+
+<step name="archive_prompts">
+
+如果为该阶段生成了提示，它们保留在原位。
+`completed/` 子文件夹模式由 create-meta-prompts 处理归档。
+
+</step>
+
+<step name="evolve_project">
+
+演进 PROJECT.md 以反映已完成阶段的经验教训。
+
+**阅读阶段摘要：**
+
+```bash
+cat .planning/phases/XX-current/*-SUMMARY.md
+```
+
+**评估需求变更：**
+
+1. **需求已验证？**
+   - 此阶段是否交付了任何 Active 需求？
+   - 移至 Validated 并附上阶段引用：`- ✓ [需求] — Phase X`
+
+2. **需求已失效？**
+   - 是否发现任何 Active 需求不必要或错误？
+   - 移至 Out of Scope 并附上原因：`- [需求] — [失效原因]`
+
+3. **新需求出现？**
+   - 构建过程中是否发现了新需求？
+   - 添加到 Active：`- [ ] [新需求]`
+
+4. **需要记录的决策？**
+   - 从 SUMMARY.md 文件中提取决策
+   - 添加到 Key Decisions 表格，如已知则附上结果
+
+5. **"这是什么"仍然准确？**
+   - 如果产品发生了有意义的变化，更新描述
+   - 保持当前和准确
+
+**更新 PROJECT.md：**
+
+直接内联编辑。更新"Last updated"页脚：
+
+```markdown
+---
+*Last updated: [date] after Phase [X]*
+```
+
+**演进示例：**
+
+之前：
+
+```markdown
+### Active
+
+- [ ] JWT authentication
+- [ ] Real-time sync < 500ms
+- [ ] Offline mode
+
+### Out of Scope
+
+- OAuth2 — complexity not needed for v1
+```
+
+之后（Phase 2 交付了 JWT auth，发现需要速率限制）：
+
+```markdown
+### Validated
+
+- ✓ JWT authentication — Phase 2
+
+### Active
+
+- [ ] Real-time sync < 500ms
+- [ ] Offline mode
+- [ ] Rate limiting on sync endpoint
+
+### Out of Scope
+
+- OAuth2 — complexity not needed for v1
+```
+
+**步骤完成条件：**
+
+- [ ] 已审查阶段摘要获取经验教训
+- [ ] 已验证的需求从 Active 移出
+- [ ] 已失效的需求移至 Out of Scope 并附原因
+- [ ] 新出现的需求添加到 Active
+- [ ] 新决策已记录并附理由
+- [ ] 如产品发生变化则更新"这是什么"
+- [ ] "Last updated"页脚反映此次过渡
+
+</step>
+
+<step name="update_current_position_after_transition">
+
+**注意：** 基本位置更新（Current Phase、Status、Current Plan、Last Activity）已在 update_roadmap_and_state 步骤中由 `specops-tools phase complete` 处理。
+
+通过读取 STATE.md 验证更新是否正确。如果进度条需要更新，使用：
+
+```bash
+PROGRESS=$(node .opencode/bin/specops-tools.cjs progress bar --raw)
+```
+
+用结果更新 STATE.md 中的进度条行。
+
+**步骤完成条件：**
+
+- [ ] 阶段编号已递增到下一阶段（由 phase complete 完成）
+- [ ] 计划状态重置为"Not started"（由 phase complete 完成）
+- [ ] 状态显示"Ready to plan"（由 phase complete 完成）
+- [ ] 进度条反映已完成计划总数
+
+</step>
+
+<step name="update_project_reference">
+
+更新 STATE.md 中的 Project Reference 部分。
+
+```markdown
+## Project Reference
+
+See: .planning/PROJECT.md (updated [today])
+
+**Core value:** [PROJECT.md 中的当前核心价值]
+**Current focus:** [下一阶段名称]
+```
+
+更新日期和当前焦点以反映过渡。
+
+</step>
+
+<step name="review_accumulated_context">
+
+审查并更新 STATE.md 中的 Accumulated Context 部分。
+
+**决策：**
+
+- 记录此阶段的近期决策（最多 3-5 个）
+- 完整日志在 PROJECT.md 的 Key Decisions 表格中
+
+**阻塞/关注点：**
+
+- 审查已完成阶段的阻塞项
+- 如果在此阶段已解决：从列表中移除
+- 如果对未来仍相关：保留并加上"Phase X"前缀
+- 添加已完成阶段摘要中的任何新关注点
+
+**示例：**
+
+之前：
+
+```markdown
+### Blockers/Concerns
+
+- ⚠️ [Phase 1] Database schema not indexed for common queries
+- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
+```
+
+之后（如果数据库索引在 Phase 2 中已解决）：
+
+```markdown
+### Blockers/Concerns
+
+- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
+```
+
+**步骤完成条件：**
+
+- [ ] 近期决策已记录（完整日志在 PROJECT.md 中）
+- [ ] 已解决的阻塞项从列表中移除
+- [ ] 未解决的阻塞项保留并附阶段前缀
+- [ ] 已完成阶段的新关注点已添加
+
+</step>
+
+<step name="update_session_continuity_after_transition">
+
+更新 STATE.md 中的 Session Continuity 部分以反映过渡完成。
+
+**格式：**
+
+```markdown
+Last session: [today]
+Stopped at: Phase [X] complete, ready to plan Phase [X+1]
+Resume file: None
+```
+
+**步骤完成条件：**
+
+- [ ] 最后会话时间戳已更新为当前日期和时间
+- [ ] Stopped at 描述了阶段完成和下一阶段
+- [ ] Resume file 确认为 None（过渡不使用恢复文件）
+
+</step>
+
+<step name="offer_next_phase">
+
+**必须：在展示后续步骤之前验证里程碑状态。**
+
+**使用 `specops-tools phase complete` 的过渡结果：**
+
+`is_last_phase` 字段直接告诉你：
+- `is_last_phase: false` → 还有更多阶段 → 转到**路线 A**
+- `is_last_phase: true` → 里程碑完成 → 转到**路线 B**
+
+`next_phase` 和 `next_phase_name` 字段提供下一阶段的详情。
+
+如果需要额外上下文，使用：
+```bash
+ROADMAP=$(node .opencode/bin/specops-tools.cjs roadmap analyze)
+```
+
+返回所有阶段及其目标、磁盘状态和完成信息。
+
+---
+
+**路线 A：里程碑中还有更多阶段**
+
+读取 ROADMAP.md 获取下一阶段的名称和目标。
+
+**检查下一阶段是否有 CONTEXT.md：**
+
+```bash
+ls .planning/phases/*[X+1]*/*-CONTEXT.md 2>/dev/null
+```
+
+**如果下一阶段存在：**
+
+<if mode="yolo">
+
+**如果 CONTEXT.md 存在：**
+
+```
+Phase [X] 已标记完成。
+
+下一步：Phase [X+1] — [名称]
+
+⚡ 自动继续：详细规划 Phase [X+1]
+```
+
+退出 skill 并调用 SlashCommand("/specops:plan-phase [X+1] --auto")
+
+**如果 CONTEXT.md 不存在：**
+
+```
+Phase [X] 已标记完成。
+
+下一步：Phase [X+1] — [名称]
+
+⚡ 自动继续：先讨论 Phase [X+1]
+```
+
+退出 skill 并调用 SlashCommand("/specops:discuss-phase [X+1] --auto")
+
+</if>
+
+<if mode="interactive" OR="custom with gates.confirm_transition true">
+
+**如果 CONTEXT.md 不存在：**
+
+```
+## ✓ Phase [X] 完成
+
+---
+
+## ▶ 下一步
+
+**Phase [X+1]: [名称]** — [ROADMAP.md 中的目标]
+
+`/specops:discuss-phase [X+1]` — 收集上下文并澄清方案
+
+<sub>`/clear` 先清理 → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:plan-phase [X+1]` — 跳过讨论，直接规划
+- `/specops:research-phase [X+1]` — 调查未知领域
+
+---
+```
+
+**如果 CONTEXT.md 存在：**
+
+```
+## ✓ Phase [X] 完成
+
+---
+
+## ▶ 下一步
+
+**Phase [X+1]: [名称]** — [ROADMAP.md 中的目标]
+<sub>✓ 上下文已收集，准备规划</sub>
+
+`/specops:plan-phase [X+1]`
+
+<sub>`/clear` 先清理 → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:discuss-phase [X+1]` — 重新审视上下文
+- `/specops:research-phase [X+1]` — 调查未知领域
+
+---
+```
+
+</if>
+
+---
+
+**路线 B：里程碑完成（所有阶段已完成）**
+
+**清除自动推进** — 里程碑边界是自然停止点：
+```bash
+node .opencode/bin/specops-tools.cjs config-set workflow.auto_advance false
+```
+
+<if mode="yolo">
+
+```
+Phase {X} 已标记完成。
+
+🎉 里程碑 {version} 100% 完成——所有 {N} 个阶段已完成！
+
+⚡ 自动继续：完成里程碑并归档
+```
+
+退出 skill 并调用 SlashCommand("/specops:complete-milestone {version}")
+
+</if>
+
+<if mode="interactive" OR="custom with gates.confirm_transition true">
+
+```
+## ✓ Phase {X}: {阶段名称} 完成
+
+🎉 里程碑 {version} 100% 完成——所有 {N} 个阶段已完成！
+
+---
+
+## ▶ 下一步
+
+**完成里程碑 {version}** — 归档并准备下一个
+
+`/specops:complete-milestone {version}`
+
+<sub>`/clear` 先清理 → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- 在归档前审查成果
+
+---
+```
+
+</if>
+
+</step>
+
+</process>
+
+<implicit_tracking>
+进度跟踪是隐式的：规划阶段 N 意味着阶段 1-(N-1) 已完成。不需要单独的进度步骤——向前推进就是进度。
+</implicit_tracking>
+
+<partial_completion>
+
+如果用户想继续但阶段未完全完成：
+
+```
+Phase [X] 有未完成的计划：
+- {phase}-02-PLAN.md（未执行）
+- {phase}-03-PLAN.md（未执行）
+
+选项：
+1. 仍然标记完成（计划不需要了）
+2. 将工作推迟到后续阶段
+3. 留下来完成当前阶段
+```
+
+尊重用户判断——他们知道工作是否重要。
+
+**如果标记完成但有未完成的计划：**
+
+- 更新 ROADMAP："2/3 plans complete"（不是"3/3"）
+- 在过渡消息中注明哪些计划被跳过
+
+</partial_completion>
+
+<success_criteria>
+
+过渡完成条件：
+
+- [ ] 当前阶段计划摘要已验证（全部存在或用户选择跳过）
+- [ ] 所有过时的交接文件已删除
+- [ ] ROADMAP.md 已更新完成状态和计划数量
+- [ ] PROJECT.md 已演进（需求、决策、描述如需要）
+- [ ] STATE.md 已更新（位置、项目引用、上下文、会话）
+- [ ] 进度表已更新
+- [ ] 用户知道后续步骤
+
+</success_criteria>