specops 0.2.4 → 0.3.0

package/.opencode/workflows/progress.md

@@ -0,0 +1,381 @@
+<purpose>
+检查项目进度，汇总近期工作和后续计划，然后智能路由到下一步操作——执行现有计划或创建下一个计划。在继续工作前提供态势感知。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="init_context">
+**加载进度上下文（仅路径）：**
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init progress)
+```
+
+从初始化 JSON 中提取：`project_exists`、`roadmap_exists`、`state_exists`、`phases`、`current_phase`、`next_phase`、`milestone_version`、`completed_count`、`phase_count`、`paused_at`、`state_path`、`roadmap_path`、`project_path`、`config_path`。
+
+如果 `project_exists` 为 false（没有 `.planning/` 目录）：
+
+```
+未找到规划结构。
+
+运行 /specops:new-project 开始新项目。
+```
+
+退出。
+
+如果缺少 STATE.md：建议 `/specops:new-project`。
+
+**如果缺少 ROADMAP.md 但 PROJECT.md 存在：**
+
+这意味着里程碑已完成并归档。转到**路由 F**（里程碑之间）。
+
+如果同时缺少 ROADMAP.md 和 PROJECT.md：建议 `/specops:new-project`。
+</step>
+
+<step name="load">
+**使用 specops-tools 的结构化提取：**
+
+不读取完整文件，而是使用针对性工具仅获取报告所需的数据：
+- `ROADMAP=$(node .opencode/bin/specops-tools.cjs roadmap analyze)`
+- `STATE=$(node .opencode/bin/specops-tools.cjs state-snapshot)`
+
+这最小化了编排器的上下文使用。
+</step>
+
+<step name="analyze_roadmap">
+**获取全面的路线图分析（替代手动解析）：**
+
+```bash
+ROADMAP=$(node .opencode/bin/specops-tools.cjs roadmap analyze)
+```
+
+返回结构化 JSON，包含：
+- 所有阶段及其磁盘状态（complete/partial/planned/empty/no_directory）
+- 每个阶段的目标和依赖
+- 每个阶段的计划和摘要数量
+- 汇总统计：总计划数、摘要数、进度百分比
+- 当前和下一阶段识别
+
+使用此结果替代手动读取/解析 ROADMAP.md。
+</step>
+
+<step name="recent">
+**收集近期工作上下文：**
+
+- 找到最近的 2-3 个 SUMMARY.md 文件
+- 使用 `summary-extract` 进行高效解析：
+  ```bash
+  node .opencode/bin/specops-tools.cjs summary-extract <path> --fields one_liner
+  ```
+- 这展示了"我们一直在做什么"
+</step>
+
+<step name="position">
+**从初始化上下文和路线图分析中解析当前位置：**
+
+- 使用 `$ROADMAP` 中的 `current_phase` 和 `next_phase`
+- 如果工作被暂停，记录 `paused_at`（来自 `$STATE`）
+- 统计待办事项：使用 `init todos` 或 `list-todos`
+- 检查活跃的调试会话：`ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
+</step>
+
+<step name="report">
+**从 specops-tools 生成进度条，然后展示丰富的状态报告：**
+
+```bash
+# 获取格式化的进度条
+PROGRESS_BAR=$(node .opencode/bin/specops-tools.cjs progress bar --raw)
+```
+
+展示：
+
+```
+# [项目名称]
+
+**进度：** {PROGRESS_BAR}
+**配置：** [quality/balanced/budget]
+
+## 近期工作
+- [阶段 X，计划 Y]：[完成了什么——来自 summary-extract 的一行]
+- [阶段 X，计划 Z]：[完成了什么——来自 summary-extract 的一行]
+
+## 当前位置
+阶段 [N] / [总数]：[阶段名称]
+计划 [M] / [阶段总数]：[状态]
+上下文：[✓ 如果有 has_context | - 如果没有]
+
+## 关键决策
+- [从 $STATE.decisions[] 提取]
+- [例如 jq -r '.decisions[].decision' from state-snapshot]
+
+## 阻塞/关注点
+- [从 $STATE.blockers[] 提取]
+- [例如 jq -r '.blockers[].text' from state-snapshot]
+
+## 待办事项
+- [数量] 个待处理 — /specops:check-todos 查看
+
+## 活跃调试会话
+- [数量] 个活跃 — /specops:debug 继续
+（仅在数量 > 0 时显示此部分）
+
+## 下一步
+[来自路线图分析的下一阶段/计划目标]
+```
+
+</step>
+
+<step name="route">
+**根据已验证的计数确定下一步操作。**
+
+**步骤 1：统计当前阶段的计划、摘要和问题**
+
+列出当前阶段目录中的文件：
+
+```bash
+ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
+ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
+ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l
+```
+
+声明："此阶段有 {X} 个计划，{Y} 个摘要。"
+
+**步骤 1.5：检查未处理的 UAT 缺口**
+
+检查状态为"diagnosed"的 UAT.md 文件（有需要修复的缺口）。
+
+```bash
+# 检查已诊断的带缺口的 UAT
+grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null
+```
+
+追踪：
+- `uat_with_gaps`：状态为"diagnosed"的 UAT.md 文件（缺口需要修复）
+
+**步骤 2：根据计数路由**
+
+| 条件 | 含义 | 操作 |
+|------|------|------|
+| uat_with_gaps > 0 | UAT 缺口需要修复计划 | 转到**路由 E** |
+| summaries < plans | 存在未执行的计划 | 转到**路由 A** |
+| summaries = plans 且 plans > 0 | 阶段完成 | 转到步骤 3 |
+| plans = 0 | 阶段尚未规划 | 转到**路由 B** |
+
+---
+
+**路由 A：存在未执行的计划**
+
+找到第一个没有对应 SUMMARY.md 的 PLAN.md。
+读取其 `<objective>` 部分。
+
+```
+---
+
+## ▶ 下一步
+
+**{phase}-{plan}：[计划名称]** — [来自 PLAN.md 的目标摘要]
+
+`/specops:execute-phase {phase}`
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+```
+
+---
+
+**路由 B：阶段需要规划**
+
+检查阶段目录中是否存在 `{phase_num}-CONTEXT.md`。
+
+**如果 CONTEXT.md 存在：**
+
+```
+---
+
+## ▶ 下一步
+
+**阶段 {N}：{名称}** — {来自 ROADMAP.md 的目标}
+<sub>✓ 上下文已收集，准备规划</sub>
+
+`/specops:plan-phase {阶段编号}`
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+```
+
+**如果 CONTEXT.md 不存在：**
+
+```
+---
+
+## ▶ 下一步
+
+**阶段 {N}：{名称}** — {来自 ROADMAP.md 的目标}
+
+`/specops:discuss-phase {phase}` — 收集上下文并明确方案
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:plan-phase {phase}` — 跳过讨论，直接规划
+- `/specops:list-phase-assumptions {phase}` — 查看 Claude 的假设
+
+---
+```
+
+---
+
+**路由 E：UAT 缺口需要修复计划**
+
+UAT.md 存在且有缺口（已诊断的问题）。用户需要规划修复。
+
+```
+---
+
+## ⚠ 发现 UAT 缺口
+
+**{phase_num}-UAT.md** 有 {N} 个缺口需要修复。
+
+`/specops:plan-phase {phase} --gaps`
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:execute-phase {phase}` — 执行阶段计划
+- `/specops:verify-work {phase}` — 运行更多 UAT 测试
+
+---
+```
+
+---
+
+**步骤 3：检查里程碑状态（仅在阶段完成时）**
+
+读取 ROADMAP.md 并识别：
+1. 当前阶段编号
+2. 当前里程碑部分中的所有阶段编号
+
+统计总阶段数并识别最高阶段编号。
+
+声明："当前阶段是 {X}。里程碑有 {N} 个阶段（最高：{Y}）。"
+
+**根据里程碑状态路由：**
+
+| 条件 | 含义 | 操作 |
+|------|------|------|
+| 当前阶段 < 最高阶段 | 还有更多阶段 | 转到**路由 C** |
+| 当前阶段 = 最高阶段 | 里程碑完成 | 转到**路由 D** |
+
+---
+
+**路由 C：阶段完成，还有更多阶段**
+
+读取 ROADMAP.md 获取下一阶段的名称和目标。
+
+```
+---
+
+## ✓ 阶段 {Z} 完成
+
+## ▶ 下一步
+
+**阶段 {Z+1}：{名称}** — {来自 ROADMAP.md 的目标}
+
+`/specops:discuss-phase {Z+1}` — 收集上下文并明确方案
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:plan-phase {Z+1}` — 跳过讨论，直接规划
+- `/specops:verify-work {Z}` — 继续前进行用户验收测试
+
+---
+```
+
+---
+
+**路由 D：里程碑完成**
+
+```
+---
+
+## 🎉 里程碑完成
+
+所有 {N} 个阶段已完成！
+
+## ▶ 下一步
+
+**完成里程碑** — 归档并准备下一个
+
+`/specops:complete-milestone`
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:verify-work` — 完成里程碑前进行用户验收测试
+
+---
+```
+
+---
+
+**路由 F：里程碑之间（ROADMAP.md 缺失，PROJECT.md 存在）**
+
+里程碑已完成并归档。准备开始下一个里程碑周期。
+
+读取 MILESTONES.md 找到最后完成的里程碑版本。
+
+```
+---
+
+## ✓ 里程碑 v{X.Y} 完成
+
+准备规划下一个里程碑。
+
+## ▶ 下一步
+
+**开始下一个里程碑** — 提问 → 研究 → 需求 → 路线图
+
+`/specops:new-milestone`
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+```
+
+</step>
+
+<step name="edge_cases">
+**处理边界情况：**
+
+- 阶段完成但下一阶段未规划 → 提供 `/specops:plan-phase [next]`
+- 所有工作完成 → 提供里程碑完成
+- 存在阻塞项 → 在提供继续选项前高亮显示
+- 存在交接文件 → 提及它，提供 `/specops:resume-work`
+</step>
+
+</process>
+
+<success_criteria>
+
+- [ ] 提供了丰富的上下文（近期工作、决策、问题）
+- [ ] 当前位置清晰，带可视化进度
+- [ ] 下一步清晰说明
+- [ ] 智能路由：如果计划存在则 /specops:execute-phase，否则 /specops:plan-phase
+- [ ] 用户在任何操作前确认
+- [ ] 无缝交接到适当的 specops 命令
+</success_criteria>