specops 0.2.4 → 0.3.0

package/.opencode/workflows/pause-work.md

@@ -0,0 +1,122 @@
+<purpose>
+创建 `.continue-here.md` 交接文件，保存完整的工作状态以便跨会话恢复。支持无缝恢复并完整还原上下文。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="detect">
+从最近修改的文件中查找当前阶段目录：
+
+```bash
+# Find most recent phase directory with work
+ls -lt .planning/phases/*/PLAN.md 2>/dev/null | head -1 | grep -oP 'phases/\K[^/]+'
+```
+
+如果未检测到活跃阶段，询问用户正在暂停哪个阶段的工作。
+</step>
+
+<step name="gather">
+**收集完整的交接状态：**
+
+1. **当前位置**：哪个阶段、哪个计划、哪个任务
+2. **已完成工作**：本次会话完成了什么
+3. **剩余工作**：当前计划/阶段还剩什么
+4. **已做决策**：关键决策及其理由
+5. **阻塞/问题**：任何卡住的地方
+6. **思维上下文**：当前方法、后续步骤、整体思路
+7. **已修改文件**：已更改但未提交的内容
+
+如有需要，通过对话式提问向用户确认。
+</step>
+
+<step name="write">
+**将交接信息写入 `.planning/phases/XX-name/.continue-here.md`：**
+
+```markdown
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: [timestamp from current-timestamp]
+---
+
+<current_state>
+[Where exactly are we? Immediate context]
+</current_state>
+
+<completed_work>
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done]
+</completed_work>
+
+<remaining_work>
+
+- Task 3: [what's left]
+- Task 4: Not started
+- Task 5: Not started
+</remaining_work>
+
+<decisions_made>
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<blockers>
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, what were you thinking, the plan]
+</context>
+
+<next_action>
+Start with: [specific first action when resuming]
+</next_action>
+```
+
+内容要足够具体，让全新的 Claude 能立即理解。
+
+使用 `current-timestamp` 获取 last_updated 字段。可以使用 init todos（提供时间戳）或直接调用：
+```bash
+timestamp=$(node .opencode/bin/specops-tools.cjs current-timestamp full --raw)
+```
+</step>
+
+<step name="commit">
+```bash
+node .opencode/bin/specops-tools.cjs commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md
+```
+</step>
+
+<step name="confirm">
+```
+✓ Handoff created: .planning/phases/[XX-name]/.continue-here.md
+
+Current state:
+
+- Phase: [XX-name]
+- Task: [X] of [Y]
+- Status: [in_progress/blocked]
+- Committed as WIP
+
+To resume: /specops:resume-work
+
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] .continue-here.md 已在正确的阶段目录中创建
+- [ ] 所有部分都填写了具体内容
+- [ ] 已作为 WIP 提交
+- [ ] 用户知道文件位置及如何恢复
+</success_criteria>

package/.opencode/workflows/plan-milestone-gaps.md

@@ -0,0 +1,274 @@
+<purpose>
+创建所有必要的阶段来关闭 `/specops:audit-milestone` 识别出的缺口。读取 MILESTONE-AUDIT.md，将缺口分组为逻辑阶段，在 ROADMAP.md 中创建阶段条目，并提供规划每个阶段的选项。一个命令创建所有修复阶段——无需为每个缺口手动执行 `/specops:add-phase`。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+## 1. 加载审计结果
+
+```bash
+# 查找最近的审计文件
+ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | head -1
+```
+
+解析 YAML frontmatter 以提取结构化缺口：
+- `gaps.requirements` — 未满足的需求
+- `gaps.integration` — 缺失的跨阶段连接
+- `gaps.flows` — 中断的端到端流程
+
+如果没有审计文件或没有缺口，报错：
+```
+未找到审计缺口。请先运行 `/specops:audit-milestone`。
+```
+
+## 2. 确定缺口优先级
+
+按 REQUIREMENTS.md 中的优先级对缺口分组：
+
+| 优先级 | 操作 |
+|--------|------|
+| `must` | 创建阶段，阻塞里程碑 |
+| `should` | 创建阶段，推荐 |
+| `nice` | 询问用户：包含还是推迟？ |
+
+对于集成/流程缺口，从受影响的需求推断优先级。
+
+## 3. 将缺口分组为阶段
+
+将相关缺口聚类为逻辑阶段：
+
+**分组规则：**
+- 影响同一阶段 → 合并为一个修复阶段
+- 同一子系统（认证、API、UI）→ 合并
+- 依赖顺序（先修复桩代码再修复连接）
+- 保持阶段聚焦：每个 2-4 个任务
+
+**分组示例：**
+```
+缺口：DASH-01 未满足（仪表盘不获取数据）
+缺口：集成 阶段 1→3（认证未传递到 API 调用）
+缺口：流程"查看仪表盘"在数据获取处中断
+
+→ 阶段 6："连接仪表盘到 API"
+  - 在 Dashboard.tsx 中添加 fetch
+  - 在 fetch 中包含 auth header
+  - 处理响应，更新状态
+  - 渲染用户数据
+```
+
+## 4. 确定阶段编号
+
+找到现有最高阶段编号：
+```bash
+# 获取排序后的阶段列表，提取最后一个
+PHASES=$(node .opencode/bin/specops-tools.cjs phases list)
+HIGHEST=$(echo "$PHASES" | jq -r '.directories[-1]')
+```
+
+新阶段从此处继续：
+- 如果阶段 5 是最高的，缺口修复阶段变为阶段 6、7、8……
+
+## 5. 展示缺口修复计划
+
+```markdown
+## 缺口修复计划
+
+**里程碑：** {version}
+**待关闭缺口：** {N} 个需求、{M} 个集成、{K} 个流程
+
+### 拟定阶段
+
+**阶段 {N}：{名称}**
+关闭：
+- {REQ-ID}：{描述}
+- 集成：{from} → {to}
+任务数：{count}
+
+**阶段 {N+1}：{名称}**
+关闭：
+- {REQ-ID}：{描述}
+- 流程：{流程名称}
+任务数：{count}
+
+{如果存在 nice-to-have 缺口：}
+
+### 已推迟（nice-to-have）
+
+这些缺口是可选的。是否包含？
+- {缺口描述}
+- {缺口描述}
+
+---
+
+创建这 {X} 个阶段？（是 / 调整 / 推迟所有可选项）
+```
+
+等待用户确认。
+
+## 6. 更新 ROADMAP.md
+
+将新阶段添加到当前里程碑：
+
+```markdown
+### Phase {N}: {名称}
+**Goal:** {从待关闭的缺口推导}
+**Requirements:** {待满足的 REQ-ID}
+**Gap Closure:** 关闭审计中的缺口
+
+### Phase {N+1}: {名称}
+...
+```
+
+## 7. 更新 REQUIREMENTS.md 追溯表（必需）
+
+对于分配到缺口修复阶段的每个 REQ-ID：
+- 更新 Phase 列以反映新的缺口修复阶段
+- 将 Status 重置为 `Pending`
+
+重置审计发现未满足的已勾选需求：
+- 将审计中标记为未满足的需求从 `[x]` 改为 `[ ]`
+- 更新 REQUIREMENTS.md 顶部的覆盖率计数
+
+```bash
+# 验证追溯表反映了缺口修复分配
+grep -c "Pending" .planning/REQUIREMENTS.md
+```
+
+## 8. 创建阶段目录
+
+```bash
+mkdir -p ".planning/phases/{NN}-{name}"
+```
+
+## 9. 提交路线图和需求更新
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
+```
+
+## 10. 提供后续步骤
+
+```markdown
+## ✓ 缺口修复阶段已创建
+
+**已添加阶段：** {N} - {M}
+**已处理缺口：** {count} 个需求、{count} 个集成、{count} 个流程
+
+---
+
+## ▶ 下一步
+
+**规划第一个缺口修复阶段**
+
+`/specops:plan-phase {N}`
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:execute-phase {N}` — 如果计划已存在
+- `cat .planning/ROADMAP.md` — 查看更新后的路线图
+
+---
+
+**所有缺口阶段完成后：**
+
+`/specops:audit-milestone` — 重新审计以验证缺口已关闭
+`/specops:complete-milestone {version}` — 审计通过后归档
+```
+
+</process>
+
+<gap_to_phase_mapping>
+
+## 缺口如何变为任务
+
+**需求缺口 → 任务：**
+```yaml
+gap:
+  id: DASH-01
+  description: "User sees their data"
+  reason: "Dashboard exists but doesn't fetch from API"
+  missing:
+    - "useEffect with fetch to /api/user/data"
+    - "State for user data"
+    - "Render user data in JSX"
+
+becomes:
+
+phase: "Wire Dashboard Data"
+tasks:
+  - name: "Add data fetching"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useEffect that fetches /api/user/data on mount"
+
+  - name: "Add state management"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useState for userData, loading, error states"
+
+  - name: "Render user data"
+    files: [src/components/Dashboard.tsx]
+    action: "Replace placeholder with userData.map rendering"
+```
+
+**集成缺口 → 任务：**
+```yaml
+gap:
+  from_phase: 1
+  to_phase: 3
+  connection: "Auth token → API calls"
+  reason: "Dashboard API calls don't include auth header"
+  missing:
+    - "Auth header in fetch calls"
+    - "Token refresh on 401"
+
+becomes:
+
+phase: "Add Auth to Dashboard API Calls"
+tasks:
+  - name: "Add auth header to fetches"
+    files: [src/components/Dashboard.tsx, src/lib/api.ts]
+    action: "Include Authorization header with token in all API calls"
+
+  - name: "Handle 401 responses"
+    files: [src/lib/api.ts]
+    action: "Add interceptor to refresh token or redirect to login on 401"
+```
+
+**流程缺口 → 任务：**
+```yaml
+gap:
+  name: "User views dashboard after login"
+  broken_at: "Dashboard data load"
+  reason: "No fetch call"
+  missing:
+    - "Fetch user data on mount"
+    - "Display loading state"
+    - "Render user data"
+
+becomes:
+
+# 通常与需求/集成缺口属于同一阶段
+# 流程缺口经常与其他缺口类型重叠
+```
+
+</gap_to_phase_mapping>
+
+<success_criteria>
+- [ ] 已加载 MILESTONE-AUDIT.md 并解析缺口
+- [ ] 已确定缺口优先级（must/should/nice）
+- [ ] 已将缺口分组为逻辑阶段
+- [ ] 用户已确认阶段计划
+- [ ] 已更新 ROADMAP.md 添加新阶段
+- [ ] 已更新 REQUIREMENTS.md 追溯表的缺口修复阶段分配
+- [ ] 已重置未满足需求的复选框（`[x]` → `[ ]`）
+- [ ] 已更新 REQUIREMENTS.md 中的覆盖率计数
+- [ ] 已创建阶段目录
+- [ ] 已提交变更（包含 REQUIREMENTS.md）
+- [ ] 用户知道接下来运行 `/specops:plan-phase`
+</success_criteria>