specops 0.2.4 → 0.3.0

package/.opencode/workflows/quick.md

@@ -0,0 +1,453 @@
+<purpose>
+使用 SpecOps 保证（原子提交、STATE.md 追踪）执行小型临时任务。快速模式生成 specops-planner（快速模式）+ specops-executor，在 `.planning/quick/` 中追踪任务，并更新 STATE.md 的"Quick Tasks Completed"表。
+
+使用 `--full` 标志：启用计划检查（最多 2 次迭代）和执行后验证，在不需要完整里程碑仪式的情况下提供质量保证。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+**步骤 1：解析参数并获取任务描述**
+
+解析 `$ARGUMENTS`：
+- `--full` 标志 → 存储为 `$FULL_MODE`（true/false）
+- 剩余文本 → 如果非空则用作 `$DESCRIPTION`
+
+如果解析后 `$DESCRIPTION` 为空，交互式提示用户：
+
+```
+AskUserQuestion(
+  header: "快速任务",
+  question: "你想做什么？",
+  followUp: null
+)
+```
+
+将回复存储为 `$DESCRIPTION`。
+
+如果仍为空，重新提示："请提供任务描述。"
+
+如果 `$FULL_MODE`：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 快速任务（完整模式）
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 计划检查 + 验证已启用
+```
+
+---
+
+**步骤 2：初始化**
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init quick "$DESCRIPTION")
+```
+
+解析 JSON 获取：`planner_model`、`executor_model`、`checker_model`、`verifier_model`、`commit_docs`、`next_num`、`slug`、`date`、`timestamp`、`quick_dir`、`task_dir`、`roadmap_exists`、`planning_exists`。
+
+**如果 `roadmap_exists` 为 false：** 错误——快速模式需要一个带 ROADMAP.md 的活跃项目。请先运行 `/specops:new-project`。
+
+快速任务可以在阶段中途运行——验证只检查 ROADMAP.md 是否存在，不检查阶段状态。
+
+---
+
+**步骤 3：创建任务目录**
+
+```bash
+mkdir -p "${task_dir}"
+```
+
+---
+
+**步骤 4：创建快速任务目录**
+
+为此快速任务创建目录：
+
+```bash
+QUICK_DIR=".planning/quick/${next_num}-${slug}"
+mkdir -p "$QUICK_DIR"
+```
+
+向用户报告：
+```
+正在创建快速任务 ${next_num}：${DESCRIPTION}
+目录：${QUICK_DIR}
+```
+
+存储 `$QUICK_DIR` 供编排使用。
+
+---
+
+**步骤 5：生成规划器（快速模式）**
+
+**如果 `$FULL_MODE`：** 使用 `quick-full` 模式，约束更严格。
+
+**如果非 `$FULL_MODE`：** 使用标准 `quick` 模式。
+
+```
+Task(
+  prompt="
+<planning_context>
+
+**Mode:** ${FULL_MODE ? 'quick-full' : 'quick'}
+**Directory:** ${QUICK_DIR}
+**Description:** ${DESCRIPTION}
+
+<files_to_read>
+- .planning/STATE.md (Project State)
+- ./CLAUDE.md (if exists — follow project-specific guidelines)
+</files_to_read>
+
+**Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules
+
+</planning_context>
+
+<constraints>
+- Create a SINGLE plan with 1-3 focused tasks
+- Quick tasks should be atomic and self-contained
+- No research phase
+${FULL_MODE ? '- Target ~40% context usage (structured for verification)' : '- Target ~30% context usage (simple, focused)'}
+${FULL_MODE ? '- MUST generate `must_haves` in plan frontmatter (truths, artifacts, key_links)' : ''}
+${FULL_MODE ? '- Each task MUST have `files`, `action`, `verify`, `done` fields' : ''}
+</constraints>
+
+<output>
+Write plan to: ${QUICK_DIR}/${next_num}-PLAN.md
+Return: ## PLANNING COMPLETE with plan path
+</output>
+",
+  subagent_type="specops-planner",
+  model="{planner_model}",
+  description="Quick plan: ${DESCRIPTION}"
+)
+```
+
+规划器返回后：
+1. 验证计划存在于 `${QUICK_DIR}/${next_num}-PLAN.md`
+2. 提取计划数量（快速任务通常为 1）
+3. 报告："计划已创建：${QUICK_DIR}/${next_num}-PLAN.md"
+
+如果未找到计划，报错："规划器未能创建 ${next_num}-PLAN.md"
+
+---
+
+**步骤 5.5：计划检查循环（仅在 `$FULL_MODE` 时）**
+
+如果非 `$FULL_MODE` 则完全跳过此步骤。
+
+显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 检查计划
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 生成计划检查器……
+```
+
+检查器提示：
+
+```markdown
+<verification_context>
+**Mode:** quick-full
+**Task Description:** ${DESCRIPTION}
+
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Plan to verify)
+</files_to_read>
+
+**Scope:** This is a quick task, not a full phase. Skip checks that require a ROADMAP phase goal.
+</verification_context>
+
+<check_dimensions>
+- Requirement coverage: Does the plan address the task description?
+- Task completeness: Do tasks have files, action, verify, done fields?
+- Key links: Are referenced files real?
+- Scope sanity: Is this appropriately sized for a quick task (1-3 tasks)?
+- must_haves derivation: Are must_haves traceable to the task description?
+
+Skip: context compliance (no CONTEXT.md), cross-plan deps (single plan), ROADMAP alignment
+</check_dimensions>
+
+<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="Check quick plan: ${DESCRIPTION}"
+)
+```
+
+**处理检查器返回：**
+
+- **`## VERIFICATION PASSED`：** 显示确认，继续到步骤 6。
+- **`## ISSUES FOUND`：** 显示问题，检查迭代次数，进入修订循环。
+
+**修订循环（最多 2 次迭代）：**
+
+追踪 `iteration_count`（初始计划 + 检查后从 1 开始）。
+
+**如果 iteration_count < 2：**
+
+显示：`发回规划器修订……（迭代 ${N}/2）`
+
+修订提示：
+
+```markdown
+<revision_context>
+**Mode:** quick-full (revision)
+
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Existing plan)
+</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 quick plan: ${DESCRIPTION}"
+)
+```
+
+规划器返回后 → 再次生成检查器，递增 iteration_count。
+
+**如果 iteration_count >= 2：**
+
+显示：`已达最大迭代次数。剩余 ${N} 个问题：` + 问题列表
+
+提供选项：1) 强制继续，2) 中止
+
+---
+
+**步骤 6：生成执行器**
+
+使用计划引用生成 specops-executor：
+
+```
+Task(
+  prompt="
+Execute quick task ${next_num}.
+
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Plan)
+- .planning/STATE.md (Project state)
+- ./CLAUDE.md (Project instructions, if exists)
+- .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
+</files_to_read>
+
+<constraints>
+- Execute all tasks in the plan
+- Commit each task atomically
+- Create summary at: ${QUICK_DIR}/${next_num}-SUMMARY.md
+- Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
+</constraints>
+",
+  subagent_type="specops-executor",
+  model="{executor_model}",
+  description="Execute: ${DESCRIPTION}"
+)
+```
+
+执行器返回后：
+1. 验证摘要存在于 `${QUICK_DIR}/${next_num}-SUMMARY.md`
+2. 从执行器输出提取提交哈希
+3. 报告完成状态
+
+**已知 Claude Code bug（classifyHandoffIfNeeded）：** 如果执行器报告"失败"且错误为 `classifyHandoffIfNeeded is not defined`，这是 Claude Code 运行时 bug——不是真正的失败。检查摘要文件是否存在以及 git log 是否显示提交。如果是，视为成功。
+
+如果未找到摘要，报错："执行器未能创建 ${next_num}-SUMMARY.md"
+
+注意：对于产生多个计划的快速任务（罕见），按 execute-phase 模式并行波次生成执行器。
+
+---
+
+**步骤 6.5：验证（仅在 `$FULL_MODE` 时）**
+
+如果非 `$FULL_MODE` 则完全跳过此步骤。
+
+显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 验证结果
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 生成验证器……
+```
+
+```
+Task(
+  prompt="Verify quick task goal achievement.
+Task directory: ${QUICK_DIR}
+Task goal: ${DESCRIPTION}
+
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Plan)
+</files_to_read>
+
+Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${next_num}-VERIFICATION.md.",
+  subagent_type="specops-verifier",
+  model="{verifier_model}",
+  description="Verify: ${DESCRIPTION}"
+)
+```
+
+读取验证状态：
+```bash
+grep "^status:" "${QUICK_DIR}/${next_num}-VERIFICATION.md" | cut -d: -f2 | tr -d ' '
+```
+
+存储为 `$VERIFICATION_STATUS`。
+
+| 状态 | 操作 |
+|------|------|
+| `passed` | 存储 `$VERIFICATION_STATUS = "Verified"`，继续到步骤 7 |
+| `human_needed` | 显示需要手动检查的项目，存储 `$VERIFICATION_STATUS = "Needs Review"`，继续 |
+| `gaps_found` | 显示缺口摘要，提供选项：1) 重新运行执行器修复缺口，2) 按现状接受。存储 `$VERIFICATION_STATUS = "Gaps"` |
+
+---
+
+**步骤 7：更新 STATE.md**
+
+用快速任务完成记录更新 STATE.md。
+
+**7a. 检查"Quick Tasks Completed"部分是否存在：**
+
+读取 STATE.md 并检查 `### Quick Tasks Completed` 部分。
+
+**7b. 如果部分不存在，创建它：**
+
+在 `### Blockers/Concerns` 部分之后插入：
+
+**如果 `$FULL_MODE`：**
+```markdown
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Status | Directory |
+|---|-------------|------|--------|--------|-----------|
+```
+
+**如果非 `$FULL_MODE`：**
+```markdown
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+```
+
+**注意：** 如果表格已存在，匹配其现有列格式。如果向已有不带 Status 列的快速任务的项目添加 `--full`，在表头和分隔行添加 Status 列，并为新行的前置行留空 Status。
+
+**7c. 向表格追加新行：**
+
+使用 init 中的 `date`：
+
+**如果 `$FULL_MODE`（或表格有 Status 列）：**
+```markdown
+| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
+```
+
+**如果非 `$FULL_MODE`（且表格无 Status 列）：**
+```markdown
+| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
+```
+
+**7d. 更新"Last activity"行：**
+
+使用 init 中的 `date`：
+```
+Last activity: ${date} - Completed quick task ${next_num}: ${DESCRIPTION}
+```
+
+使用 Edit 工具原子化地进行这些更改
+
+---
+
+**步骤 8：最终提交和完成**
+
+暂存并提交快速任务产物：
+
+构建文件列表：
+- `${QUICK_DIR}/${next_num}-PLAN.md`
+- `${QUICK_DIR}/${next_num}-SUMMARY.md`
+- `.planning/STATE.md`
+- 如果 `$FULL_MODE` 且验证文件存在：`${QUICK_DIR}/${next_num}-VERIFICATION.md`
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs(quick-${next_num}): ${DESCRIPTION}" --files ${file_list}
+```
+
+获取最终提交哈希：
+```bash
+commit_hash=$(git rev-parse --short HEAD)
+```
+
+显示完成输出：
+
+**如果 `$FULL_MODE`：**
+```
+---
+
+SpecOps > 快速任务完成（完整模式）
+
+快速任务 ${next_num}：${DESCRIPTION}
+
+摘要：${QUICK_DIR}/${next_num}-SUMMARY.md
+验证：${QUICK_DIR}/${next_num}-VERIFICATION.md（${VERIFICATION_STATUS}）
+提交：${commit_hash}
+
+---
+
+准备好下一个任务：/specops:quick
+```
+
+**如果非 `$FULL_MODE`：**
+```
+---
+
+SpecOps > 快速任务完成
+
+快速任务 ${next_num}：${DESCRIPTION}
+
+摘要：${QUICK_DIR}/${next_num}-SUMMARY.md
+提交：${commit_hash}
+
+---
+
+准备好下一个任务：/specops:quick
+```
+
+</process>
+
+<success_criteria>
+- [ ] ROADMAP.md 验证通过
+- [ ] 用户提供了任务描述
+- [ ] 存在时已从参数解析 `--full` 标志
+- [ ] 已生成 slug（小写、连字符、最多 40 字符）
+- [ ] 已计算下一个编号（001、002、003……）
+- [ ] 已在 `.planning/quick/NNN-slug/` 创建目录
+- [ ] 规划器已创建 `${next_num}-PLAN.md`
+- [ ] （--full）计划检查器已验证计划，修订循环上限为 2
+- [ ] 执行器已创建 `${next_num}-SUMMARY.md`
+- [ ] （--full）验证器已创建 `${next_num}-VERIFICATION.md`
+- [ ] STATE.md 已更新快速任务行（--full 时包含 Status 列）
+- [ ] 产物已提交
+</success_criteria>

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

@@ -0,0 +1,154 @@
+<purpose>
+从项目路线图中移除一个未开始的未来阶段，删除其目录，重新编号所有后续阶段以保持干净的线性序列，并提交更改。git 提交记录作为移除的历史记录。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+解析命令参数：
+- 参数是要移除的阶段编号（整数或小数）
+- 示例：`/specops:remove-phase 17` → phase = 17
+- 示例：`/specops:remove-phase 16.1` → phase = 16.1
+
+如果未提供参数：
+
+```
+ERROR: Phase number required
+Usage: /specops:remove-phase <phase-number>
+Example: /specops:remove-phase 17
+```
+
+退出。
+</step>
+
+<step name="init_context">
+加载阶段操作上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "${target}")
+```
+
+提取：`phase_found`、`phase_dir`、`phase_number`、`commit_docs`、`roadmap_exists`。
+
+同时读取 STATE.md 和 ROADMAP.md 内容以解析当前位置。
+</step>
+
+<step name="validate_future_phase">
+验证该阶段是未来阶段（未开始）：
+
+1. 将目标阶段与 STATE.md 中的当前阶段进行比较
+2. 目标必须 > 当前阶段编号
+
+如果 target <= 当前阶段：
+
+```
+ERROR: Cannot remove Phase {target}
+
+Only future phases can be removed:
+- Current phase: {current}
+- Phase {target} is current or completed
+
+To abandon current work, use /specops:pause-work instead.
+```
+
+退出。
+</step>
+
+<step name="confirm_removal">
+展示移除摘要并确认：
+
+```
+Removing Phase {target}: {Name}
+
+This will:
+- Delete: .planning/phases/{target}-{slug}/
+- Renumber all subsequent phases
+- Update: ROADMAP.md, STATE.md
+
+Proceed? (y/n)
+```
+
+等待确认。
+</step>
+
+<step name="execute_removal">
+**将整个移除操作委托给 specops-tools：**
+
+```bash
+RESULT=$(node .opencode/bin/specops-tools.cjs phase remove "${target}")
+```
+
+如果该阶段有已执行的计划（SUMMARY.md 文件），specops-tools 会报错。仅在用户确认后使用 `--force`：
+
+```bash
+RESULT=$(node .opencode/bin/specops-tools.cjs phase remove "${target}" --force)
+```
+
+CLI 处理以下操作：
+- 删除阶段目录
+- 重新编号所有后续目录（按逆序避免冲突）
+- 重命名重新编号目录中的所有文件（PLAN.md、SUMMARY.md 等）
+- 更新 ROADMAP.md（移除部分、重新编号所有阶段引用、更新依赖）
+- 更新 STATE.md（递减阶段计数）
+
+从结果中提取：`removed`、`directory_deleted`、`renamed_directories`、`renamed_files`、`roadmap_updated`、`state_updated`。
+</step>
+
+<step name="commit">
+暂存并提交移除：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
+```
+
+提交消息保留了被移除内容的历史记录。
+</step>
+
+<step name="completion">
+展示完成摘要：
+
+```
+Phase {target} ({original-name}) removed.
+
+Changes:
+- Deleted: .planning/phases/{target}-{slug}/
+- Renumbered: {N} directories and {M} files
+- Updated: ROADMAP.md, STATE.md
+- Committed: chore: remove phase {target} ({original-name})
+
+---
+
+## What's Next
+
+Would you like to:
+- `/specops:progress` — see updated roadmap status
+- Continue with current phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- 不要在没有 --force 的情况下移除已完成的阶段（有 SUMMARY.md 文件）
+- 不要移除当前或过去的阶段
+- 不要手动重新编号 — 使用 `specops-tools phase remove` 处理所有重新编号
+- 不要在 STATE.md 中添加"已移除阶段"备注 — git 提交就是记录
+- 不要修改已完成阶段的目录
+</anti_patterns>
+
+<success_criteria>
+阶段移除完成的条件：
+
+- [ ] 目标阶段已验证为未来/未开始状态
+- [ ] `specops-tools phase remove` 执行成功
+- [ ] 更改已提交并附有描述性消息
+- [ ] 用户已被告知更改内容
+</success_criteria>

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

@@ -0,0 +1,73 @@
+<purpose>
+研究如何实现某个阶段。使用阶段上下文生成 specops-phase-researcher。
+
+独立的研究命令。大多数工作流中，建议使用 `/specops:plan-phase`，它会自动集成研究流程。
+</purpose>
+
+<process>
+
+## Step 0: 解析模型配置
+
+@.opencode/references/model-profile-resolution.md
+
+解析以下模型：
+- `specops-phase-researcher`
+
+## Step 1: 规范化并验证阶段
+
+@.opencode/references/phase-argument-parsing.md
+
+```bash
+PHASE_INFO=$(node .opencode/bin/specops-tools.cjs roadmap get-phase "${PHASE}")
+```
+
+如果 `found` 为 false：报错并退出。
+
+## Step 2: 检查已有研究
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+```
+
+如果已存在：提供更新/查看/跳过选项。
+
+## Step 3: 收集阶段上下文
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "${PHASE}")
+# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path
+```
+
+## Step 4: 生成研究 Agent
+
+```
+Task(
+  prompt="<objective>
+Research implementation approach for Phase {phase}: {name}
+</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: {description}
+</additional_context>
+
+<output>
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+</output>",
+  subagent_type="specops-phase-researcher",
+  model="{researcher_model}"
+)
+```
+
+## Step 5: 处理返回结果
+
+- `## RESEARCH COMPLETE` — 显示摘要，提供选项：规划/深入研究/审查/完成
+- `## CHECKPOINT REACHED` — 展示给用户，生成后续任务
+- `## RESEARCH INCONCLUSIVE` — 显示尝试记录，提供选项：补充上下文/尝试其他模式/手动处理
+
+</process>