specops 0.2.5 → 0.3.2

package/.opencode/workflows/resume-project.md

@@ -0,0 +1,304 @@
+<trigger>
+在以下情况使用此工作流：
+- 在现有项目上开始新会话
+- 用户说"继续"、"下一步是什么"、"我们到哪了"、"恢复"
+- 当 .planning/ 已存在时的任何规划操作
+- 用户离开项目一段时间后返回
+</trigger>
+
+<purpose>
+即时恢复完整的项目上下文，让"我们到哪了？"能得到即时、完整的回答。
+</purpose>
+
+<required_reading>
+@.opencode/references/continuation-format.md
+</required_reading>
+
+<process>
+
+<step name="initialize">
+一次调用加载所有上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init resume)
+```
+
+解析 JSON 获取：`state_exists`、`roadmap_exists`、`project_exists`、`planning_exists`、`has_interrupted_agent`、`interrupted_agent_id`、`commit_docs`。
+
+**如果 `state_exists` 为 true：** 继续到 load_state
+**如果 `state_exists` 为 false 但 `roadmap_exists` 或 `project_exists` 为 true：** 提供重建 STATE.md 的选项
+**如果 `planning_exists` 为 false：** 这是新项目——路由到 /specops:new-project
+</step>
+
+<step name="load_state">
+
+读取并解析 STATE.md，然后读取 PROJECT.md：
+
+```bash
+cat .planning/STATE.md
+cat .planning/PROJECT.md
+```
+
+**从 STATE.md 提取：**
+
+- **项目参考**：核心价值和当前焦点
+- **当前位置**：第 X 阶段（共 Y 个），计划 A（共 B 个），状态
+- **进度**：可视化进度条
+- **近期决策**：影响当前工作的关键决策
+- **待办事项**：会话期间捕获的想法
+- **阻塞/关注点**：遗留的问题
+- **会话连续性**：上次停在哪里，任何恢复文件
+
+**从 PROJECT.md 提取：**
+
+- **这是什么**：当前准确的描述
+- **需求**：已验证的、活跃的、超出范围的
+- **关键决策**：完整的决策日志及结果
+- **约束**：实现的硬性限制
+</step>
+
+<step name="check_incomplete_work">
+查找需要关注的未完成工作：
+
+```bash
+# 检查 continue-here 文件（计划中途恢复）
+ls .planning/phases/*/.continue-here*.md 2>/dev/null
+
+# 检查没有摘要的计划（未完成的执行）
+for plan in .planning/phases/*/*-PLAN.md; do
+  summary="${plan/PLAN/SUMMARY}"
+  [ ! -f "$summary" ] && echo "Incomplete: $plan"
+done 2>/dev/null
+
+# 检查中断的 Agent（使用 init 中的 has_interrupted_agent 和 interrupted_agent_id）
+if [ "$has_interrupted_agent" = "true" ]; then
+  echo "Interrupted agent: $interrupted_agent_id"
+fi
+```
+
+**如果存在 .continue-here 文件：**
+
+- 这是计划中途的恢复点
+- 读取文件获取具体的恢复上下文
+- 标记："发现计划中途检查点"
+
+**如果存在没有 SUMMARY 的 PLAN：**
+
+- 执行已开始但未完成
+- 标记："发现未完成的计划执行"
+
+**如果发现中断的 Agent：**
+
+- 子 Agent 已生成但会话在完成前结束
+- 读取 agent-history.json 获取任务详情
+- 标记："发现中断的 Agent"
+</step>
+
+<step name="present_status">
+向用户展示完整的项目状态：
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  项目状态                                                     ║
+╠══════════════════════════════════════════════════════════════╣
+║  构建中：[PROJECT.md "这是什么"的一句话描述]                    ║
+║                                                               ║
+║  阶段：[X] / [Y] - [阶段名称]                                 ║
+║  计划：[A] / [B] - [状态]                                     ║
+║  进度：[██████░░░░] XX%                                       ║
+║                                                               ║
+║  最近活动：[日期] - [做了什么]                                  ║
+╚══════════════════════════════════════════════════════════════╝
+
+[如果发现未完成的工作：]
+⚠️  检测到未完成的工作：
+    - [.continue-here 文件或未完成的计划]
+
+[如果发现中断的 Agent：]
+⚠️  检测到中断的 Agent：
+    Agent ID：[id]
+    任务：[来自 agent-history.json 的任务描述]
+    中断时间：[时间戳]
+
+    恢复方式：Task 工具（带 Agent ID 的 resume 参数）
+
+[如果有待办事项：]
+📋 [N] 个待办事项 — /specops:check-todos 查看
+
+[如果有阻塞项：]
+⚠️  遗留关注点：
+    - [阻塞项 1]
+    - [阻塞项 2]
+
+[如果对齐状态不是 ✓：]
+⚠️  简要对齐：[状态] - [评估]
+```
+</step>
+
+<step name="determine_next_action">
+根据项目状态确定最合理的下一步操作：
+
+**如果存在中断的 Agent：**
+→ 主要：恢复中断的 Agent（Task 工具带 resume 参数）
+→ 选项：重新开始（放弃 Agent 工作）
+
+**如果存在 .continue-here 文件：**
+→ 主要：从检查点恢复
+→ 选项：在当前计划上重新开始
+
+**如果有未完成的计划（PLAN 没有 SUMMARY）：**
+→ 主要：完成未完成的计划
+→ 选项：放弃并继续
+
+**如果阶段进行中，所有计划已完成：**
+→ 主要：过渡到下一阶段
+→ 选项：审查已完成的工作
+
+**如果阶段准备规划：**
+→ 检查此阶段是否存在 CONTEXT.md：
+
+- 如果 CONTEXT.md 缺失：
+  → 主要：讨论阶段愿景（用户如何想象它的运作方式）
+  → 次要：直接规划（跳过上下文收集）
+- 如果 CONTEXT.md 存在：
+  → 主要：规划阶段
+  → 选项：审查路线图
+
+**如果阶段准备执行：**
+→ 主要：执行下一个计划
+→ 选项：先审查计划
+</step>
+
+<step name="offer_options">
+根据项目状态展示上下文相关的选项：
+
+```
+你想做什么？
+
+[基于状态的主要操作——例如：]
+1. 恢复中断的 Agent [如果发现中断的 Agent]
+   或
+1. 执行阶段（/specops:execute-phase {phase}）
+   或
+1. 讨论阶段 3 上下文（/specops:discuss-phase 3）[如果 CONTEXT.md 缺失]
+   或
+1. 规划阶段 3（/specops:plan-phase 3）[如果 CONTEXT.md 存在或讨论选项被拒绝]
+
+[次要选项：]
+2. 审查当前阶段状态
+3. 查看待办事项（[N] 个待处理）
+4. 审查简要对齐
+5. 其他
+```
+
+**注意：** 提供阶段规划选项时，先检查 CONTEXT.md 是否存在：
+
+```bash
+ls .planning/phases/XX-name/*-CONTEXT.md 2>/dev/null
+```
+
+如果缺失，建议先 discuss-phase 再 plan。如果存在，直接提供 plan。
+
+等待用户选择。
+</step>
+
+<step name="route_to_workflow">
+根据用户选择路由到相应的工作流：
+
+- **执行计划** → 显示用户清除后运行的命令：
+  ```
+  ---
+
+  ## ▶ 下一步
+
+  **{phase}-{plan}：[计划名称]** — [PLAN.md 中的目标]
+
+  `/specops:execute-phase {phase}`
+
+  <sub>先 `/clear` → 全新上下文窗口</sub>
+
+  ---
+  ```
+- **规划阶段** → 显示用户清除后运行的命令：
+  ```
+  ---
+
+  ## ▶ 下一步
+
+  **阶段 [N]：[名称]** — [ROADMAP.md 中的目标]
+
+  `/specops:plan-phase [阶段编号]`
+
+  <sub>先 `/clear` → 全新上下文窗口</sub>
+
+  ---
+
+  **其他可用操作：**
+  - `/specops:discuss-phase [N]` — 先收集上下文
+  - `/specops:research-phase [N]` — 调查未知项
+
+  ---
+  ```
+- **过渡** → ./transition.md
+- **查看待办** → 读取 .planning/todos/pending/，展示摘要
+- **审查对齐** → 读取 PROJECT.md，与当前状态比较
+- **其他** → 询问需要什么
+</step>
+
+<step name="update_session">
+在继续到路由的工作流之前，更新会话连续性：
+
+更新 STATE.md：
+
+```markdown
+## Session Continuity
+
+Last session: [now]
+Stopped at: Session resumed, proceeding to [action]
+Resume file: [updated if applicable]
+```
+
+这确保如果会话意外结束，下次恢复时知道状态。
+</step>
+
+</process>
+
+<reconstruction>
+如果 STATE.md 缺失但其他产物存在：
+
+"STATE.md 缺失。正在从产物重建……"
+
+1. 读取 PROJECT.md → 提取"这是什么"和核心价值
+2. 读取 ROADMAP.md → 确定阶段，找到当前位置
+3. 扫描 \*-SUMMARY.md 文件 → 提取决策、关注点
+4. 统计 .planning/todos/pending/ 中的待办事项
+5. 检查 .continue-here 文件 → 会话连续性
+
+重建并写入 STATE.md，然后正常继续。
+
+这处理以下情况：
+
+- 项目早于 STATE.md 引入
+- 文件被意外删除
+- 克隆仓库时没有完整的 .planning/ 状态
+</reconstruction>
+
+<quick_resume>
+如果用户说"继续"或"开始"：
+- 静默加载状态
+- 确定主要操作
+- 立即执行，不展示选项
+
+"从 [状态] 继续……[操作]"
+</quick_resume>
+
+<success_criteria>
+恢复完成的标志：
+
+- [ ] STATE.md 已加载（或已重建）
+- [ ] 已检测并标记未完成的工作
+- [ ] 已向用户展示清晰的状态
+- [ ] 已提供上下文相关的下一步操作
+- [ ] 用户清楚项目当前的位置
+- [ ] 会话连续性已更新
+</success_criteria>

package/.opencode/workflows/set-profile.md

@@ -0,0 +1,80 @@
+<purpose>
+切换 SpecOps Agent 使用的模型配置。控制每个 Agent 使用哪个 Claude 模型，在质量和 token 消耗之间取得平衡。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="validate">
+验证参数：
+
+```
+if $ARGUMENTS.profile not in ["quality", "balanced", "budget"]:
+  Error: Invalid profile "$ARGUMENTS.profile"
+  Valid profiles: quality, balanced, budget
+  EXIT
+```
+</step>
+
+<step name="ensure_and_load_config">
+确保配置存在并加载当前状态：
+
+```bash
+node .opencode/bin/specops-tools.cjs config-ensure-section
+INIT=$(node .opencode/bin/specops-tools.cjs state load)
+```
+
+如果 `.planning/config.json` 不存在，则使用默认值创建，并加载当前配置。
+</step>
+
+<step name="update_config">
+从 state load 或直接读取当前配置：
+
+更新 `model_profile` 字段：
+```json
+{
+  "model_profile": "$ARGUMENTS.profile"
+}
+```
+
+将更新后的配置写回 `.planning/config.json`。
+</step>
+
+<step name="confirm">
+显示确认信息及所选配置的模型表：
+
+```
+✓ Model profile set to: $ARGUMENTS.profile
+
+Agents will now use:
+
+[Show table from MODEL_PROFILES in specops-tools.cjs for selected profile]
+
+Example:
+| Agent | Model |
+|-------|-------|
+| specops-planner | opus |
+| specops-executor | sonnet |
+| specops-verifier | haiku |
+| ... | ... |
+
+Next spawned agents will use the new profile.
+```
+
+配置名称映射：
+- quality：使用 MODEL_PROFILES 中的 "quality" 列
+- balanced：使用 MODEL_PROFILES 中的 "balanced" 列
+- budget：使用 MODEL_PROFILES 中的 "budget" 列
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] 参数已验证
+- [ ] 配置文件已确认存在
+- [ ] 配置已更新为新的 model_profile
+- [ ] 已显示确认信息及模型表
+</success_criteria>

package/.opencode/workflows/settings.md

@@ -0,0 +1,213 @@
+<purpose>
+通过多问题提示交互式配置 SpecOps 工作流 Agent（研究、计划检查、验证器）和模型配置选择。将用户偏好更新到 .planning/config.json。可选择将设置保存为全局默认值（.opencode/defaults.json）供未来项目使用。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="ensure_and_load_config">
+确保配置存在并加载当前状态：
+
+```bash
+node .opencode/bin/specops-tools.cjs config-ensure-section
+INIT=$(node .opencode/bin/specops-tools.cjs state load)
+```
+
+如果 `.planning/config.json` 不存在则创建默认配置，并加载当前配置值。
+</step>
+
+<step name="read_current">
+```bash
+cat .planning/config.json
+```
+
+解析当前值（如果不存在则默认为 `true`）：
+- `workflow.research` — 在 plan-phase 期间生成研究员
+- `workflow.plan_check` — 在 plan-phase 期间生成计划检查器
+- `workflow.verifier` — 在 execute-phase 期间生成验证器
+- `workflow.nyquist_validation` — 在 plan-phase 期间进行验证架构研究
+- `model_profile` — 每个 Agent 使用的模型（默认：`balanced`）
+- `git.branching_strategy` — 分支策略（默认：`"none"`）
+</step>
+
+<step name="present_settings">
+使用 AskUserQuestion 并预选当前值：
+
+```
+AskUserQuestion([
+  {
+    question: "Agent 使用哪个模型配置？",
+    header: "模型",
+    multiSelect: false,
+    options: [
+      { label: "Quality", description: "除验证外全部使用 Opus（最高成本）" },
+      { label: "Balanced（推荐）", description: "规划用 Opus，执行/验证用 Sonnet" },
+      { label: "Budget", description: "编写用 Sonnet，研究/验证用 Haiku（最低成本）" }
+    ]
+  },
+  {
+    question: "是否生成计划研究员？（在规划前研究领域知识）",
+    header: "研究",
+    multiSelect: false,
+    options: [
+      { label: "是", description: "在规划前研究阶段目标" },
+      { label: "否", description: "跳过研究，直接规划" }
+    ]
+  },
+  {
+    question: "是否生成计划检查器？（在执行前验证计划）",
+    header: "计划检查",
+    multiSelect: false,
+    options: [
+      { label: "是", description: "验证计划是否满足阶段目标" },
+      { label: "否", description: "跳过计划验证" }
+    ]
+  },
+  {
+    question: "是否生成执行验证器？（验证阶段完成情况）",
+    header: "验证器",
+    multiSelect: false,
+    options: [
+      { label: "是", description: "执行后验证必要项" },
+      { label: "否", description: "跳过执行后验证" }
+    ]
+  },
+  {
+    question: "是否自动推进流水线？（discuss → plan → execute 自动执行）",
+    header: "自动推进",
+    multiSelect: false,
+    options: [
+      { label: "否（推荐）", description: "阶段间手动 /clear + 粘贴" },
+      { label: "是", description: "通过 Task() 子 Agent 链式执行（相同隔离性）" }
+    ]
+  },
+  {
+    question: "是否启用 Nyquist 验证？（在规划期间研究测试覆盖率）",
+    header: "Nyquist",
+    multiSelect: false,
+    options: [
+      { label: "是（推荐）", description: "在 plan-phase 期间研究自动化测试覆盖率。为计划添加验证要求。如果任务缺少自动化验证则阻止审批。" },
+      { label: "否", description: "跳过验证研究。适用于快速原型或无测试阶段。" }
+    ]
+  },
+  {
+    question: "Git 分支策略？",
+    header: "分支",
+    multiSelect: false,
+    options: [
+      { label: "无（推荐）", description: "直接提交到当前分支" },
+      { label: "按阶段", description: "为每个阶段创建分支（specops/phase-{N}-{name}）" },
+      { label: "按里程碑", description: "为整个里程碑创建分支（specops/{version}-{name}）" }
+    ]
+  }
+])
+```
+</step>
+
+<step name="update_config">
+将新设置合并到现有 config.json 中：
+
+```json
+{
+  ...existing_config,
+  "model_profile": "quality" | "balanced" | "budget",
+  "workflow": {
+    "research": true/false,
+    "plan_check": true/false,
+    "verifier": true/false,
+    "auto_advance": true/false,
+    "nyquist_validation": true/false
+  },
+  "git": {
+    "branching_strategy": "none" | "phase" | "milestone"
+  }
+}
+```
+
+将更新后的配置写入 `.planning/config.json`。
+</step>
+
+<step name="save_as_defaults">
+询问是否将这些设置保存为未来项目的全局默认值：
+
+```
+AskUserQuestion([
+  {
+    question: "是否将这些设置保存为所有新项目的默认值？",
+    header: "默认值",
+    multiSelect: false,
+    options: [
+      { label: "是", description: "新项目将使用这些设置启动（保存到 .opencode/defaults.json）" },
+      { label: "否", description: "仅应用于当前项目" }
+    ]
+  }
+])
+```
+
+如果选择"是"：将相同的配置对象（去除项目特定字段如 `brave_search`）写入 `.opencode/defaults.json`：
+
+```bash
+mkdir -p .opencode
+```
+
+写入 `.opencode/defaults.json`：
+```json
+{
+  "mode": <当前值>,
+  "depth": <当前值>,
+  "model_profile": <当前值>,
+  "commit_docs": <当前值>,
+  "parallelization": <当前值>,
+  "branching_strategy": <当前值>,
+  "workflow": {
+    "research": <当前值>,
+    "plan_check": <当前值>,
+    "verifier": <当前值>,
+    "auto_advance": <当前值>,
+    "nyquist_validation": <当前值>
+  }
+}
+```
+</step>
+
+<step name="confirm">
+显示：
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 设置已更新
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| 设置项               | 值 |
+|----------------------|-------|
+| 模型配置             | {quality/balanced/budget} |
+| 计划研究员           | {开启/关闭} |
+| 计划检查器           | {开启/关闭} |
+| 执行验证器           | {开启/关闭} |
+| 自动推进             | {开启/关闭} |
+| Nyquist 验证         | {开启/关闭} |
+| Git 分支             | {无/按阶段/按里程碑} |
+| 已保存为默认值       | {是/否} |
+
+这些设置将应用于后续的 /specops:plan-phase 和 /specops:execute-phase 运行。
+
+快捷命令：
+- /specops:set-profile <profile> — 切换模型配置
+- /specops:plan-phase --research — 强制启用研究
+- /specops:plan-phase --skip-research — 跳过研究
+- /specops:plan-phase --skip-verify — 跳过计划检查
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] 已读取当前配置
+- [ ] 向用户展示了 7 项设置（配置 + 5 个工作流开关 + git 分支）
+- [ ] 已更新配置的 model_profile、workflow 和 git 部分
+- [ ] 已提供保存为全局默认值的选项（.opencode/defaults.json）
+- [ ] 已向用户确认变更
+</success_criteria>