specops 0.2.5 → 0.3.2

package/.opencode/workflows/help.md

@@ -0,0 +1,489 @@
+<purpose>
+显示完整的 SpecOps 命令参考。仅输出参考内容。不要添加项目分析、git 状态、下一步建议或参考之外的任何评论。
+</purpose>
+
+<reference>
+# SpecOps 命令参考
+
+**SpecOps**（Get Shit Done）创建层次化的项目计划，专为使用 Claude Code 的单人 Agent 开发优化。
+
+## 快速开始
+
+1. `/specops:new-project` - 初始化项目（包括研究、需求、路线图）
+2. `/specops:plan-phase 1` - 为第一个阶段创建详细计划
+3. `/specops:execute-phase 1` - 执行该阶段
+
+## 保持更新
+
+SpecOps 迭代迅速。定期更新：
+
+```bash
+npx specops-cc@latest
+```
+
+## 核心工作流
+
+```
+/specops:new-project → /specops:plan-phase → /specops:execute-phase → 重复
+```
+
+### 项目初始化
+
+**`/specops:new-project`**
+通过统一流程初始化新项目。
+
+一个命令带你从想法到准备规划：
+- 深度提问以了解你要构建什么
+- 可选的领域研究（生成 4 个并行研究代理）
+- 需求定义，含 v1/v2/不在范围内的划分
+- 路线图创建，含阶段分解和成功标准
+
+创建所有 `.planning/` 产物：
+- `PROJECT.md` — 愿景和需求
+- `config.json` — 工作流模式（interactive/yolo）
+- `research/` — 领域研究（如果选择了）
+- `REQUIREMENTS.md` — 带 REQ-ID 的范围化需求
+- `ROADMAP.md` — 映射到需求的阶段
+- `STATE.md` — 项目记忆
+
+用法：`/specops:new-project`
+
+**`/specops:map-codebase`**
+为棕地项目映射现有代码库。
+
+- 使用并行 Explore 代理分析代码库
+- 创建 `.planning/codebase/`，包含 7 份聚焦文档
+- 覆盖技术栈、架构、结构、约定、测试、集成、关注点
+- 在现有代码库上运行 `/specops:new-project` 之前使用
+
+用法：`/specops:map-codebase`
+
+### 阶段规划
+
+**`/specops:discuss-phase <number>`**
+在规划之前帮助表达你对阶段的愿景。
+
+- 捕获你对这个阶段如何运作的想象
+- 创建 CONTEXT.md，包含你的愿景、核心要素和边界
+- 当你对某些东西应该是什么样子/感觉时使用
+
+用法：`/specops:discuss-phase 2`
+
+**`/specops:research-phase <number>`**
+针对小众/复杂领域的全面生态系统研究。
+
+- 发现标准技术栈、架构模式、陷阱
+- 创建 RESEARCH.md，包含「专家如何构建这个」的知识
+- 用于 3D、游戏、音频、着色器、ML 和其他专业领域
+- 不仅限于「用哪个库」，而是生态系统知识
+
+用法：`/specops:research-phase 3`
+
+**`/specops:list-phase-assumptions <number>`**
+在 Claude 开始之前查看它计划做什么。
+
+- 显示 Claude 对阶段的预期方案
+- 如果 Claude 误解了你的愿景，可以纠正方向
+- 不创建文件——仅对话输出
+
+用法：`/specops:list-phase-assumptions 3`
+
+**`/specops:plan-phase <number>`**
+为特定阶段创建详细的执行计划。
+
+- 生成 `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
+- 将阶段分解为具体、可执行的任务
+- 包含验证标准和成功衡量
+- 每个阶段支持多个计划（XX-01、XX-02 等）
+
+用法：`/specops:plan-phase 1`
+结果：创建 `.planning/phases/01-foundation/01-01-PLAN.md`
+
+**PRD 快速路径：** 传递 `--prd path/to/requirements.md` 可完全跳过 discuss-phase。你的 PRD 成为 CONTEXT.md 中的锁定决策。当你已经有明确的验收标准时很有用。
+
+### 执行
+
+**`/specops:execute-phase <phase-number>`**
+执行阶段中的所有计划。
+
+- 按波次分组计划（来自 frontmatter），按顺序执行波次
+- 每个波次内的计划通过 Task 工具并行运行
+- 所有计划完成后验证阶段目标
+- 更新 REQUIREMENTS.md、ROADMAP.md、STATE.md
+
+用法：`/specops:execute-phase 5`
+
+### 快速模式
+
+**`/specops:quick`**
+使用 SpecOps 保障执行小型临时任务，但跳过可选代理。
+
+快速模式使用相同系统但路径更短：
+- 生成规划器 + 执行器（跳过研究器、检查器、验证器）
+- 快速任务存放在 `.planning/quick/`，与计划阶段分开
+- 更新 STATE.md 跟踪（不更新 ROADMAP.md）
+
+当你确切知道要做什么且任务小到不需要研究或验证时使用。
+
+用法：`/specops:quick`
+结果：创建 `.planning/quick/NNN-slug/PLAN.md`、`.planning/quick/NNN-slug/SUMMARY.md`
+
+### 路线图管理
+
+**`/specops:add-phase <description>`**
+在当前里程碑末尾添加新阶段。
+
+- 追加到 ROADMAP.md
+- 使用下一个顺序编号
+- 更新阶段目录结构
+
+用法：`/specops:add-phase "Add admin dashboard"`
+
+**`/specops:insert-phase <after> <description>`**
+在现有阶段之间插入紧急工作的小数阶段。
+
+- 创建中间阶段（例如 7 和 8 之间的 7.1）
+- 适用于里程碑中途发现的必须完成的工作
+- 保持阶段顺序
+
+用法：`/specops:insert-phase 7 "Fix critical auth bug"`
+结果：创建 Phase 7.1
+
+**`/specops:remove-phase <number>`**
+移除未来阶段并重新编号后续阶段。
+
+- 删除阶段目录和所有引用
+- 重新编号所有后续阶段以填补空缺
+- 仅适用于未开始的未来阶段
+- Git 提交保留历史记录
+
+用法：`/specops:remove-phase 17`
+结果：Phase 17 删除，phases 18-20 变为 17-19
+
+### 里程碑管理
+
+**`/specops:new-milestone <name>`**
+通过统一流程开始新里程碑。
+
+- 深度提问以了解你接下来要构建什么
+- 可选的领域研究（生成 4 个并行研究代理）
+- 需求定义，含范围划分
+- 路线图创建，含阶段分解
+
+为棕地项目（已有 PROJECT.md）提供与 `/specops:new-project` 相同的流程。
+
+用法：`/specops:new-milestone "v2.0 Features"`
+
+**`/specops:complete-milestone <version>`**
+归档已完成的里程碑并准备下一版本。
+
+- 在 MILESTONES.md 中创建条目和统计
+- 将完整详情归档到 milestones/ 目录
+- 为发布创建 git tag
+- 为下一版本准备工作区
+
+用法：`/specops:complete-milestone 1.0.0`
+
+### 进度跟踪
+
+**`/specops:progress`**
+检查项目状态并智能路由到下一个操作。
+
+- 显示可视化进度条和完成百分比
+- 从 SUMMARY 文件汇总近期工作
+- 显示当前位置和下一步
+- 列出关键决策和待解决问题
+- 提供执行下一个计划或创建计划（如缺失）的选项
+- 检测 100% 里程碑完成
+
+用法：`/specops:progress`
+
+### 会话管理
+
+**`/specops:resume-work`**
+从之前的会话恢复工作，完整恢复上下文。
+
+- 读取 STATE.md 获取项目上下文
+- 显示当前位置和近期进展
+- 根据项目状态提供下一步操作
+
+用法：`/specops:resume-work`
+
+**`/specops:pause-work`**
+在阶段中途暂停工作时创建上下文交接。
+
+- 创建 .continue-here 文件记录当前状态
+- 更新 STATE.md 会话连续性部分
+- 捕获进行中的工作上下文
+
+用法：`/specops:pause-work`
+
+### 调试
+
+**`/specops:debug [issue description]`**
+跨上下文重置的持久化系统调试。
+
+- 通过自适应提问收集症状
+- 创建 `.planning/debug/[slug].md` 跟踪调查
+- 使用科学方法调查（证据 → 假设 → 测试）
+- 可在 `/clear` 后存活——不带参数运行 `/specops:debug` 即可恢复
+- 将已解决的问题归档到 `.planning/debug/resolved/`
+
+用法：`/specops:debug "login button doesn't work"`
+用法：`/specops:debug`（恢复活跃会话）
+
+### 待办事项管理
+
+**`/specops:add-todo [description]`**
+从当前对话中捕获想法或任务作为待办事项。
+
+- 从对话中提取上下文（或使用提供的描述）
+- 在 `.planning/todos/pending/` 中创建结构化待办文件
+- 从文件路径推断所属区域以便分组
+- 创建前检查重复
+- 更新 STATE.md 待办计数
+
+用法：`/specops:add-todo`（从对话推断）
+用法：`/specops:add-todo Add auth token refresh`
+
+**`/specops:check-todos [area]`**
+列出待办事项并选择一个来处理。
+
+- 列出所有待办事项，含标题、区域、时间
+- 可选区域过滤（如 `/specops:check-todos api`）
+- 为选中的待办加载完整上下文
+- 路由到相应操作（立即处理、添加到阶段、头脑风暴）
+- 开始工作时将待办移到 done/
+
+用法：`/specops:check-todos`
+用法：`/specops:check-todos api`
+
+### 用户验收测试
+
+**`/specops:verify-work [phase]`**
+通过对话式 UAT 验证已构建的功能。
+
+- 从 SUMMARY.md 文件中提取可测试的交付物
+- 逐个展示测试（是/否响应）
+- 自动诊断失败并创建修复计划
+- 发现问题后准备重新执行
+
+用法：`/specops:verify-work 3`
+
+### 里程碑审计
+
+**`/specops:audit-milestone [version]`**
+对照原始意图审计里程碑完成情况。
+
+- 读取所有阶段的 VERIFICATION.md 文件
+- 检查需求覆盖率
+- 生成集成检查器用于跨阶段连接
+- 创建 MILESTONE-AUDIT.md，包含差距和技术债务
+
+用法：`/specops:audit-milestone`
+
+**`/specops:plan-milestone-gaps`**
+创建阶段来弥补审计发现的差距。
+
+- 读取 MILESTONE-AUDIT.md 并将差距分组为阶段
+- 按需求优先级排序（must/should/nice）
+- 将差距修复阶段添加到 ROADMAP.md
+- 准备好对新阶段运行 `/specops:plan-phase`
+
+用法：`/specops:plan-milestone-gaps`
+
+### 配置
+
+**`/specops:settings`**
+交互式配置工作流开关和模型配置。
+
+- 切换研究器、计划检查器、验证器代理
+- 选择模型配置（quality/balanced/budget）
+- 更新 `.planning/config.json`
+
+用法：`/specops:settings`
+
+**`/specops:set-profile <profile>`**
+快速切换 SpecOps 代理的模型配置。
+
+- `quality` — 除验证外全部使用 Opus
+- `balanced` — 规划用 Opus，执行用 Sonnet（默认）
+- `budget` — 编写用 Sonnet，研究/验证用 Haiku
+
+用法：`/specops:set-profile budget`
+
+### 实用命令
+
+**`/specops:cleanup`**
+归档已完成里程碑中积累的阶段目录。
+
+- 识别仍在 `.planning/phases/` 中的已完成里程碑阶段
+- 移动前显示预览摘要
+- 将阶段目录移到 `.planning/milestones/v{X.Y}-phases/`
+- 在多个里程碑后用于减少 `.planning/phases/` 的混乱
+
+用法：`/specops:cleanup`
+
+**`/specops:help`**
+显示此命令参考。
+
+**`/specops:update`**
+更新 SpecOps 到最新版本并预览变更日志。
+
+- 显示已安装版本与最新版本的对比
+- 显示你错过的版本的变更日志条目
+- 高亮破坏性变更
+- 安装前确认
+- 比直接运行 `npx specops-cc` 更好
+
+用法：`/specops:update`
+
+**`/specops:join-discord`**
+加入 SpecOps Discord 社区。
+
+- 获取帮助，分享你正在构建的东西，保持更新
+- 与其他 SpecOps 用户联系
+
+用法：`/specops:join-discord`
+
+## 文件与结构
+
+```
+.planning/
+├── PROJECT.md            # 项目愿景
+├── ROADMAP.md            # 当前阶段分解
+├── STATE.md              # 项目记忆与上下文
+├── RETROSPECTIVE.md      # 持续更新的回顾（每个里程碑更新）
+├── config.json           # 工作流模式与门控
+├── todos/                # 捕获的想法和任务
+│   ├── pending/          # 等待处理的待办
+│   └── done/             # 已完成的待办
+├── debug/                # 活跃调试会话
+│   └── resolved/         # 已归档的已解决问题
+├── milestones/
+│   ├── v1.0-ROADMAP.md       # 归档的路线图快照
+│   ├── v1.0-REQUIREMENTS.md  # 归档的需求
+│   └── v1.0-phases/          # 归档的阶段目录（通过 /specops:cleanup 或 --archive-phases）
+│       ├── 01-foundation/
+│       └── 02-core-features/
+├── codebase/             # 代码库映射（棕地项目）
+│   ├── STACK.md          # 语言、框架、依赖
+│   ├── ARCHITECTURE.md   # 模式、层次、数据流
+│   ├── STRUCTURE.md      # 目录布局、关键文件
+│   ├── CONVENTIONS.md    # 编码标准、命名
+│   ├── TESTING.md        # 测试设置、模式
+│   ├── INTEGRATIONS.md   # 外部服务、API
+│   └── CONCERNS.md       # 技术债务、已知问题
+└── phases/
+    ├── 01-foundation/
+    │   ├── 01-01-PLAN.md
+    │   └── 01-01-SUMMARY.md
+    └── 02-core-features/
+        ├── 02-01-PLAN.md
+        └── 02-01-SUMMARY.md
+```
+
+## 工作流模式
+
+在 `/specops:new-project` 期间设置：
+
+**交互模式**
+
+- 确认每个主要决策
+- 在检查点暂停等待批准
+- 全程提供更多指导
+
+**YOLO 模式**
+
+- 自动批准大多数决策
+- 无需确认即执行计划
+- 仅在关键检查点停止
+
+随时通过编辑 `.planning/config.json` 更改
+
+## 规划配置
+
+在 `.planning/config.json` 中配置规划产物的管理方式：
+
+**`planning.commit_docs`**（默认：`true`）
+- `true`：规划产物提交到 git（标准工作流）
+- `false`：规划产物仅保留在本地，不提交
+
+当 `commit_docs: false` 时：
+- 将 `.planning/` 添加到你的 `.gitignore`
+- 适用于 OSS 贡献、客户项目或保持规划私密
+- 所有规划文件仍正常工作，只是不被 git 跟踪
+
+**`planning.search_gitignored`**（默认：`false`）
+- `true`：在广泛的 ripgrep 搜索中添加 `--no-ignore`
+- 仅在 `.planning/` 被 gitignore 且你希望项目范围搜索包含它时需要
+
+配置示例：
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "search_gitignored": true
+  }
+}
+```
+
+## 常见工作流
+
+**启动新项目：**
+
+```
+/specops:new-project        # 统一流程：提问 → 研究 → 需求 → 路线图
+/clear
+/specops:plan-phase 1       # 为第一阶段创建计划
+/clear
+/specops:execute-phase 1    # 执行阶段中所有计划
+```
+
+**休息后恢复工作：**
+
+```
+/specops:progress  # 查看上次停在哪里并继续
+```
+
+**添加紧急的里程碑中途工作：**
+
+```
+/specops:insert-phase 5 "Critical security fix"
+/specops:plan-phase 5.1
+/specops:execute-phase 5.1
+```
+
+**完成里程碑：**
+
+```
+/specops:complete-milestone 1.0.0
+/clear
+/specops:new-milestone  # 开始下一个里程碑（提问 → 研究 → 需求 → 路线图）
+```
+
+**工作中捕获想法：**
+
+```
+/specops:add-todo                    # 从对话上下文中捕获
+/specops:add-todo Fix modal z-index  # 用明确描述捕获
+/specops:check-todos                 # 查看并处理待办
+/specops:check-todos api             # 按区域过滤
+```
+
+**调试问题：**
+
+```
+/specops:debug "form submission fails silently"  # 开始调试会话
+# ... 调查进行中，上下文填满 ...
+/clear
+/specops:debug                                    # 从上次断点恢复
+```
+
+## 获取帮助
+
+- 阅读 `.planning/PROJECT.md` 了解项目愿景
+- 阅读 `.planning/STATE.md` 了解当前上下文
+- 查看 `.planning/ROADMAP.md` 了解阶段状态
+- 运行 `/specops:progress` 查看当前进度
+</reference>

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

@@ -0,0 +1,129 @@
+<purpose>
+在里程碑进行中发现紧急工作时，在现有整数阶段之间插入小数阶段。使用小数编号（72.1、72.2 等）来保持已规划阶段的逻辑顺序，同时容纳紧急插入而无需重新编号整个路线图。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+解析命令参数：
+- 第一个参数：要在其后插入的整数阶段编号
+- 剩余参数：阶段描述
+
+示例：`/specops:insert-phase 72 Fix critical auth bug`
+-> after = 72
+-> description = "Fix critical auth bug"
+
+如果参数缺失：
+
+```
+ERROR: Both phase number and description required
+Usage: /specops:insert-phase <after> <description>
+Example: /specops:insert-phase 72 Fix critical auth bug
+```
+
+退出。
+
+验证第一个参数是否为整数。
+</step>
+
+<step name="init_context">
+加载阶段操作上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "${after_phase}")
+```
+
+检查 init JSON 中的 `roadmap_exists`。如果为 false：
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+```
+退出。
+</step>
+
+<step name="insert_phase">
+**将阶段插入操作委托给 specops-tools：**
+
+```bash
+RESULT=$(node .opencode/bin/specops-tools.cjs phase insert "${after_phase}" "${description}")
+```
+
+CLI 处理以下操作：
+- 验证目标阶段存在于 ROADMAP.md 中
+- 计算下一个小数阶段编号（检查磁盘上已有的小数阶段）
+- 从描述生成 slug
+- 创建阶段目录（`.planning/phases/{N.M}-{slug}/`）
+- 在 ROADMAP.md 中目标阶段之后插入阶段条目，带有 (INSERTED) 标记
+
+从结果中提取：`phase_number`、`after_phase`、`name`、`slug`、`directory`。
+</step>
+
+<step name="update_project_state">
+更新 STATE.md 以反映插入的阶段：
+
+1. 读取 `.planning/STATE.md`
+2. 在 "## Accumulated Context" → "### Roadmap Evolution" 下添加条目：
+   ```
+   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
+   ```
+
+如果 "Roadmap Evolution" 部分不存在，则创建它。
+</step>
+
+<step name="completion">
+展示完成摘要：
+
+```
+Phase {decimal_phase} inserted after Phase {after_phase}:
+- Description: {description}
+- Directory: .planning/phases/{decimal-phase}-{slug}/
+- Status: Not planned yet
+- Marker: (INSERTED) - indicates urgent work
+
+Roadmap updated: .planning/ROADMAP.md
+Project state updated: .planning/STATE.md
+
+---
+
+## 下一步
+
+**Phase {decimal_phase}: {description}** -- 紧急插入
+
+`/specops:plan-phase {decimal_phase}`
+
+<sub>`/clear` 先清理 -> 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- 审查插入影响：检查 Phase {next_integer} 的依赖是否仍然合理
+- 审查路线图
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- 不要将此命令用于里程碑末尾的计划工作（应使用 /specops:add-phase）
+- 不要在 Phase 1 之前插入（小数 0.1 没有意义）
+- 不要重新编号现有阶段
+- 不要修改目标阶段的内容
+- 不要在此创建计划（那是 /specops:plan-phase 的工作）
+- 不要提交更改（由用户决定何时提交）
+</anti_patterns>
+
+<success_criteria>
+阶段插入完成的条件：
+
+- [ ] `specops-tools phase insert` 执行成功
+- [ ] 阶段目录已创建
+- [ ] 路线图已更新，包含新阶段条目（含 "(INSERTED)" 标记）
+- [ ] STATE.md 已更新路线图演进记录
+- [ ] 用户已被告知后续步骤及依赖影响
+</success_criteria>