specops 0.2.4 → 0.3.0

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

@@ -0,0 +1,569 @@
+<purpose>
+为路线图阶段创建可执行的阶段提示（PLAN.md 文件），集成研究和验证。默认流程：研究（如需要）→ 规划 → 验证 → 完成。编排 specops-phase-researcher、specops-planner 和 specops-plan-checker Agent，带有修订循环（最多 3 次迭代）。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+
+@.opencode/references/ui-brand.md
+</required_reading>
+
+<process>
+
+## 1. 初始化
+
+一次调用加载所有上下文（仅路径以最小化编排器上下文）：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init plan-phase "$PHASE")
+```
+
+解析 JSON 获取：`researcher_model`、`planner_model`、`checker_model`、`research_enabled`、`plan_checker_enabled`、`nyquist_validation_enabled`、`commit_docs`、`phase_found`、`phase_dir`、`phase_number`、`phase_name`、`phase_slug`、`padded_phase`、`has_research`、`has_context`、`has_plans`、`plan_count`、`planning_exists`、`roadmap_exists`、`phase_req_ids`。
+
+**文件路径（用于 <files_to_read> 块）：** `state_path`、`roadmap_path`、`requirements_path`、`context_path`、`research_path`、`verification_path`、`uat_path`。如果文件不存在则为 null。
+
+**如果 `planning_exists` 为 false：** 报错——先运行 `/specops:new-project`。
+
+## 2. 解析和规范化参数
+
+从 $ARGUMENTS 提取：阶段编号（整数或小数如 `2.1`）、标志（`--research`、`--skip-research`、`--gaps`、`--skip-verify`、`--prd <filepath>`）。
+
+从 $ARGUMENTS 提取 `--prd <filepath>`。如果存在，将 PRD_FILE 设为该文件路径。
+
+**如果没有阶段编号：** 从路线图检测下一个未规划的阶段。
+
+**如果 `phase_found` 为 false：** 验证阶段是否存在于 ROADMAP.md 中。如果有效，使用 init 返回的 `phase_slug` 和 `padded_phase` 创建目录：
+```bash
+mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+```
+
+**来自 init 的现有产物：** `has_research`、`has_plans`、`plan_count`。
+
+## 3. 验证阶段
+
+```bash
+PHASE_INFO=$(node .opencode/bin/specops-tools.cjs roadmap get-phase "${PHASE}")
+```
+
+**如果 `found` 为 false：** 报错并显示可用阶段。**如果 `found` 为 true：** 从 JSON 提取 `phase_number`、`phase_name`、`goal`。
+
+## 3.5. 处理 PRD 快速路径
+
+**跳过条件：** 参数中没有 `--prd` 标志。
+
+**如果提供了 `--prd <filepath>`：**
+
+1. 读取 PRD 文件：
+```bash
+PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null)
+if [ -z "$PRD_CONTENT" ]; then
+  echo "Error: PRD file not found: $PRD_FILE"
+  exit 1
+fi
+```
+
+2. 显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► PRD 快速路径
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+使用 PRD：{PRD_FILE}
+正在从需求生成 CONTEXT.md...
+```
+
+3. 解析 PRD 内容并生成 CONTEXT.md。编排器应该：
+   - 从 PRD 中提取所有需求、用户故事、验收标准和约束
+   - 将每个映射为锁定决策（PRD 中的所有内容都视为锁定决策）
+   - 识别 PRD 未覆盖的领域并标记为"Claude's Discretion"
+   - 在阶段目录中创建 CONTEXT.md
+
+4. 写入 CONTEXT.md：
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+**Source:** PRD Express Path ({PRD_FILE})
+
+<domain>
+## Phase Boundary
+
+[从 PRD 提取——此阶段交付什么]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+{对于 PRD 中的每个需求/故事/标准：}
+### [从内容推导的类别]
+- [作为锁定决策的需求]
+
+### Claude's Discretion
+[PRD 未覆盖的领域——实现细节、技术选择]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[PRD 中的任何具体参考、示例或具体需求]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[PRD 中明确标记为未来/v2/范围外的项目]
+[如果没有："无——PRD 覆盖了阶段范围"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date] via PRD Express Path*
+```
+
+5. 提交：
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+6. 将 `context_content` 设为生成的 CONTEXT.md 内容，继续到步骤 5（处理研究）。
+
+**效果：** 这完全绕过了步骤 4（加载 CONTEXT.md），因为我们刚刚创建了它。工作流的其余部分（研究、规划、验证）使用 PRD 派生的上下文正常进行。
+
+## 4. 加载 CONTEXT.md
+
+**跳过条件：** 使用了 PRD 快速路径（CONTEXT.md 已在步骤 3.5 中创建）。
+
+检查 init JSON 中的 `context_path`。
+
+如果 `context_path` 不为 null，显示：`使用阶段上下文：${context_path}`
+
+**如果 `context_path` 为 null（没有 CONTEXT.md）：**
+
+使用 AskUserQuestion：
+- header: "无上下文"
+- question: "Phase {X} 没有找到 CONTEXT.md。计划将仅使用研究和需求——你的设计偏好不会被包含。继续还是先捕获上下文？"
+- options:
+  - "不使用上下文继续" — 仅使用研究 + 需求进行规划
+  - "先运行 discuss-phase" — 在规划前捕获设计决策
+
+如果"不使用上下文继续"：继续到步骤 5。
+如果"先运行 discuss-phase"：显示 `/specops:discuss-phase {X}` 并退出工作流。
+
+## 5. 处理研究
+
+**跳过条件：** `--gaps` 标志、`--skip-research` 标志，或 `research_enabled` 为 false（来自 init）且没有 `--research` 覆盖。
+
+**如果 `has_research` 为 true（来自 init）且没有 `--research` 标志：** 使用现有研究，跳到步骤 6。
+
+**如果 RESEARCH.md 缺失或有 `--research` 标志：**
+
+显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 研究 PHASE {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 正在生成研究员...
+```
+
+### 生成 specops-phase-researcher
+
+```bash
+PHASE_DESC=$(node .opencode/bin/specops-tools.cjs roadmap get-phase "${PHASE}" | jq -r '.section')
+```
+
+研究提示：
+
+```markdown
+<objective>
+Research how to implement Phase {phase_number}: {phase_name}
+Answer: "What do I need to know to PLAN this phase well?"
+</objective>
+
+<files_to_read>
+- {context_path} (USER DECISIONS from /specops:discuss-phase)
+- {requirements_path} (Project requirements)
+- {state_path} (Project decisions and history)
+</files_to_read>
+
+<additional_context>
+**Phase description:** {phase_description}
+**Phase requirement IDs (MUST address):** {phase_req_ids}
+
+**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines
+**Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, research should account for project skill patterns
+</additional_context>
+
+<output>
+Write to: {phase_dir}/{phase_num}-RESEARCH.md
+</output>
+```
+
+```
+Task(
+  prompt="First, read .opencode/agent/specops-phase-researcher.md for your role and instructions.\n\n" + research_prompt,
+  subagent_type="general-purpose",
+  model="{researcher_model}",
+  description="Research Phase {phase}"
+)
+```
+
+### 处理研究员返回
+
+- **`## RESEARCH COMPLETE`：** 显示确认，继续到步骤 6
+- **`## RESEARCH BLOCKED`：** 显示阻塞信息，提供选项：1) 提供上下文，2) 跳过研究，3) 中止
+
+## 5.5. 创建验证策略（如果 Nyquist 启用）
+
+**跳过条件：** INIT JSON 中 `nyquist_validation_enabled` 为 false。
+
+研究员完成后，检查 RESEARCH.md 是否包含 Validation Architecture 部分：
+
+```bash
+grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null
+```
+
+**如果找到：**
+1. 从 `.opencode/templates/VALIDATION.md` 读取验证模板
+2. 写入 `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
+3. 填充前置信息：将 `{N}` 替换为阶段编号，`{phase-slug}` 替换为阶段 slug，`{date}` 替换为当前日期
+4. 如果 `commit_docs` 为 true：
+```bash
+node .opencode/bin/specops-tools.cjs commit-docs "docs(phase-${PHASE}): add validation strategy"
+```
+
+**如果未找到（但 nyquist 已启用）：** 显示警告：
+```
+⚠ Nyquist 验证已启用但研究员未生成 Validation Architecture 部分。
+  继续但没有验证策略。计划可能无法通过 Dimension 8 检查。
+```
+
+## 6. 检查现有计划
+
+```bash
+ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null
+```
+
+**如果存在：** 提供选项：1) 添加更多计划，2) 查看现有计划，3) 从头重新规划。
+
+## 7. 使用 INIT 中的上下文路径
+
+从 INIT JSON 提取：
+
+```bash
+STATE_PATH=$(echo "$INIT" | jq -r '.state_path // empty')
+ROADMAP_PATH=$(echo "$INIT" | jq -r '.roadmap_path // empty')
+REQUIREMENTS_PATH=$(echo "$INIT" | jq -r '.requirements_path // empty')
+RESEARCH_PATH=$(echo "$INIT" | jq -r '.research_path // empty')
+VERIFICATION_PATH=$(echo "$INIT" | jq -r '.verification_path // empty')
+UAT_PATH=$(echo "$INIT" | jq -r '.uat_path // empty')
+CONTEXT_PATH=$(echo "$INIT" | jq -r '.context_path // empty')
+```
+
+## 8. 生成 specops-planner Agent
+
+显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 规划 PHASE {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 正在生成规划器...
+```
+
+规划器提示：
+
+```markdown
+<planning_context>
+**Phase:** {phase_number}
+**Mode:** {standard | gap_closure}
+
+<files_to_read>
+- {state_path} (Project State)
+- {roadmap_path} (Roadmap)
+- {requirements_path} (Requirements)
+- {context_path} (USER DECISIONS from /specops:discuss-phase)
+- {research_path} (Technical Research)
+- {verification_path} (Verification Gaps - if --gaps)
+- {uat_path} (UAT Gaps - if --gaps)
+</files_to_read>
+
+**Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
+
+**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines
+**Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules
+</planning_context>
+
+<downstream_consumer>
+Output consumed by /specops:execute-phase. Plans need:
+- Frontmatter (wave, depends_on, files_modified, autonomous)
+- Tasks in XML format
+- Verification criteria
+- must_haves for goal-backward verification
+</downstream_consumer>
+
+<quality_gate>
+- [ ] PLAN.md files created in phase directory
+- [ ] Each plan has valid frontmatter
+- [ ] Tasks are specific and actionable
+- [ ] Dependencies correctly identified
+- [ ] Waves assigned for parallel execution
+- [ ] must_haves derived from phase goal
+</quality_gate>
+```
+
+```
+Task(
+  prompt="First, read .opencode/agent/specops-planner.md for your role and instructions.\n\n" + filled_prompt,
+  subagent_type="general-purpose",
+  model="{planner_model}",
+  description="Plan Phase {phase}"
+)
+```
+
+## 9. 处理规划器返回
+
+- **`## PLANNING COMPLETE`：** 显示计划数量。如果 `--skip-verify` 或 `plan_checker_enabled` 为 false（来自 init）：跳到步骤 13。否则：步骤 10。
+- **`## CHECKPOINT REACHED`：** 展示给用户，获取回复，生成继续任务（步骤 12）
+- **`## PLANNING INCONCLUSIVE`：** 显示尝试次数，提供选项：添加上下文 / 重试 / 手动
+
+## 10. 生成 specops-plan-checker Agent
+
+显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 验证计划
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 正在生成计划检查器...
+```
+
+检查器提示：
+
+```markdown
+<verification_context>
+**Phase:** {phase_number}
+**Phase Goal:** {goal from ROADMAP}
+
+<files_to_read>
+- {PHASE_DIR}/*-PLAN.md (Plans to verify)
+- {roadmap_path} (Roadmap)
+- {requirements_path} (Requirements)
+- {context_path} (USER DECISIONS from /specops:discuss-phase)
+- {research_path} (Technical Research — includes Validation Architecture)
+</files_to_read>
+
+**Phase requirement IDs (MUST ALL be covered):** {phase_req_ids}
+
+**Project instructions:** Read ./CLAUDE.md if exists — verify plans honor project guidelines
+**Project skills:** Check .agents/skills/ directory (if exists) — verify plans account for project skill rules
+</verification_context>
+
+<expected_output>
+- ## VERIFICATION PASSED — all checks pass
+- ## ISSUES FOUND — structured issue list
+</expected_output>
+```
+
+```
+Task(
+  prompt=checker_prompt,
+  subagent_type="specops-plan-checker",
+  model="{checker_model}",
+  description="Verify Phase {phase} plans"
+)
+```
+
+## 11. 处理检查器返回
+
+- **`## VERIFICATION PASSED`：** 显示确认，继续到步骤 13。
+- **`## ISSUES FOUND`：** 显示问题，检查迭代次数，继续到步骤 12。
+
+## 12. 修订循环（最多 3 次迭代）
+
+跟踪 `iteration_count`（初始规划 + 检查后从 1 开始）。
+
+**如果 iteration_count < 3：**
+
+显示：`正在发回规划器修订...（迭代 {N}/3）`
+
+修订提示：
+
+```markdown
+<revision_context>
+**Phase:** {phase_number}
+**Mode:** revision
+
+<files_to_read>
+- {PHASE_DIR}/*-PLAN.md (Existing plans)
+- {context_path} (USER DECISIONS from /specops:discuss-phase)
+</files_to_read>
+
+**Checker issues:** {structured_issues_from_checker}
+</revision_context>
+
+<instructions>
+Make targeted updates to address checker issues.
+Do NOT replan from scratch unless issues are fundamental.
+Return what changed.
+</instructions>
+```
+
+```
+Task(
+  prompt="First, read .opencode/agent/specops-planner.md for your role and instructions.\n\n" + revision_prompt,
+  subagent_type="general-purpose",
+  model="{planner_model}",
+  description="Revise Phase {phase} plans"
+)
+```
+
+规划器返回后 → 再次生成检查器（步骤 10），递增 iteration_count。
+
+**如果 iteration_count >= 3：**
+
+显示：`已达最大迭代次数。{N} 个问题仍然存在：` + 问题列表
+
+提供选项：1) 强制继续，2) 提供指导并重试，3) 放弃
+
+## 13. 展示最终状态
+
+根据标志/配置路由到 `<offer_next>` 或 `auto_advance`。
+
+## 14. 自动推进检查
+
+检查自动推进触发条件：
+
+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：**
+
+显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 自动推进到执行
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+计划就绪。正在生成 execute-phase...
+```
+
+将 execute-phase 作为 Task 生成，使用直接工作流文件引用（不要使用 Skill 工具——Skill 在 Task 子 Agent 中无法解析）：
+```
+Task(
+  prompt="
+    <objective>
+    你是 execute-phase 编排器。执行 Phase ${PHASE}: ${PHASE_NAME} 的所有计划。
+    </objective>
+
+    <execution_context>
+    @.opencode/workflows/execute-phase.md
+    @.opencode/references/checkpoints.md
+    @.opencode/references/tdd.md
+    @.opencode/references/model-profile-resolution.md
+    </execution_context>
+
+    <arguments>
+    PHASE=${PHASE}
+    ARGUMENTS='${PHASE} --auto --no-transition'
+    </arguments>
+
+    <instructions>
+    1. 从 execution_context 读取 execute-phase.md 获取完整工作流
+    2. 遵循所有步骤：initialize、handle_branching、validate_phase、discover_and_group_plans、execute_waves、aggregate_results、close_parent_artifacts、verify_phase_goal、update_roadmap
+    3. --no-transition 标志意味着：验证 + 路线图更新后，停止并返回状态。不要运行 transition.md。
+    4. 生成执行器 Agent 时，使用 subagent_type='specops-executor' 并使用工作流中现有的 @file 模式
+    5. 生成验证器 Agent 时，使用 subagent_type='specops-verifier'
+    6. 保留 classifyHandoffIfNeeded 变通方案（针对该特定错误的抽查）
+    7. 不要使用 Skill 工具或 /specops: 命令
+    </instructions>
+  ",
+  subagent_type="general-purpose",
+  description="Execute Phase ${PHASE}"
+)
+```
+
+**处理 execute-phase 返回：**
+- **PHASE COMPLETE** → 显示最终摘要：
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   SpecOps ► PHASE ${PHASE} 完成 ✓
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  自动推进流水线完成。
+
+  下一步：/specops:discuss-phase ${NEXT_PHASE} --auto
+  ```
+- **GAPS FOUND / VERIFICATION FAILED** → 显示结果，停止链：
+  ```
+  自动推进已停止：执行需要审查。
+
+  审查上面的输出并手动继续：
+  /specops:execute-phase ${PHASE}
+  ```
+
+**如果既没有 `--auto` 也没有配置启用：**
+路由到 `<offer_next>`（现有行为）。
+
+</process>
+
+<offer_next>
+直接输出此 markdown（不作为代码块）：
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► PHASE {X} 规划完成 ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {X}: {名称}** — {N} 个计划，{M} 个波次
+
+| 波次 | 计划 | 构建内容 |
+|------|------|----------|
+| 1    | 01, 02 | [目标] |
+| 2    | 03     | [目标] |
+
+研究：{已完成 | 使用现有 | 已跳过}
+验证：{通过 | 覆盖后通过 | 已跳过}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ 下一步
+
+**执行 Phase {X}** — 运行所有 {N} 个计划
+
+/specops:execute-phase {X}
+
+<sub>/clear 先清理 → 全新上下文窗口</sub>
+
+───────────────────────────────────────────────────────────────
+
+**其他可用操作：**
+- cat .planning/phases/{phase-dir}/*-PLAN.md — 审查计划
+- /specops:plan-phase {X} --research — 先重新研究
+
+───────────────────────────────────────────────────────────────
+</offer_next>
+
+<success_criteria>
+- [ ] .planning/ 目录已验证
+- [ ] 阶段已根据路线图验证
+- [ ] 阶段目录已创建（如需要）
+- [ ] CONTEXT.md 在步骤 4 中提前加载并传递给所有 Agent
+- [ ] 研究已完成（除非 --skip-research 或 --gaps 或已存在）
+- [ ] specops-phase-researcher 已生成并附带 CONTEXT.md
+- [ ] 现有计划已检查
+- [ ] specops-planner 已生成并附带 CONTEXT.md + RESEARCH.md
+- [ ] 计划已创建（PLANNING COMPLETE 或 CHECKPOINT 已处理）
+- [ ] specops-plan-checker 已生成并附带 CONTEXT.md
+- [ ] 验证通过或用户覆盖或达到最大迭代次数后用户决定
+- [ ] Agent 生成之间用户可以看到状态
+- [ ] 用户知道后续步骤
+</success_criteria>