specops 0.2.4 → 0.3.0

package/commands/specops/map-codebase.md

@@ -0,0 +1,71 @@
+---
+name: specops:map-codebase
+description: 使用并行映射代理分析代码库，生成 .planning/codebase/ 文档
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+使用并行的 specops-codebase-mapper 代理分析现有代码库，生成结构化的代码库文档。
+
+每个映射代理探索一个焦点领域并**直接将文档写入** `.planning/codebase/`。编排器只接收确认信息，保持上下文使用最小化。
+
+输出：.planning/codebase/ 文件夹，包含 7 个关于代码库状态的结构化文档。
+</objective>
+
+<execution_context>
+@.opencode/workflows/map-codebase.md
+</execution_context>
+
+<context>
+焦点领域：$ARGUMENTS（可选 - 如果提供，告诉代理聚焦于特定子系统）
+
+**如果存在则加载项目状态：**
+检查 .planning/STATE.md - 如果项目已初始化则加载上下文
+
+**此命令可以运行于：**
+- `/specops:new-project` 之前（棕地代码库）- 先创建代码库映射
+- `/specops:new-project` 之后（绿地代码库）- 随代码演进更新代码库映射
+- 任何时候刷新代码库理解
+</context>
+
+<when_to_use>
+**使用 map-codebase 的场景：**
+- 初始化前的棕地项目（先理解现有代码）
+- 重大变更后刷新代码库映射
+- 入门不熟悉的代码库
+- 重大重构前（理解当前状态）
+- 当 STATE.md 引用过时的代码库信息时
+
+**跳过 map-codebase 的场景：**
+- 还没有代码的绿地项目（没什么可映射的）
+- 简单的代码库（<5 个文件）
+</when_to_use>
+
+<process>
+1. 检查 .planning/codebase/ 是否已存在（提供刷新或跳过选项）
+2. 创建 .planning/codebase/ 目录结构
+3. 生成 4 个并行的 specops-codebase-mapper 代理：
+   - 代理 1：tech 焦点 → 写入 STACK.md、INTEGRATIONS.md
+   - 代理 2：arch 焦点 → 写入 ARCHITECTURE.md、STRUCTURE.md
+   - 代理 3：quality 焦点 → 写入 CONVENTIONS.md、TESTING.md
+   - 代理 4：concerns 焦点 → 写入 CONCERNS.md
+4. 等待代理完成，收集确认（不是文档内容）
+5. 验证所有 7 个文档存在并统计行数
+6. 提交代码库映射
+7. 提供后续步骤（通常：/specops:new-project 或 /specops:plan-phase）
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ 目录已创建
+- [ ] 所有 7 个代码库文档已由映射代理写入
+- [ ] 文档遵循模板结构
+- [ ] 并行代理无错误完成
+- [ ] 用户知道后续步骤
+</success_criteria>

package/commands/specops/new-milestone.md

@@ -0,0 +1,44 @@
+---
+name: specops:new-milestone
+description: 开始新的里程碑周期——更新 PROJECT.md 并路由到需求定义
+argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+开始新的里程碑：提问 → 研究（可选）→ 需求 → 路线图。
+
+new-project 的棕地等价物。项目已存在，PROJECT.md 有历史记录。收集"下一步做什么"，更新 PROJECT.md，然后运行需求 → 路线图周期。
+
+**创建/更新：**
+- `.planning/PROJECT.md` — 更新为新里程碑目标
+- `.planning/research/` — 领域研究（可选，仅新功能）
+- `.planning/REQUIREMENTS.md` — 此里程碑的范围化需求
+- `.planning/ROADMAP.md` — 阶段结构（继续编号）
+- `.planning/STATE.md` — 为新里程碑重置
+
+**之后：** `/specops:plan-phase [N]` 开始执行。
+</objective>
+
+<execution_context>
+@.opencode/workflows/new-milestone.md
+@.opencode/references/questioning.md
+@.opencode/references/ui-brand.md
+@.opencode/templates/project.md
+@.opencode/templates/requirements.md
+</execution_context>
+
+<context>
+里程碑名称：$ARGUMENTS（可选 - 未提供时会提示）
+
+项目和里程碑上下文文件在工作流内部解析（`init new-milestone`），并通过 `<files_to_read>` 块委托给子代理。
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/new-milestone.md 中的 new-milestone 工作流。
+保留所有工作流门控（验证、提问、研究、需求、路线图审批、提交）。
+</process>

package/commands/specops/new-project.md

@@ -0,0 +1,42 @@
+---
+name: specops:new-project
+description: 通过深度上下文收集和 PROJECT.md 初始化新项目
+argument-hint: "[--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<context>
+**标志：**
+- `--auto` — 自动模式。配置问题之后，无需进一步交互即运行研究 → 需求 → 路线图。期望通过 @ 引用提供想法文档。
+</context>
+
+<objective>
+通过统一流程初始化新项目：提问 → 研究（可选）→ 需求 → 路线图。
+
+**创建：**
+- `.planning/PROJECT.md` — 项目上下文
+- `.planning/config.json` — 工作流偏好
+- `.planning/research/` — 领域研究（可选）
+- `.planning/REQUIREMENTS.md` — 范围化需求
+- `.planning/ROADMAP.md` — 阶段结构
+- `.planning/STATE.md` — 项目记忆
+
+**此命令之后：** 运行 `/specops:plan-phase 1` 开始执行。
+</objective>
+
+<execution_context>
+@.opencode/workflows/new-project.md
+@.opencode/references/questioning.md
+@.opencode/references/ui-brand.md
+@.opencode/templates/project.md
+@.opencode/templates/requirements.md
+</execution_context>
+
+<process>
+端到端执行 @.opencode/workflows/new-project.md 中的 new-project 工作流。
+保留所有工作流门控（验证、审批、提交、路由）。
+</process>

package/commands/specops/pause-work.md

@@ -0,0 +1,38 @@
+---
+name: specops:pause-work
+description: 在阶段中途暂停工作时创建上下文交接
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+创建 `.continue-here.md` 交接文件，以在会话间保留完整的工作状态。
+
+路由到 pause-work 工作流，该工作流处理：
+- 从最近文件检测当前阶段
+- 完整状态收集（位置、已完成工作、剩余工作、决策、阻塞项）
+- 创建包含所有上下文章节的交接文件
+- 作为 WIP 进行 Git 提交
+- 恢复说明
+</objective>
+
+<execution_context>
+@.opencode/workflows/pause-work.md
+</execution_context>
+
+<context>
+状态和阶段进度在工作流中通过定向读取收集。
+</context>
+
+<process>
+**遵循 pause-work 工作流**，来自 `@.opencode/workflows/pause-work.md`。
+
+该工作流处理所有逻辑，包括：
+1. 阶段目录检测
+2. 状态收集及用户澄清
+3. 带时间戳的交接文件写入
+4. Git 提交
+5. 确认及恢复说明
+</process>

package/commands/specops/plan-milestone-gaps.md

@@ -0,0 +1,34 @@
+---
+name: specops:plan-milestone-gaps
+description: 创建阶段以关闭里程碑审计中识别的所有缺口
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<objective>
+创建关闭 `/specops:audit-milestone` 识别的缺口所需的所有阶段。
+
+读取 MILESTONE-AUDIT.md，将缺口分组为逻辑阶段，在 ROADMAP.md 中创建阶段条目，并提供规划每个阶段的选项。
+
+一个命令创建所有修复阶段——无需为每个缺口手动执行 `/specops:add-phase`。
+</objective>
+
+<execution_context>
+@.opencode/workflows/plan-milestone-gaps.md
+</execution_context>
+
+<context>
+**审计结果：**
+Glob: .planning/v*-MILESTONE-AUDIT.md（使用最新的）
+
+原始意图和当前规划状态在工作流内部按需加载。
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/plan-milestone-gaps.md 中的 plan-milestone-gaps 工作流。
+保留所有工作流门控（审计加载、优先级排序、阶段分组、用户确认、路线图更新）。
+</process>

package/commands/specops/plan-phase.md

@@ -0,0 +1,45 @@
+---
+name: specops:plan-phase
+description: 创建带验证循环的详细阶段计划（PLAN.md）
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>]"
+agent: specops-planner
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - mcp__context7__*
+---
+<objective>
+为路线图阶段创建可执行的阶段提示（PLAN.md 文件），集成研究和验证。
+
+**默认流程：** 研究（如需要）→ 规划 → 验证 → 完成
+
+**编排器角色：** 解析参数，验证阶段，研究领域（除非跳过），生成 specops-planner，使用 specops-plan-checker 验证，迭代直到通过或达到最大迭代次数，展示结果。
+</objective>
+
+<execution_context>
+@.opencode/workflows/plan-phase.md
+@.opencode/references/ui-brand.md
+</execution_context>
+
+<context>
+阶段编号：$ARGUMENTS（可选——如果省略则自动检测下一个未规划的阶段）
+
+**标志：**
+- `--research` — 即使 RESEARCH.md 已存在也强制重新研究
+- `--skip-research` — 跳过研究，直接进入规划
+- `--gaps` — 缺口修复模式（读取 VERIFICATION.md，跳过研究）
+- `--skip-verify` — 跳过验证循环
+- `--prd <file>` — 使用 PRD/验收标准文件代替 discuss-phase。自动将需求解析为 CONTEXT.md。完全跳过 discuss-phase。
+
+在步骤 2 中标准化阶段输入，然后再进行任何目录查找。
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/plan-phase.md 中的 plan-phase 工作流。
+保留所有工作流门控（验证、研究、规划、验证循环、路由）。
+</process>

package/commands/specops/progress.md

@@ -0,0 +1,24 @@
+---
+name: specops:progress
+description: 检查项目进度，显示上下文，并路由到下一个操作（执行或规划）
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - SlashCommand
+---
+<objective>
+检查项目进度，总结最近的工作和接下来的内容，然后智能路由到下一个操作——执行现有计划或创建下一个计划。
+
+在继续工作之前提供态势感知。
+</objective>
+
+<execution_context>
+@.opencode/workflows/progress.md
+</execution_context>
+
+<process>
+端到端执行 @.opencode/workflows/progress.md 中的 progress 工作流。
+保留所有路由逻辑（路由 A 到 F）和边缘情况处理。
+</process>

package/commands/specops/quick.md

@@ -0,0 +1,41 @@
+---
+name: specops:quick
+description: 使用 SpecOps 保障执行快速任务（原子提交、状态追踪）但跳过可选 agent
+argument-hint: "[--full]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+执行小型临时任务，带有 SpecOps 保障（原子提交、STATE.md 追踪）。
+
+快速模式是相同系统的简短路径：
+- 生成 specops-planner（快速模式）+ specops-executor
+- 快速任务存放在 `.planning/quick/` 中，与规划阶段分开
+- 更新 STATE.md "快速任务完成" 表格（不是 ROADMAP.md）
+
+**默认：** 跳过研究、计划检查器、验证器。适用于你明确知道要做什么的场景。
+
+**`--full` 标志：** 启用计划检查（最多 2 次迭代）和执行后验证。适用于想要质量保障但不需要完整里程碑流程的场景。
+</objective>
+
+<execution_context>
+@.opencode/workflows/quick.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+上下文文件在工作流内部通过 `init quick` 解析，并通过 `<files_to_read>` 块委托。
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/quick.md 中的快速工作流。
+保留所有工作流门控（验证、任务描述、规划、执行、状态更新、提交）。
+</process>

package/commands/specops/reapply-patches.md

@@ -0,0 +1,111 @@
+---
+name: specops:reapply-patches
+description: 更新后重新应用本地修改
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+SpecOps 更新擦除并重新安装文件后，此命令将用户之前保存的本地修改合并回新版本。使用智能比较处理上游文件也发生变化的情况。
+</purpose>
+
+<process>
+
+## 步骤 1：检测备份的补丁
+
+检查本地补丁目录：
+
+```bash
+# 全局安装（路径在安装时模板化）
+PATCHES_DIR=~/.config/opencode/specops-local-patches
+# 本地安装回退
+if [ ! -d "$PATCHES_DIR" ]; then
+  PATCHES_DIR=./.opencode/specops-local-patches
+fi
+```
+
+从补丁目录读取 `backup-meta.json`。
+
+**如果未找到补丁：**
+```
+未找到本地补丁。无需重新应用。
+
+本地补丁会在你运行 /specops:update 后自动保存
+（如果你修改了任何 SpecOps 工作流、命令或 agent 文件）。
+```
+退出。
+
+## 步骤 2：展示补丁摘要
+
+```
+## 待重新应用的本地补丁
+
+**备份自：** v{from_version}
+**当前版本：** {读取 VERSION 文件}
+**修改文件数：** {count}
+
+| # | 文件 | 状态 |
+|---|------|------|
+| 1 | {file_path} | 待处理 |
+| 2 | {file_path} | 待处理 |
+```
+
+## 步骤 3：合并每个文件
+
+对 `backup-meta.json` 中的每个文件：
+
+1. **读取备份版本**（用户修改过的副本，来自 `specops-local-patches/`）
+2. **读取新安装版本**（更新后的当前文件）
+3. **比较并合并：**
+
+   - 如果新文件与备份文件相同：跳过（修改已被上游合并）
+   - 如果新文件不同：识别用户的修改并应用到新版本
+
+   **合并策略：**
+   - 完整读取两个版本
+   - 识别用户添加或修改的部分（寻找新增内容，而非仅路径替换的差异）
+   - 将用户的新增/修改应用到新版本
+   - 如果用户修改的部分上游也发生了变化：标记为冲突，展示两个版本，询问用户保留哪个
+
+4. **写入合并结果**到安装位置
+5. **报告状态：**
+   - `已合并` — 用户修改已干净应用
+   - `已跳过` — 修改已存在于上游
+   - `冲突` — 用户选择了解决方案
+
+## 步骤 4：更新清单
+
+重新应用后，重新生成文件清单以便未来更新正确检测这些用户修改：
+
+```bash
+# 清单将在下次 /specops:update 时重新生成
+# 现在只记录哪些文件被修改
+```
+
+## 步骤 5：清理选项
+
+询问用户：
+- "保留补丁备份作为参考？" → 保留 `specops-local-patches/`
+- "清理补丁备份？" → 删除 `specops-local-patches/` 目录
+
+## 步骤 6：报告
+
+```
+## 补丁已重新应用
+
+| # | 文件 | 状态 |
+|---|------|------|
+| 1 | {file_path} | ✓ 已合并 |
+| 2 | {file_path} | ○ 已跳过（已在上游） |
+| 3 | {file_path} | ⚠ 冲突已解决 |
+
+{count} 个文件已更新。你的本地修改已重新激活。
+```
+
+</process>
+
+<success_criteria>
+- [ ] 所有备份的补丁已处理
+- [ ] 用户修改已合并到新版本
+- [ ] 冲突已通过用户输入解决
+- [ ] 每个文件的状态已报告
+</success_criteria>

package/commands/specops/remove-phase.md

@@ -0,0 +1,31 @@
+---
+name: specops:remove-phase
+description: 从路线图中移除未来阶段并重新编号后续阶段
+argument-hint: <phase-number>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+<objective>
+从路线图中移除一个未开始的未来阶段，并重新编号所有后续阶段以保持干净的线性序列。
+
+目的：干净地移除你决定不做的工作，不会用取消/延迟标记污染上下文。
+输出：阶段已删除，所有后续阶段已重新编号，git 提交作为历史记录。
+</objective>
+
+<execution_context>
+@.opencode/workflows/remove-phase.md
+</execution_context>
+
+<context>
+阶段：$ARGUMENTS
+
+路线图和状态在工作流中通过 `init phase-op` 和定向读取解析。
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/remove-phase.md 中的 remove-phase 工作流。
+保留所有验证门控（未来阶段检查、工作检查）、重新编号逻辑和提交。
+</process>

package/commands/specops/research-phase.md

@@ -0,0 +1,189 @@
+---
+name: specops:research-phase
+description: 研究如何实现某个阶段（独立命令——通常使用 /specops:plan-phase 代替）
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+---
+
+<objective>
+研究如何实现某个阶段。生成带有阶段上下文的 specops-phase-researcher 代理。
+
+**注意：** 这是一个独立的研究命令。对于大多数工作流，使用 `/specops:plan-phase` 会自动集成研究。
+
+**使用此命令的场景：**
+- 你想在不规划的情况下先研究
+- 你想在规划完成后重新研究
+- 你需要在决定阶段是否可行之前进行调查
+
+**编排器角色：** 解析阶段，对照路线图验证，检查现有研究，收集上下文，生成研究代理，展示结果。
+
+**为什么用子代理：** 研究会快速消耗上下文（WebSearch、Context7 查询、源验证）。调查使用全新的 200k 上下文。主上下文保持精简以便用户交互。
+</objective>
+
+<context>
+阶段编号：$ARGUMENTS（必需）
+
+在步骤 1 中标准化阶段输入，然后再进行任何目录查找。
+</context>
+
+<process>
+
+## 0. 初始化上下文
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "$ARGUMENTS")
+```
+
+从初始化 JSON 中提取：`phase_dir`、`phase_number`、`phase_name`、`phase_found`、`commit_docs`、`has_research`、`state_path`、`requirements_path`、`context_path`、`research_path`。
+
+解析研究员模型：
+```bash
+RESEARCHER_MODEL=$(node .opencode/bin/specops-tools.cjs resolve-model specops-phase-researcher --raw)
+```
+
+## 1. 验证阶段
+
+```bash
+PHASE_INFO=$(node .opencode/bin/specops-tools.cjs roadmap get-phase "${phase_number}")
+```
+
+**如果 `found` 为 false：** 报错并退出。**如果 `found` 为 true：** 从 JSON 中提取 `phase_number`、`phase_name`、`goal`。
+
+## 2. 检查现有研究
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+```
+
+**如果存在：** 提供选项：1) 更新研究，2) 查看现有，3) 跳过。等待响应。
+
+**如果不存在：** 继续。
+
+## 3. 收集阶段上下文
+
+使用 INIT 中的路径（不要在编排器上下文中内联文件内容）：
+- `requirements_path`
+- `context_path`
+- `state_path`
+
+展示摘要，包含阶段描述和研究员将加载的文件。
+
+## 4. 生成 specops-phase-researcher 代理
+
+研究模式：ecosystem（默认）、feasibility、implementation、comparison。
+
+```markdown
+<research_type>
+Phase Research — investigating HOW to implement a specific phase well.
+</research_type>
+
+<key_insight>
+The question is NOT "which library should I use?"
+
+The question is: "What do I not know that I don't know?"
+
+For this phase, discover:
+- What's the established architecture pattern?
+- What libraries form the standard stack?
+- What problems do people commonly hit?
+- What's SOTA vs what Claude's training thinks is SOTA?
+- What should NOT be hand-rolled?
+</key_insight>
+
+<objective>
+Research implementation approach for Phase {phase_number}: {phase_name}
+Mode: ecosystem
+</objective>
+
+<files_to_read>
+- {requirements_path} (Requirements)
+- {context_path} (Phase context from discuss-phase, if exists)
+- {state_path} (Prior project decisions and blockers)
+</files_to_read>
+
+<additional_context>
+**Phase description:** {phase_description}
+</additional_context>
+
+<downstream_consumer>
+Your RESEARCH.md will be loaded by `/specops:plan-phase` which uses specific sections:
+- `## Standard Stack` → Plans use these libraries
+- `## Architecture Patterns` → Task structure follows these
+- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
+- `## Common Pitfalls` → Verification steps check for these
+- `## Code Examples` → Task actions reference these patterns
+
+Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
+</downstream_consumer>
+
+<quality_gate>
+Before declaring complete, verify:
+- [ ] All domains investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources for critical claims
+- [ ] Confidence levels assigned honestly
+- [ ] Section names match what plan-phase expects
+</quality_gate>
+
+<output>
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+</output>
+```
+
+```
+Task(
+  prompt="First, read ~/.claude/agents/specops-phase-researcher.md for your role and instructions.\n\n" + filled_prompt,
+  subagent_type="general-purpose",
+  model="{researcher_model}",
+  description="Research Phase {phase}"
+)
+```
+
+## 5. 处理代理返回
+
+**`## RESEARCH COMPLETE`：** 显示摘要，提供选项：规划阶段、深入研究、查看完整内容、完成。
+
+**`## CHECKPOINT REACHED`：** 向用户展示，获取响应，生成后续代理。
+
+**`## RESEARCH INCONCLUSIVE`：** 显示已尝试的内容，提供选项：添加上下文、尝试不同模式、手动。
+
+## 6. 生成后续代理
+
+```markdown
+<objective>
+Continue research for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+```
+
+```
+Task(
+  prompt="First, read ~/.claude/agents/specops-phase-researcher.md for your role and instructions.\n\n" + continuation_prompt,
+  subagent_type="general-purpose",
+  model="{researcher_model}",
+  description="Continue research Phase {phase}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] 阶段已对照路线图验证
+- [ ] 已检查现有研究
+- [ ] 已生成带上下文的 specops-phase-researcher
+- [ ] 正确处理检查点
+- [ ] 用户知道后续步骤
+</success_criteria>