specops 0.2.4 → 0.3.0

package/.opencode/workflows/execute-phase.md

@@ -0,0 +1,449 @@
+<purpose>
+使用基于波次的并行执行方式执行阶段中的所有计划。编排器保持精简——将计划执行委托给子代理。
+</purpose>
+
+<core_principle>
+编排器负责协调，而非执行。每个子代理加载完整的 execute-plan 上下文。编排器：发现计划 → 分析依赖 → 分组波次 → 生成代理 → 处理检查点 → 收集结果。
+</core_principle>
+
+<required_reading>
+在任何操作之前先读取 STATE.md 以加载项目上下文。
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+一次调用加载所有上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init execute-phase "${PHASE_ARG}")
+```
+
+从 JSON 中解析：`executor_model`、`verifier_model`、`commit_docs`、`parallelization`、`branching_strategy`、`branch_name`、`phase_found`、`phase_dir`、`phase_number`、`phase_name`、`phase_slug`、`plans`、`incomplete_plans`、`plan_count`、`incomplete_count`、`state_exists`、`roadmap_exists`、`phase_req_ids`。
+
+**如果 `phase_found` 为 false：** 错误——未找到阶段目录。
+**如果 `plan_count` 为 0：** 错误——阶段中未找到计划。
+**如果 `state_exists` 为 false 但 `.planning/` 存在：** 提供重建或继续的选项。
+
+当 `parallelization` 为 false 时，波次内的计划按顺序执行。
+</step>
+
+<step name="handle_branching">
+从 init 检查 `branching_strategy`：
+
+**"none"：** 跳过，继续在当前分支上工作。
+
+**"phase" 或 "milestone"：** 使用 init 预计算的 `branch_name`：
+```bash
+git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+```
+
+后续所有提交都到此分支。用户自行处理合并。
+</step>
+
+<step name="validate_phase">
+从 init JSON 获取：`phase_dir`、`plan_count`、`incomplete_count`。
+
+报告："在 {phase_dir} 中找到 {plan_count} 个计划（{incomplete_count} 个未完成）"
+</step>
+
+<step name="discover_and_group_plans">
+一次调用加载带波次分组的计划清单：
+
+```bash
+PLAN_INDEX=$(node .opencode/bin/specops-tools.cjs phase-plan-index "${PHASE_NUMBER}")
+```
+
+从 JSON 中解析：`phase`、`plans[]`（每个包含 `id`、`wave`、`autonomous`、`objective`、`files_modified`、`task_count`、`has_summary`）、`waves`（波次编号到计划 ID 的映射）、`incomplete`、`has_checkpoints`。
+
+**过滤：** 跳过 `has_summary: true` 的计划。如果使用 `--gaps-only`：同时跳过非 gap_closure 计划。如果全部被过滤："没有匹配的未完成计划" → 退出。
+
+报告：
+```
+## 执行计划
+
+**阶段 {X}：{Name}** — {total_plans} 个计划，分 {wave_count} 个波次
+
+| 波次 | 计划 | 构建内容 |
+|------|------|----------|
+| 1 | 01-01, 01-02 | {从计划目标提取，3-8 个词} |
+| 2 | 01-03 | ... |
+```
+</step>
+
+<step name="execute_waves">
+按顺序执行每个波次。波次内部：如果 `PARALLELIZATION=true` 则并行，如果为 `false` 则顺序执行。
+
+**对于每个波次：**
+
+1. **描述正在构建的内容（生成代理之前）：**
+
+   读取每个计划的 `<objective>`。提取正在构建的内容和原因。
+
+   ```
+   ---
+   ## 波次 {N}
+
+   **{Plan ID}：{Plan Name}**
+   {2-3 句话：构建内容、技术方案、为什么重要}
+
+   正在生成 {count} 个代理...
+   ---
+   ```
+
+   - 差：「执行地形生成计划」
+   - 好：「使用 Perlin 噪声的程序化地形生成器——创建高度图、生态区域和碰撞网格。在车辆物理引擎与地面交互之前必须完成。」
+
+2. **生成执行器代理：**
+
+   只传递路径——执行器用它们的全新 200k 上下文自行读取文件。
+   这让编排器上下文保持精简（约 10-15%）。
+
+   ```
+   Task(
+     subagent_type="specops-executor",
+     model="{executor_model}",
+     prompt="
+       <objective>
+       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+       Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
+       </objective>
+
+       <execution_context>
+       @.opencode/workflows/execute-plan.md
+       @.opencode/templates/summary.md
+       @.opencode/references/checkpoints.md
+       @.opencode/references/tdd.md
+       </execution_context>
+
+       <files_to_read>
+       Read these files at execution start using the Read tool:
+       - {phase_dir}/{plan_file} (Plan)
+       - .planning/STATE.md (State)
+       - .planning/config.json (Config, if exists)
+       - ./CLAUDE.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
+       - .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
+       </files_to_read>
+
+       <success_criteria>
+       - [ ] All tasks executed
+       - [ ] Each task committed individually
+       - [ ] SUMMARY.md created in plan directory
+       - [ ] STATE.md updated with position and decisions
+       - [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
+       </success_criteria>
+     "
+   )
+   ```
+
+3. **等待波次中所有代理完成。**
+
+4. **报告完成——先抽查验证声明：**
+
+   对于每个 SUMMARY.md：
+   - 验证 `key-files.created` 中前 2 个文件在磁盘上存在
+   - 检查 `git log --oneline --all --grep="{phase}-{plan}"` 返回 ≥1 个提交
+   - 检查是否有 `## Self-Check: FAILED` 标记
+
+   如果任何抽查失败：报告哪个计划失败，路由到失败处理程序——询问「重试计划？」或「继续剩余波次？」
+
+   如果通过：
+   ```
+   ---
+   ## 波次 {N} 完成
+
+   **{Plan ID}：{Plan Name}**
+   {构建了什么——来自 SUMMARY.md}
+   {显著偏差（如有）}
+
+   {如果还有更多波次：这为下一波次启用了什么}
+   ---
+   ```
+
+   - 差：「波次 2 完成。继续波次 3。」
+   - 好：「地形系统完成——3 种生态类型、基于高度的纹理、物理碰撞网格。车辆物理（波次 3）现在可以引用地面表面。」
+
+5. **处理失败：**
+
+   **已知 Claude Code bug（classifyHandoffIfNeeded）：** 如果代理报告「失败」且错误包含 `classifyHandoffIfNeeded is not defined`，这是 Claude Code 运行时 bug——不是 SpecOps 或代理的问题。该错误在所有工具调用完成后的完成处理程序中触发。此时：运行与步骤 4 相同的抽查（SUMMARY.md 存在、git 提交存在、无 Self-Check: FAILED）。如果抽查通过 → 视为**成功**。如果抽查失败 → 按下面的真实失败处理。
+
+   对于真实失败：报告哪个计划失败 → 询问「继续？」或「停止？」→ 如果继续，依赖计划也可能失败。如果停止，输出部分完成报告。
+
+6. **在波次之间执行检查点计划** — 参见 `<checkpoint_handling>`。
+
+7. **继续下一波次。**
+</step>
+
+<step name="checkpoint_handling">
+`autonomous: false` 的计划需要用户交互。
+
+**自动模式检查点处理：**
+
+读取自动推进配置：
+```bash
+AUTO_CFG=$(node .opencode/bin/specops-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+```
+
+当执行器返回检查点且 `AUTO_CFG` 为 `"true"` 时：
+- **human-verify** → 自动生成延续代理，`{user_response}` = `"approved"`。记录 `⚡ 自动批准检查点`。
+- **decision** → 自动生成延续代理，`{user_response}` = 检查点详情中的第一个选项。记录 `⚡ 自动选择：[option]`。
+- **human-action** → 向用户展示（下面的现有行为）。认证门控不能自动化。
+
+**标准流程（非自动模式，或 human-action 类型）：**
+
+1. 为检查点计划生成代理
+2. 代理运行直到检查点任务或认证门控 → 返回结构化状态
+3. 代理返回包括：已完成任务表、当前任务 + 阻塞原因、检查点类型/详情、等待内容
+4. **向用户展示：**
+   ```
+   ## 检查点：[Type]
+
+   **计划：** 03-03 Dashboard Layout
+   **进度：** 2/3 任务完成
+
+   [来自代理返回的检查点详情]
+   [来自代理返回的等待部分]
+   ```
+5. 用户响应："approved"/"done" | 问题描述 | 决策选择
+6. **生成延续代理（不是恢复）** 使用 continuation-prompt.md 模板：
+   - `{completed_tasks_table}`：来自检查点返回
+   - `{resume_task_number}` + `{resume_task_name}`：当前任务
+   - `{user_response}`：用户提供的内容
+   - `{resume_instructions}`：基于检查点类型
+7. 延续代理验证之前的提交，从恢复点继续
+8. 重复直到计划完成或用户停止
+
+**为什么用新代理而不是恢复：** 恢复依赖于在并行工具调用时会中断的内部序列化。使用显式状态的新代理更可靠。
+
+**并行波次中的检查点：** 代理暂停并返回，而其他并行代理可能已完成。展示检查点，生成延续，等待所有代理完成后再进入下一波次。
+</step>
+
+<step name="aggregate_results">
+所有波次完成后：
+
+```markdown
+## 阶段 {X}：{Name} 执行完成
+
+**波次：** {N} | **计划：** {M}/{total} 完成
+
+| 波次 | 计划 | 状态 |
+|------|------|------|
+| 1 | plan-01, plan-02 | ✓ 完成 |
+| CP | plan-03 | ✓ 已验证 |
+| 2 | plan-04 | ✓ 完成 |
+
+### 计划详情
+1. **03-01**：[来自 SUMMARY.md 的一句话]
+2. **03-02**：[来自 SUMMARY.md 的一句话]
+
+### 遇到的问题
+[从 SUMMARY 汇总，或「无」]
+```
+</step>
+
+<step name="close_parent_artifacts">
+**仅适用于小数/打磨阶段（X.Y 模式）：** 通过解决父级 UAT 和调试产物来关闭反馈循环。
+
+**如果**阶段编号没有小数点（如 `3`、`04`）则跳过——仅适用于间隙修复阶段如 `4.1`、`03.1`。
+
+**1. 检测小数阶段并推导父级：**
+```bash
+# Check if phase_number contains a decimal
+if [[ "$PHASE_NUMBER" == *.* ]]; then
+  PARENT_PHASE="${PHASE_NUMBER%%.*}"
+fi
+```
+
+**2. 查找父级 UAT 文件：**
+```bash
+PARENT_INFO=$(node .opencode/bin/specops-tools.cjs find-phase "${PARENT_PHASE}" --raw)
+# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
+```
+
+**如果未找到父级 UAT：** 跳过此步骤（间隙修复可能由 VERIFICATION.md 触发而非 UAT）。
+
+**3. 更新 UAT 间隙状态：**
+
+读取父级 UAT 文件的 `## Gaps` 部分。对于每个 `status: failed` 的间隙条目：
+- 更新为 `status: resolved`
+
+**4. 更新 UAT 前置信息：**
+
+如果所有间隙现在都是 `status: resolved`：
+- 将前置信息 `status: diagnosed` → `status: resolved`
+- 更新前置信息 `updated:` 时间戳
+
+**5. 解决引用的调试会话：**
+
+对于每个有 `debug_session:` 字段的间隙：
+- 读取调试会话文件
+- 将前置信息 `status:` → `resolved`
+- 更新前置信息 `updated:` 时间戳
+- 移动到已解决目录：
+```bash
+mkdir -p .planning/debug/resolved
+mv .planning/debug/{slug}.md .planning/debug/resolved/
+```
+
+**6. 提交更新的产物：**
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
+```
+</step>
+
+<step name="verify_phase_goal">
+验证阶段是否达成了目标，而不仅仅是完成了任务。
+
+```
+Task(
+  prompt="Verify phase {phase_number} goal achievement.
+Phase directory: {phase_dir}
+Phase goal: {goal from ROADMAP.md}
+Phase requirement IDs: {phase_req_ids}
+Check must_haves against actual codebase.
+Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for.
+Create VERIFICATION.md.",
+  subagent_type="specops-verifier",
+  model="{verifier_model}"
+)
+```
+
+读取状态：
+```bash
+grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
+```
+
+| 状态 | 操作 |
+|------|------|
+| `passed` | → update_roadmap |
+| `human_needed` | 展示需要人工测试的项目，获取批准或反馈 |
+| `gaps_found` | 展示间隙摘要，提供 `/specops:plan-phase {phase} --gaps` |
+
+**如果 human_needed：**
+```
+## ✓ 阶段 {X}：{Name} — 需要人工验证
+
+所有自动化检查通过。{N} 个项目需要人工测试：
+
+{来自 VERIFICATION.md human_verification 部分}
+
+"approved" → 继续 | 报告问题 → 间隙修复
+```
+
+**如果 gaps_found：**
+```
+## ⚠ 阶段 {X}：{Name} — 发现间隙
+
+**得分：** {N}/{M} 个必需项已验证
+**报告：** {phase_dir}/{phase_num}-VERIFICATION.md
+
+### 缺失内容
+{来自 VERIFICATION.md 的间隙摘要}
+
+---
+## ▶ 下一步
+
+`/specops:plan-phase {X} --gaps`
+
+<sub>`/clear` 先清理 → 全新上下文窗口</sub>
+
+也可以：`cat {phase_dir}/{phase_num}-VERIFICATION.md` — 完整报告
+也可以：`/specops:verify-work {X}` — 先进行手动测试
+```
+
+间隙修复循环：`/specops:plan-phase {X} --gaps` 读取 VERIFICATION.md → 创建带 `gap_closure: true` 的间隙计划 → 用户运行 `/specops:execute-phase {X} --gaps-only` → 验证器重新运行。
+</step>
+
+<step name="update_roadmap">
+**标记阶段完成并更新所有跟踪文件：**
+
+```bash
+COMPLETION=$(node .opencode/bin/specops-tools.cjs phase complete "${PHASE_NUMBER}")
+```
+
+CLI 处理：
+- 用完成日期标记阶段复选框 `[x]`
+- 更新进度表（状态 → 完成、日期）
+- 将计划数更新为最终值
+- 在 STATE.md 中推进到下一阶段
+- 更新 REQUIREMENTS.md 可追溯性
+
+从结果中提取：`next_phase`、`next_phase_name`、`is_last_phase`。
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
+```
+</step>
+
+<step name="offer_next">
+
+**例外：** 如果 `gaps_found`，`verify_phase_goal` 步骤已经展示了间隙修复路径（`/specops:plan-phase {X} --gaps`）。不需要额外路由——跳过自动推进。
+
+**无转换检查（由自动推进链生成）：**
+
+从 $ARGUMENTS 解析 `--no-transition` 标志。
+
+**如果存在 `--no-transition` 标志：**
+
+execute-phase 由 plan-phase 的自动推进生成。不要运行 transition.md。
+验证通过且路线图更新后，向父级返回完成状态：
+
+```
+## PHASE COMPLETE
+
+Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
+Plans: ${completed_count}/${total_count}
+Verification: {Passed | Gaps Found}
+
+[Include aggregate_results output]
+```
+
+停止。不要继续自动推进或转换。
+
+**如果不存在 `--no-transition` 标志：**
+
+**自动推进检测：**
+
+1. 从 $ARGUMENTS 解析 `--auto` 标志
+2. 从配置读取 `workflow.auto_advance`：
+   ```bash
+   AUTO_CFG=$(node .opencode/bin/specops-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+   ```
+
+**如果存在 `--auto` 标志或 `AUTO_CFG` 为 true（且验证通过无间隙）：**
+
+```
+╔══════════════════════════════════════════╗
+║  AUTO-ADVANCING → TRANSITION             ║
+║  Phase {X} verified, continuing chain    ║
+╚══════════════════════════════════════════╝
+```
+
+内联执行转换工作流（不要使用 Task——编排器上下文约 10-15%，转换需要的阶段完成数据已在上下文中）：
+
+读取并执行 `.opencode/workflows/transition.md`，传递 `--auto` 标志使其传播到下一阶段调用。
+
+**如果既没有 `--auto` 也没有 `AUTO_CFG` 为 true：**
+
+工作流结束。用户运行 `/specops:progress` 或手动调用转换工作流。
+</step>
+
+</process>
+
+<context_efficiency>
+编排器：约 10-15% 上下文。子代理：每个全新 200k。无轮询（Task 阻塞）。无上下文泄漏。
+</context_efficiency>
+
+<failure_handling>
+- **classifyHandoffIfNeeded 误报失败：** 代理报告「失败」但错误是 `classifyHandoffIfNeeded is not defined` → Claude Code bug，不是 SpecOps 问题。抽查（SUMMARY 存在、提交存在）→ 如果通过，视为成功
+- **代理在计划中途失败：** 缺少 SUMMARY.md → 报告，询问用户如何处理
+- **依赖链断裂：** 波次 1 失败 → 波次 2 依赖项可能也会失败 → 用户选择尝试或跳过
+- **波次中所有代理都失败：** 系统性问题 → 停止，报告以供调查
+- **检查点无法解决：** 「跳过此计划？」或「中止阶段执行？」→ 在 STATE.md 中记录部分进度
+</failure_handling>
+
+<resumption>
+重新运行 `/specops:execute-phase {phase}` → discover_plans 找到已完成的 SUMMARY → 跳过它们 → 从第一个未完成的计划恢复 → 继续波次执行。
+
+STATE.md 跟踪：最后完成的计划、当前波次、待处理的检查点。
+</resumption>