specops 0.2.4 → 0.3.0

package/commands/specops/audit-milestone.md

@@ -0,0 +1,36 @@
+---
+name: specops:audit-milestone
+description: 在归档之前审计里程碑完成情况是否符合原始意图
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - Write
+---
+<objective>
+验证里程碑是否达成了其完成定义。检查需求覆盖率、跨阶段集成和端到端流程。
+
+**此命令本身就是编排器。** 读取现有的 VERIFICATION.md 文件（阶段在 execute-phase 期间已验证），汇总技术债务和延迟的缺口，然后生成集成检查器进行跨阶段连接检查。
+</objective>
+
+<execution_context>
+@.opencode/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+版本：$ARGUMENTS（可选 — 默认为当前里程碑）
+
+核心规划文件在工作流中解析（`init milestone-op`），仅按需加载。
+
+**已完成的工作：**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/audit-milestone.md 中的 audit-milestone 工作流。
+保留所有工作流门控（范围确定、验证读取、集成检查、需求覆盖、路由）。
+</process>

package/commands/specops/check-todos.md

@@ -0,0 +1,45 @@
+---
+name: specops:check-todos
+description: 列出待处理的待办事项并选择一个来处理
+argument-hint: [area filter]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+列出所有待处理的待办事项，允许选择，加载所选待办的完整上下文，并路由到适当的操作。
+
+路由到 check-todos 工作流，该工作流处理：
+- 待办计数和列表（带领域过滤）
+- 交互式选择及完整上下文加载
+- 路线图关联检查
+- 操作路由（立即处理、添加到阶段、头脑风暴、创建阶段）
+- STATE.md 更新和 git 提交
+</objective>
+
+<execution_context>
+@.opencode/workflows/check-todos.md
+</execution_context>
+
+<context>
+参数：$ARGUMENTS（可选的领域过滤器）
+
+待办状态和路线图关联在工作流中通过 `init todos` 和定向读取加载。
+</context>
+
+<process>
+**遵循 check-todos 工作流**，来自 `@.opencode/workflows/check-todos.md`。
+
+该工作流处理所有逻辑，包括：
+1. 待办存在性检查
+2. 领域过滤
+3. 交互式列表和选择
+4. 完整上下文加载及文件摘要
+5. 路线图关联检查
+6. 操作提供和执行
+7. STATE.md 更新
+8. Git 提交
+</process>

package/commands/specops/cleanup.md

@@ -0,0 +1,18 @@
+---
+name: specops:cleanup
+description: 归档已完成里程碑的阶段目录
+---
+<objective>
+将已完成里程碑的阶段目录归档到 `.planning/milestones/v{X.Y}-phases/` 中。
+
+当 `.planning/phases/` 积累了过多历史里程碑的目录时使用。
+</objective>
+
+<execution_context>
+@.opencode/workflows/cleanup.md
+</execution_context>
+
+<process>
+遵循 @.opencode/workflows/cleanup.md 中的清理工作流。
+识别已完成的里程碑，展示预演摘要，确认后执行归档。
+</process>

package/commands/specops/complete-milestone.md

@@ -0,0 +1,136 @@
+---
+type: prompt
+name: specops:complete-milestone
+description: 归档已完成的里程碑并为下一个版本做准备
+argument-hint: <version>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+将里程碑 {{version}} 标记为完成，归档到 milestones/，并更新 ROADMAP.md 和 REQUIREMENTS.md。
+
+目的：创建已发布版本的历史记录，归档里程碑产物（路线图 + 需求），并为下一个里程碑做准备。
+输出：里程碑已归档（路线图 + 需求），PROJECT.md 已演进，git 已打标签。
+</objective>
+
+<execution_context>
+**立即加载这些文件（在继续之前）：**
+
+- @.opencode/workflows/complete-milestone.md（主工作流）
+- @.opencode/templates/milestone-archive.md（归档模板）
+  </execution_context>
+
+<context>
+**项目文件：**
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/PROJECT.md`
+
+**用户输入：**
+
+- 版本：{{version}}（例如 "1.0"、"1.1"、"2.0"）
+  </context>
+
+<process>
+
+**遵循 complete-milestone.md 工作流：**
+
+0. **检查审计：**
+
+   - 查找 `.planning/v{{version}}-MILESTONE-AUDIT.md`
+   - 如果缺失或过期：建议先运行 `/specops:audit-milestone`
+   - 如果审计状态为 `gaps_found`：建议先运行 `/specops:plan-milestone-gaps`
+   - 如果审计状态为 `passed`：继续步骤 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md:}
+   ⚠ No milestone audit found. Run `/specops:audit-milestone` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/specops:plan-milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **验证就绪状态：**
+
+   - 检查里程碑中所有阶段是否有已完成的计划（SUMMARY.md 存在）
+   - 展示里程碑范围和统计数据
+   - 等待确认
+
+2. **收集统计数据：**
+
+   - 统计阶段、计划、任务数量
+   - 计算 git 范围、文件变更、代码行数
+   - 从 git log 提取时间线
+   - 展示摘要，确认
+
+3. **提取成就：**
+
+   - 读取里程碑范围内所有阶段的 SUMMARY.md 文件
+   - 提取 4-6 个关键成就
+   - 提交审批
+
+4. **归档里程碑：**
+
+   - 创建 `.planning/milestones/v{{version}}-ROADMAP.md`
+   - 从 ROADMAP.md 提取完整阶段详情
+   - 填充 milestone-archive.md 模板
+   - 将 ROADMAP.md 更新为带链接的单行摘要
+
+5. **归档需求：**
+
+   - 创建 `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - 将所有 v1 需求标记为完成（复选框已勾选）
+   - 记录需求结果（已验证、已调整、已放弃）
+   - 删除 `.planning/REQUIREMENTS.md`（为下一个里程碑创建新的）
+
+6. **更新 PROJECT.md：**
+
+   - 添加"当前状态"章节，包含已发布版本
+   - 添加"下一里程碑目标"章节
+   - 将之前的内容归档到 `<details>` 中（如果是 v1.1+）
+
+7. **提交并打标签：**
+
+   - 暂存：MILESTONES.md、PROJECT.md、ROADMAP.md、STATE.md、归档文件
+   - 提交：`chore: archive v{{version}} milestone`
+   - 标签：`git tag -a v{{version}} -m "[milestone summary]"`
+   - 询问是否推送标签
+
+8. **提供后续步骤：**
+   - `/specops:new-milestone` — 开始下一个里程碑（提问 → 研究 → 需求 → 路线图）
+
+</process>
+
+<success_criteria>
+
+- 里程碑已归档到 `.planning/milestones/v{{version}}-ROADMAP.md`
+- 需求已归档到 `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- `.planning/REQUIREMENTS.md` 已删除（为下一个里程碑准备新的）
+- ROADMAP.md 已折叠为单行条目
+- PROJECT.md 已更新为当前状态
+- Git 标签 v{{version}} 已创建
+- 提交成功
+- 用户知道后续步骤（包括需要新的需求定义）
+  </success_criteria>
+
+<critical_rules>
+
+- **先加载工作流：** 在执行前读取 complete-milestone.md
+- **验证完成度：** 所有阶段必须有 SUMMARY.md 文件
+- **用户确认：** 在验证门控处等待批准
+- **先归档再删除：** 在更新/删除原始文件之前始终创建归档文件
+- **单行摘要：** ROADMAP.md 中折叠的里程碑应为带链接的单行
+- **上下文效率：** 归档使 ROADMAP.md 和 REQUIREMENTS.md 每个里程碑保持恒定大小
+- **新需求：** 下一个里程碑从 `/specops:new-milestone` 开始，其中包含需求定义
+  </critical_rules>

package/commands/specops/debug.md

@@ -0,0 +1,167 @@
+---
+name: specops:debug
+description: 跨上下文重置的系统化调试，带持久状态
+argument-hint: [issue description]
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+使用科学方法和子代理隔离来调试问题。
+
+**编排器角色：** 收集症状，生成 specops-debugger 代理，处理检查点，生成后续代理。
+
+**为什么用子代理：** 调查会快速消耗上下文（读取文件、形成假设、测试）。每次调查都有全新的 200k 上下文。主上下文保持精简以便用户交互。
+</objective>
+
+<context>
+用户的问题：$ARGUMENTS
+
+检查活跃会话：
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+
+## 0. 初始化上下文
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs state load)
+```
+
+从初始化 JSON 中提取 `commit_docs`。解析调试器模型：
+```bash
+DEBUGGER_MODEL=$(node .opencode/bin/specops-tools.cjs resolve-model specops-debugger --raw)
+```
+
+## 1. 检查活跃会话
+
+如果存在活跃会话且没有 $ARGUMENTS：
+- 列出会话及状态、假设、下一步操作
+- 用户选择编号恢复或描述新问题
+
+如果提供了 $ARGUMENTS 或用户描述了新问题：
+- 继续到症状收集
+
+## 2. 收集症状（如果是新问题）
+
+使用 AskUserQuestion 逐一询问：
+
+1. **预期行为** - 应该发生什么？
+2. **实际行为** - 实际发生了什么？
+3. **错误消息** - 有错误吗？（粘贴或描述）
+4. **时间线** - 什么时候开始的？之前正常过吗？
+5. **复现方式** - 如何触发？
+
+全部收集后，确认准备开始调查。
+
+## 3. 生成 specops-debugger 代理
+
+填充提示并生成：
+
+```markdown
+<objective>
+Investigate issue: {slug}
+
+**Summary:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="specops-debugger",
+  model="{debugger_model}",
+  description="Debug {slug}"
+)
+```
+
+## 4. 处理代理返回
+
+**如果 `## ROOT CAUSE FOUND`：**
+- 显示根本原因和证据摘要
+- 提供选项：
+  - "立即修复" - 生成修复子代理
+  - "计划修复" - 建议 /specops:plan-phase --gaps
+  - "手动修复" - 完成
+
+**如果 `## CHECKPOINT REACHED`：**
+- 向用户展示检查点详情
+- 获取用户响应
+- 如果检查点类型是 `human-verify`：
+  - 如果用户确认已修复：继续让代理完成/解决/归档
+  - 如果用户报告问题：继续让代理返回调查/修复
+- 生成后续代理（见步骤 5）
+
+**如果 `## INVESTIGATION INCONCLUSIVE`：**
+- 显示已检查和排除的内容
+- 提供选项：
+  - "继续调查" - 生成带额外上下文的新代理
+  - "手动调查" - 完成
+  - "添加更多上下文" - 收集更多症状，再次生成
+
+## 5. 生成后续代理（检查点之后）
+
+当用户响应检查点时，生成新代理：
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/debug/{slug}.md (Debug session state)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="specops-debugger",
+  model="{debugger_model}",
+  description="Continue debug {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] 已检查活跃会话
+- [ ] 已收集症状（如果是新问题）
+- [ ] 已生成带上下文的 specops-debugger
+- [ ] 正确处理检查点
+- [ ] 修复前确认根本原因
+</success_criteria>

package/commands/specops/discuss-phase.md

@@ -0,0 +1,83 @@
+---
+name: specops:discuss-phase
+description: 在规划前通过自适应提问收集阶段上下文
+argument-hint: "<phase> [--auto]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+提取下游 agent 需要的实现决策 — 研究员和规划师将使用 CONTEXT.md 来了解需要调查什么以及哪些选择已锁定。
+
+**工作方式：**
+1. 分析阶段以识别灰色地带（UI、UX、行为等）
+2. 展示灰色地带 — 用户选择要讨论的内容
+3. 深入探讨每个选定区域直到满意
+4. 创建 CONTEXT.md，记录可指导研究和规划的决策
+
+**输出：** `{phase_num}-CONTEXT.md` — 决策足够清晰，下游 agent 无需再向用户询问
+</objective>
+
+<execution_context>
+@.opencode/workflows/discuss-phase.md
+@.opencode/templates/context.md
+</execution_context>
+
+<context>
+阶段编号：$ARGUMENTS（必填）
+
+上下文文件在工作流内部通过 `init phase-op` 和路线图/状态工具调用解析。
+</context>
+
+<process>
+1. 验证阶段编号（缺失或不在路线图中则报错）
+2. 检查 CONTEXT.md 是否存在（如存在则提供更新/查看/跳过选项）
+3. **分析阶段** — 识别领域并生成阶段特定的灰色地带
+4. **展示灰色地带** — 多选：要讨论哪些？（不提供跳过选项）
+5. **深入探讨每个区域** — 每个区域 4 个问题，然后提供继续/下一个选项
+6. **编写 CONTEXT.md** — 章节与讨论区域对应
+7. 提供下一步建议（研究或规划）
+
+**关键：范围守卫**
+- 路线图中的阶段边界是固定的
+- 讨论澄清的是如何实现，而非是否增加更多内容
+- 如果用户建议新功能："这应该是独立的阶段。我会记录下来待后续处理。"
+- 记录延后的想法 — 不遗漏，不执行
+
+**领域感知的灰色地带：**
+灰色地带取决于正在构建的内容。分析阶段目标：
+- 用户能看到的 → 布局、密度、交互、状态
+- 用户能调用的 → 响应、错误、认证、版本控制
+- 用户能运行的 → 输出格式、标志、模式、错误处理
+- 用户能阅读的 → 结构、语调、深度、流程
+- 正在组织的 → 标准、分组、命名、例外
+
+为每个阶段生成 3-4 个**阶段特定**灰色地带，而非通用类别。
+
+**探索深度：**
+- 每个区域先问 4 个问题再确认
+- "关于[区域]还有更多问题，还是进入下一个？"
+- 如果继续 → 再问 4 个，再次确认
+- 所有区域完成后 → "准备创建上下文了吗？"
+
+**不要询问（Claude 自行处理）：**
+- 技术实现
+- 架构选择
+- 性能问题
+- 范围扩展
+</process>
+
+<success_criteria>
+- 通过智能分析识别灰色地带
+- 用户选择了要讨论的区域
+- 每个选定区域探讨至满意
+- 范围蔓延被引导为延后想法
+- CONTEXT.md 记录的是决策，而非模糊愿景
+- 用户知道下一步是什么
+</success_criteria>

package/commands/specops/execute-phase.md

@@ -0,0 +1,41 @@
+---
+name: specops:execute-phase
+description: 使用基于波次的并行化执行阶段中的所有计划
+argument-hint: "<phase-number> [--gaps-only]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TodoWrite
+  - AskUserQuestion
+---
+<objective>
+使用基于波次的并行执行来执行阶段中的所有计划。
+
+编排器保持精简：发现计划、分析依赖、分组为波次、生成子代理、收集结果。每个子代理加载完整的 execute-plan 上下文并处理自己的计划。
+
+上下文预算：编排器约 15%，每个子代理 100% 全新。
+</objective>
+
+<execution_context>
+@.opencode/workflows/execute-phase.md
+@.opencode/references/ui-brand.md
+</execution_context>
+
+<context>
+阶段：$ARGUMENTS
+
+**标志：**
+- `--gaps-only` — 仅执行缺口修复计划（frontmatter 中 `gap_closure: true` 的计划）。在 verify-work 创建修复计划后使用。
+
+上下文文件在工作流内部通过 `specops-tools init execute-phase` 和每个子代理的 `<files_to_read>` 块解析。
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/execute-phase.md 中的 execute-phase 工作流。
+保留所有工作流门控（波次执行、检查点处理、验证、状态更新、路由）。
+</process>

package/commands/specops/health.md

@@ -0,0 +1,22 @@
+---
+name: specops:health
+description: 诊断规划目录健康状态并可选修复问题
+argument-hint: "[--repair]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+<objective>
+验证 `.planning/` 目录完整性并报告可操作的问题。检查缺失文件、无效配置、不一致状态和孤立计划。
+</objective>
+
+<execution_context>
+@.opencode/workflows/health.md
+</execution_context>
+
+<process>
+端到端执行 @.opencode/workflows/health.md 中的健康检查工作流。
+从参数中解析 --repair 标志并传递给工作流。
+</process>

package/commands/specops/help.md

@@ -0,0 +1,22 @@
+---
+name: specops:help
+description: 显示可用的 SpecOps 命令和使用指南
+---
+<objective>
+显示完整的 SpecOps 命令参考。
+
+仅输出以下参考内容。不要添加：
+- 项目特定的分析
+- Git 状态或文件上下文
+- 后续步骤建议
+- 参考之外的任何评论
+</objective>
+
+<execution_context>
+@.opencode/workflows/help.md
+</execution_context>
+
+<process>
+输出来自 @.opencode/workflows/help.md 的完整 SpecOps 命令参考。
+直接显示参考内容——不做任何添加或修改。
+</process>

package/commands/specops/insert-phase.md

@@ -0,0 +1,32 @@
+---
+name: specops:insert-phase
+description: 将紧急工作作为小数阶段（如 72.1）插入到现有阶段之间
+argument-hint: <after> <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+为里程碑中期发现的紧急工作插入一个小数阶段，该工作必须在现有整数阶段之间完成。
+
+使用小数编号（72.1、72.2 等）来保留计划阶段的逻辑顺序，同时容纳紧急插入。
+
+目的：处理执行期间发现的紧急工作，无需重新编号整个路线图。
+</objective>
+
+<execution_context>
+@.opencode/workflows/insert-phase.md
+</execution_context>
+
+<context>
+参数：$ARGUMENTS（格式：<after-phase-number> <description>）
+
+路线图和状态在工作流中通过 `init phase-op` 和定向工具调用解析。
+</context>
+
+<process>
+端到端执行 @.opencode/workflows/insert-phase.md 中的 insert-phase 工作流。
+保留所有验证门控（参数解析、阶段验证、小数计算、路线图更新）。
+</process>

package/commands/specops/join-discord.md

@@ -0,0 +1,18 @@
+---
+name: specops:join-discord
+description: 加入 SpecOps Discord 社区
+---
+
+<objective>
+显示 SpecOps 社区服务器的 Discord 邀请链接。
+</objective>
+
+<output>
+# 加入 SpecOps Discord
+
+与其他 SpecOps 用户交流，获取帮助，分享你正在构建的项目，并保持更新。
+
+**邀请链接：** https://discord.gg/5JJgD5svVS
+
+点击链接或将其粘贴到浏览器中即可加入。
+</output>

package/commands/specops/list-phase-assumptions.md

@@ -0,0 +1,46 @@
+---
+name: specops:list-phase-assumptions
+description: 在规划之前展示 Claude 对阶段方法的假设
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+分析一个阶段并展示 Claude 关于技术方法、实现顺序、范围边界、风险领域和依赖关系的假设。
+
+目的：帮助用户在规划开始之前看到 Claude 的想法——在假设错误时尽早纠正。
+输出：仅对话输出（不创建文件）——以"你觉得怎么样？"提示结束
+</objective>
+
+<execution_context>
+@.opencode/workflows/list-phase-assumptions.md
+</execution_context>
+
+<context>
+阶段编号：$ARGUMENTS（必需）
+
+项目状态和路线图在工作流中通过定向读取加载。
+</context>
+
+<process>
+1. 验证阶段编号参数（缺失或无效时报错）
+2. 检查阶段是否存在于路线图中
+3. 遵循 list-phase-assumptions.md 工作流：
+   - 分析路线图描述
+   - 展示关于以下方面的假设：技术方法、实现顺序、范围、风险、依赖关系
+   - 清晰展示假设
+   - 提示"你觉得怎么样？"
+4. 收集反馈并提供后续步骤
+</process>
+
+<success_criteria>
+
+- 阶段已对照路线图验证
+- 在五个领域展示了假设
+- 已提示用户反馈
+- 用户知道后续步骤（讨论上下文、规划阶段或纠正假设）
+  </success_criteria>