specops 0.2.5 → 0.3.2

package/.opencode/references/model-profiles.md

@@ -0,0 +1,92 @@
+# 模型配置
+
+模型配置控制每个 SpecOps 代理使用哪个 Claude 模型。这允许在质量和 token 消耗之间取得平衡。
+
+## 配置定义
+
+| 代理 | `quality` | `balanced` | `budget` |
+|------|-----------|------------|----------|
+| specops-planner | opus | opus | sonnet |
+| specops-roadmapper | opus | sonnet | sonnet |
+| specops-executor | opus | sonnet | sonnet |
+| specops-phase-researcher | opus | sonnet | haiku |
+| specops-project-researcher | opus | sonnet | haiku |
+| specops-research-synthesizer | sonnet | sonnet | haiku |
+| specops-debugger | opus | sonnet | sonnet |
+| specops-codebase-mapper | sonnet | haiku | haiku |
+| specops-verifier | sonnet | sonnet | haiku |
+| specops-plan-checker | sonnet | sonnet | haiku |
+| specops-integration-checker | sonnet | sonnet | haiku |
+
+## 配置理念
+
+**quality** - 最大推理能力
+- 所有决策代理使用 Opus
+- 只读验证使用 Sonnet
+- 适用场景：配额充足、关键架构工作
+
+**balanced**（默认） - 智能分配
+- 仅规划使用 Opus（架构决策发生的地方）
+- 执行和研究使用 Sonnet（遵循明确指令）
+- 验证使用 Sonnet（需要推理，不只是模式匹配）
+- 适用场景：日常开发、质量和成本的良好平衡
+
+**budget** - 最小 Opus 使用
+- 写代码的都用 Sonnet
+- 研究和验证用 Haiku
+- 适用场景：节省配额、大量工作、不太关键的阶段
+
+## 解析逻辑
+
+编排器在生成前解析模型：
+
+```
+1. 读取 .planning/config.json
+2. 检查 model_overrides 中是否有代理特定的覆盖
+3. 如果没有覆盖，在配置表中查找代理
+4. 将 model 参数传递给 Task 调用
+```
+
+## 单代理覆盖
+
+覆盖特定代理而不改变整个配置：
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "specops-executor": "opus",
+    "specops-planner": "haiku"
+  }
+}
+```
+
+覆盖优先于配置。有效值：`opus`、`sonnet`、`haiku`。
+
+## 切换配置
+
+运行时：`/specops:set-profile <profile>`
+
+项目默认：在 `.planning/config.json` 中设置：
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+## 设计原理
+
+**为什么 specops-planner 用 Opus？**
+规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。
+
+**为什么 specops-executor 用 Sonnet？**
+执行器遵循明确的 PLAN.md 指令。计划已经包含了推理；执行是实现。
+
+**为什么 balanced 中验证器用 Sonnet（不是 Haiku）？**
+验证需要目标反推推理，检查代码是否*交付*了阶段承诺的内容，而非只是模式匹配。Sonnet 处理得好；Haiku 可能遗漏细微差距。
+
+**为什么 specops-codebase-mapper 用 Haiku？**
+只读的探索和模式提取。不需要推理，只需从文件内容生成结构化输出。
+
+**为什么用 `inherit` 而不是直接传 `opus`？**
+Claude Code 的 `"opus"` 别名映射到特定模型版本。组织可能阻止旧的 opus 版本而允许新版本。SpecOps 对 opus 级别的代理返回 `"inherit"`，使它们使用用户会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。

package/.opencode/references/phase-argument-parsing.md

@@ -0,0 +1,61 @@
+# 阶段参数解析
+
+解析和规范化操作阶段的命令的阶段参数。
+
+## 提取
+
+从 `$ARGUMENTS` 中：
+- 提取阶段编号（第一个数字参数）
+- 提取标志（以 `--` 为前缀）
+- 剩余文本为描述（用于 insert/add 命令）
+
+## 使用 specops-tools
+
+`find-phase` 命令一步完成规范化和验证：
+
+```bash
+PHASE_INFO=$(node .opencode/bin/specops-tools.cjs find-phase "${PHASE}")
+```
+
+返回 JSON 包含：
+- `found`：true/false
+- `directory`：阶段目录的完整路径
+- `phase_number`：规范化的编号（如 "06"、"06.1"）
+- `phase_name`：名称部分（如 "foundation"）
+- `plans`：PLAN.md 文件数组
+- `summaries`：SUMMARY.md 文件数组
+
+## 手动规范化（遗留方式）
+
+整数阶段零填充到 2 位。保留小数后缀。
+
+```bash
+# 规范化阶段编号
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  # 整数：8 -> 08
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  # 小数：2.1 -> 02.1
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+## 验证
+
+使用 `roadmap get-phase` 验证阶段是否存在：
+
+```bash
+PHASE_CHECK=$(node .opencode/bin/specops-tools.cjs roadmap get-phase "${PHASE}")
+if [ "$(echo "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
+  echo "ERROR: Phase ${PHASE} not found in roadmap"
+  exit 1
+fi
+```
+
+## 目录查找
+
+使用 `find-phase` 进行目录查找：
+
+```bash
+PHASE_DIR=$(node .opencode/bin/specops-tools.cjs find-phase "${PHASE}" --raw)
+```

package/.opencode/references/planning-config.md

@@ -0,0 +1,196 @@
+<planning_config>
+
+`.planning/` 目录行为的配置选项。
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "phase_branch_template": "specops/phase-{phase}-{slug}",
+  "milestone_branch_template": "specops/{milestone}-{slug}"
+}
+```
+
+| 选项 | 默认值 | 说明 |
+|------|--------|------|
+| `commit_docs` | `true` | 是否将规划产物提交到 git |
+| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` |
+| `git.branching_strategy` | `"none"` | Git 分支策略：`"none"`、`"phase"` 或 `"milestone"` |
+| `git.phase_branch_template` | `"specops/phase-{phase}-{slug}"` | 阶段策略的分支模板 |
+| `git.milestone_branch_template` | `"specops/{milestone}-{slug}"` | 里程碑策略的分支模板 |
+</config_schema>
+
+<commit_docs_behavior>
+
+**当 `commit_docs: true`（默认）时：**
+- 规划文件正常提交
+- SUMMARY.md、STATE.md、ROADMAP.md 纳入 git 追踪
+- 完整保留规划决策历史
+
+**当 `commit_docs: false` 时：**
+- 跳过所有 `.planning/` 文件的 `git add`/`git commit`
+- 用户需将 `.planning/` 添加到 `.gitignore`
+- 适用场景：开源贡献、客户项目、保持规划私密
+
+**使用 specops-tools.cjs（推荐）：**
+
+```bash
+# 带自动 commit_docs + gitignore 检查的提交：
+node .opencode/bin/specops-tools.cjs commit "docs: update state" --files .planning/STATE.md
+
+# 通过 state load 加载配置（返回 JSON）：
+INIT=$(node .opencode/bin/specops-tools.cjs state load)
+# commit_docs 包含在 JSON 输出中
+
+# 或使用 init 命令，其中包含 commit_docs：
+INIT=$(node .opencode/bin/specops-tools.cjs init execute-phase "1")
+# commit_docs 包含在所有 init 命令输出中
+```
+
+**自动检测：** 如果 `.planning/` 被 gitignore，无论 config.json 如何设置，`commit_docs` 自动为 `false`。这可以防止用户在 `.gitignore` 中有 `.planning/` 时出现 git 错误。
+
+**通过 CLI 提交（自动处理检查）：**
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: update state" --files .planning/STATE.md
+```
+
+CLI 会在内部检查 `commit_docs` 配置和 gitignore 状态，无需手动条件判断。
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**当 `search_gitignored: false`（默认）时：**
+- 标准 rg 行为（遵守 .gitignore）
+- 直接路径搜索有效：`rg "pattern" .planning/` 可找到文件
+- 广泛搜索跳过被 gitignore 的内容：`rg "pattern"` 跳过 `.planning/`
+
+**当 `search_gitignored: true` 时：**
+- 在需要包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore`
+- 仅在搜索整个仓库且期望匹配 `.planning/` 内容时需要
+
+**注意：** 大多数 SpecOps 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都能正常工作。
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+要使用非提交模式：
+
+1. **设置配置：**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **添加到 .gitignore：**
+   ```
+   .planning/
+   ```
+
+3. **已追踪的文件：** 如果 `.planning/` 之前已被追踪：
+   ```bash
+   git rm -r --cached .planning/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+4. **分支合并：** 使用 `branching_strategy: phase` 或 `milestone` 时，`complete-milestone` 工作流在 `commit_docs: false` 的情况下会自动在合并提交前从暂存区移除 `.planning/` 文件。
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**分支策略：**
+
+| 策略 | 创建分支时机 | 分支范围 | 合并点 |
+|------|-------------|---------|--------|
+| `none` | 从不 | 不适用 | 不适用 |
+| `phase` | 在 `execute-phase` 开始时 | 单个阶段 | 用户在阶段完成后合并 |
+| `milestone` | 在里程碑的第一个 `execute-phase` 时 | 整个里程碑 | 在 `complete-milestone` 时 |
+
+**当 `git.branching_strategy: "none"`（默认）时：**
+- 所有工作提交到当前分支
+- 标准 SpecOps 行为
+
+**当 `git.branching_strategy: "phase"` 时：**
+- `execute-phase` 在执行前创建/切换到分支
+- 分支名来自 `phase_branch_template`（如 `specops/phase-03-authentication`）
+- 所有计划提交到该分支
+- 用户在阶段完成后手动合并分支
+- `complete-milestone` 提供合并所有阶段分支的选项
+
+**当 `git.branching_strategy: "milestone"` 时：**
+- 里程碑的第一个 `execute-phase` 创建里程碑分支
+- 分支名来自 `milestone_branch_template`（如 `specops/v1.0-mvp`）
+- 里程碑中所有阶段提交到同一分支
+- `complete-milestone` 提供将里程碑分支合并到 main 的选项
+
+**模板变量：**
+
+| 变量 | 可用于 | 说明 |
+|------|--------|------|
+| `{phase}` | phase_branch_template | 零填充的阶段编号（如 "03"） |
+| `{slug}` | 两者都可 | 小写、连字符分隔的名称 |
+| `{milestone}` | milestone_branch_template | 里程碑版本（如 "v1.0"） |
+
+**检查配置：**
+
+使用 `init execute-phase`，它以 JSON 返回所有配置：
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init execute-phase "1")
+# JSON 输出包含：branching_strategy、phase_branch_template、milestone_branch_template
+```
+
+或使用 `state load` 获取配置值：
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs state load)
+# 从 JSON 中解析 branching_strategy、phase_branch_template、milestone_branch_template
+```
+
+**分支创建：**
+
+```bash
+# 阶段策略
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# 里程碑策略
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**complete-milestone 时的合并选项：**
+
+| 选项 | Git 命令 | 结果 |
+|------|----------|------|
+| 压缩合并（推荐） | `git merge --squash` | 每个分支一个干净的提交 |
+| 保留历史合并 | `git merge --no-ff` | 保留所有单独的提交 |
+| 删除不合并 | `git branch -D` | 丢弃分支工作 |
+| 保留分支 | （无） | 稍后手动处理 |
+
+推荐压缩合并，保持主分支历史干净，同时在分支中保留完整的开发历史（直到删除）。
+
+**使用场景：**
+
+| 策略 | 最适合 |
+|------|--------|
+| `none` | 独立开发、简单项目 |
+| `phase` | 按阶段代码审查、细粒度回滚、团队协作 |
+| `milestone` | 发布分支、预发布环境、按版本 PR |
+
+</branching_strategy_behavior>
+
+</planning_config>

package/.opencode/references/questioning.md

@@ -0,0 +1,145 @@
+<questioning_guide>
+
+项目初始化是梦想提取，而非需求收集。你在帮助用户发现和表达他们想要构建的东西。这不是合同谈判，而是协作思考。
+
+<philosophy>
+
+**你是思考伙伴，不是面试官。**
+
+用户通常有一个模糊的想法。你的工作是帮助他们把它变清晰。提出让他们想到「哦，我没考虑过这个」或「是的，这正是我的意思」的问题。
+
+不要审问。要协作。不要照本宣科。要跟着线索走。
+
+</philosophy>
+
+<the_goal>
+
+提问结束时，你需要足够的清晰度来编写一个下游阶段可以据此行动的 PROJECT.md：
+
+- **研究** 需要：研究什么领域、用户已经知道什么、存在什么未知
+- **需求** 需要：足够清晰的愿景来确定 v1 特性范围
+- **路线图** 需要：足够清晰的愿景来分解为阶段、「完成」是什么样子
+- **plan-phase** 需要：具体的需求来分解为任务、实现选择的上下文
+- **execute-phase** 需要：验证的成功标准、需求背后的「为什么」
+
+模糊的 PROJECT.md 迫使每个下游阶段去猜测。成本会累积。
+
+</the_goal>
+
+<how_to_question>
+
+**从开放式开始。** 让他们倾倒脑中的模型。不要用结构打断。
+
+**跟随能量。** 他们强调了什么，就深入什么。什么让他们兴奋？什么问题触发了这个想法？
+
+**挑战模糊。** 永远不要接受模糊的回答。「好」是什么意思？「用户」是谁？「简单」是怎样的？
+
+**让抽象变具体。** 「带我走一遍使用过程。」「那实际上是什么样子？」
+
+**澄清歧义。** 「你说 Z 的时候，是指 A 还是 B？」「你提到了 X，多说说。」
+
+**知道何时停止。** 当你理解了他们想要什么、为什么想要、为谁做、以及完成是什么样子时，提议继续。
+
+</how_to_question>
+
+<question_types>
+
+把这些当作灵感，不是清单。选择与当前线索相关的。
+
+**动机 - 为什么存在：**
+- 「是什么促使了这个？」
+- 「你今天在做什么，这个要替代它？」
+- 「如果这个存在了，你会做什么？」
+
+**具体性 - 实际是什么：**
+- 「带我走一遍使用过程」
+- 「你说 X，那实际上是什么样子？」
+- 「给我一个例子」
+
+**澄清 - 他们的意思：**
+- 「你说 Z 的时候，是指 A 还是 B？」
+- 「你提到了 X，多说说」
+
+**成功 - 如何知道它在工作：**
+- 「你怎么知道这个在工作？」
+- 「完成是什么样子？」
+
+</question_types>
+
+<using_askuserquestion>
+
+使用 AskUserQuestion 通过呈现具体选项来帮助用户思考。
+
+**好的选项：**
+- 对他们可能意思的解读
+- 用于确认或否认的具体例子
+- 揭示优先级的具体选择
+
+**坏的选项：**
+- 通用类别（「技术」、「业务」、「其他」）
+- 预设答案的引导性选项
+- 太多选项（2-4 个最理想）
+- 标题超过 12 个字符（硬限制，验证会拒绝）
+
+**示例 - 模糊回答：**
+用户说「它应该很快」
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**示例 - 跟随线索：**
+用户提到「对当前工具感到沮丧」
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+**用户提示 - 修改选项：**
+想要某个选项的略微修改版本的用户可以选择「Other」并通过编号引用选项：`#1 but for finger joints only` 或 `#2 with pagination disabled`。这避免了重新输入完整的选项文本。
+
+</using_askuserquestion>
+
+<context_checklist>
+
+把这当作**后台清单**，不是对话结构。在进行中心理检查这些。如果有空白，自然地穿插问题。
+
+- [ ] 他们在构建什么（具体到能向陌生人解释）
+- [ ] 为什么需要存在（驱动它的问题或愿望）
+- [ ] 为谁做的（即使只是他们自己）
+- [ ] 「完成」是什么样子（可观察的结果）
+
+四件事。如果他们主动提供更多，记录下来。
+
+</context_checklist>
+
+<decision_gate>
+
+当你能写出清晰的 PROJECT.md 时，提议继续：
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" - Let's move forward
+  - "Keep exploring" - I want to share more / ask me more
+
+如果选择「Keep exploring」，询问他们想添加什么，或识别空白并自然地探索。
+
+循环直到选择「Create PROJECT.md」。
+
+</decision_gate>
+
+<anti_patterns>
+
+- **清单式提问** - 不管他们说了什么都遍历所有领域
+- **罐头问题** - 不管上下文都问「你的核心价值是什么？」「什么不在范围内？」
+- **企业腔** - 「你的成功标准是什么？」「你的利益相关者是谁？」
+- **审问** - 连珠炮式提问而不基于回答展开
+- **急于求成** - 最小化提问以尽快进入「工作」
+- **浅层接受** - 接受模糊回答而不深入探究
+- **过早约束** - 在理解想法之前就问技术栈
+- **用户技能** - 永远不要问用户的技术经验。Claude 来构建。
+
+</anti_patterns>
+
+</questioning_guide>