specops 0.2.3 → 0.2.5

package/.opencode/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: dispatching-parallel-agents
+description: 面对 2 个以上独立任务时使用，这些任务之间没有共享状态或顺序依赖
+---
+
+# 并行 Agent 调度
+
+## 概述
+
+当你有多个不相关的故障（不同的测试文件、不同的子系统、不同的 bug），逐个排查是浪费时间。每个排查都是独立的，可以并行进行。
+
+**核心原则：** 每个独立问题域派发一个 agent。让它们并发工作。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "多个故障？" [shape=diamond];
+    "它们独立吗？" [shape=diamond];
+    "单个 agent 排查全部" [shape=box];
+    "每个问题域一个 agent" [shape=box];
+    "能并行工作吗？" [shape=diamond];
+    "顺序 agent" [shape=box];
+    "并行调度" [shape=box];
+
+    "多个故障？" -> "它们独立吗？" [label="是"];
+    "它们独立吗？" -> "单个 agent 排查全部" [label="否 - 相关"];
+    "它们独立吗？" -> "能并行工作吗？" [label="是"];
+    "能并行工作吗？" -> "并行调度" [label="是"];
+    "能并行工作吗？" -> "顺序 agent" [label="否 - 共享状态"];
+}
+```
+
+**适用场景：**
+- 3 个以上测试文件因不同根因失败
+- 多个子系统独立出问题
+- 每个问题无需其他问题的上下文即可理解
+- 排查之间没有共享状态
+
+**不适用场景：**
+- 故障相关（修一个可能修好其他的）
+- 需要理解完整系统状态
+- agent 之间会互相干扰
+
+## 模式
+
+### 1. 识别独立域
+
+按故障分组：
+- 文件 A 测试：工具审批流程
+- 文件 B 测试：批量完成行为
+- 文件 C 测试：中止功能
+
+每个域都是独立的，修复工具审批不会影响中止测试。
+
+### 2. 创建聚焦的 Agent 任务
+
+每个 agent 获得：
+- **明确范围：** 一个测试文件或子系统
+- **清晰目标：** 让这些测试通过
+- **约束条件：** 不要修改其他代码
+- **预期输出：** 发现和修复的摘要
+
+### 3. 并行调度
+
+```typescript
+// 在 opencode 环境中
+task(run_in_background=true, prompt="修复 agent-tool-abort.test.ts 的失败")
+task(run_in_background=true, prompt="修复 batch-completion-behavior.test.ts 的失败")
+task(run_in_background=true, prompt="修复 tool-approval-race-conditions.test.ts 的失败")
+// 三个并发运行
+```
+
+### 4. 审查与集成
+
+agent 返回后：
+- 阅读每个摘要
+- 验证修复不冲突
+- 运行完整测试套件
+- 集成所有变更
+
+## Agent 提示词结构
+
+好的 agent 提示词应该：
+1. **聚焦** - 一个清晰的问题域
+2. **自包含** - 理解问题所需的所有上下文
+3. **明确输出** - agent 应该返回什么？
+
+```markdown
+修复 src/agents/agent-tool-abort.test.ts 中的 3 个失败测试：
+
+1. "should abort tool with partial output capture" - 期望消息中包含 'interrupted at'
+2. "should handle mixed completed and aborted tools" - 快速工具被中止而非完成
+3. "should properly track pendingToolCount" - 期望 3 个结果但得到 0
+
+这些是时序/竞态条件问题。你的任务：
+
+1. 阅读测试文件，理解每个测试验证什么
+2. 找到根因 - 是时序问题还是实际 bug？
+3. 修复方式：
+   - 用基于事件的等待替换任意超时
+   - 如果发现中止实现的 bug 则修复
+   - 如果测试的是已变更的行为则调整测试期望
+
+不要只是增加超时 - 找到真正的问题。
+
+返回：你发现了什么以及修复了什么的摘要。
+```
+
+## 常见错误
+
+**❌ 范围太广：** "修复所有测试" - agent 会迷失
+**✅ 具体：** "修复 agent-tool-abort.test.ts" - 聚焦的范围
+
+**❌ 没有上下文：** "修复竞态条件" - agent 不知道在哪
+**✅ 有上下文：** 粘贴错误信息和测试名称
+
+**❌ 没有约束：** agent 可能重构所有东西
+**✅ 有约束：** "不要修改生产代码" 或 "只修复测试"
+
+**❌ 输出模糊：** "修好它" - 你不知道改了什么
+**✅ 输出明确：** "返回根因和变更的摘要"
+
+## 何时不使用
+
+**相关故障：** 修一个可能修好其他的，先一起排查
+**需要完整上下文：** 理解问题需要看整个系统
+**探索性调试：** 你还不知道什么坏了
+**共享状态：** agent 会互相干扰（编辑同一文件、使用同一资源）
+
+## 真实案例
+
+**场景：** 大规模重构后 3 个文件中有 6 个测试失败
+
+**失败情况：**
+- agent-tool-abort.test.ts：3 个失败（时序问题）
+- batch-completion-behavior.test.ts：2 个失败（工具未执行）
+- tool-approval-race-conditions.test.ts：1 个失败（执行次数 = 0）
+
+**决策：** 独立域 - 中止逻辑与批量完成与竞态条件各自独立
+
+**调度：**
+```
+Agent 1 → 修复 agent-tool-abort.test.ts
+Agent 2 → 修复 batch-completion-behavior.test.ts
+Agent 3 → 修复 tool-approval-race-conditions.test.ts
+```
+
+**结果：**
+- Agent 1：用基于事件的等待替换了超时
+- Agent 2：修复了事件结构 bug（threadId 位置错误）
+- Agent 3：添加了异步工具执行完成的等待
+
+**集成：** 所有修复独立，无冲突，完整套件全绿
+
+**节省时间：** 3 个问题并行解决 vs 顺序解决
+
+## 核心收益
+
+1. **并行化** - 多个排查同时进行
+2. **聚焦** - 每个 agent 范围窄，需要跟踪的上下文少
+3. **独立性** - agent 互不干扰
+4. **速度** - 3 个问题在 1 个问题的时间内解决
+
+## 验证
+
+agent 返回后：
+1. **审查每个摘要** - 理解改了什么
+2. **检查冲突** - agent 是否编辑了同一段代码？
+3. **运行完整套件** - 验证所有修复协同工作
+4. **抽查** - agent 可能犯系统性错误
+
+## 实际影响
+
+来自调试会话（2025-10-03）：
+- 3 个文件中 6 个失败
+- 3 个 agent 并行调度
+- 所有排查并发完成
+- 所有修复成功集成
+- agent 变更之间零冲突

package/.opencode/skills/executing-plans/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: executing-plans
+description: "有写好的实现计划需要在单独会话中执行时使用，带审查检查点"
+triggers:
+  - "执行计划"
+  - "实现计划"
+  - "按计划开发"
+  - "分批执行"
+---
+
+# 执行计划
+
+## 概述
+
+加载计划，批判性审查，分批执行任务，批次之间报告等待审查。
+
+**核心原则：** 分批执行，带检查点供架构师审查。
+
+**开始时宣布：** "我正在使用 executing-plans skill 来实现这个计划。"
+
+## 流程
+
+### 步骤 1：加载并审查计划
+1. 读取计划文件
+2. 批判性审查，找出任何问题或疑虑
+3. 如果有疑虑：在开始之前向你的人类搭档提出
+4. 如果没有疑虑：创建 TodoWrite 并继续
+
+### 步骤 2：执行批次
+**默认：前 3 个任务**
+
+对每个任务：
+1. 标记为 in_progress
+2. 严格按照每一步执行（计划已经拆成了小步骤）
+3. 按要求运行验证
+4. 标记为 completed
+
+### 步骤 3：报告
+批次完成时：
+- 展示实现了什么
+- 展示验证输出
+- 说："等待反馈。"
+
+### 步骤 4：继续
+根据反馈：
+- 如果需要就应用修改
+- 执行下一批次
+- 重复直到完成
+
+### 步骤 5：完成开发
+
+所有任务完成并验证后：
+- 先运行 specops acceptance runner 进行验收测试
+- 宣布："我正在使用 finishing-a-development-branch skill 来完成这项工作。"
+- **必须使用的子 SKILL：** 使用 specops:finishing-a-development-branch
+- 按照那个 skill 来验证测试、展示选项、执行选择
+
+## 什么时候停下来求助
+
+**遇到以下情况立即停止执行：**
+- 批次中途遇到阻塞（缺少依赖、测试失败、指令不清楚）
+- 计划有关键缺口导致无法开始
+- 你不理解某条指令
+- 验证反复失败
+
+**宁可问清楚，也不要猜。**
+
+## 什么时候回到前面的步骤
+
+**回到审查（步骤 1）的情况：**
+- 搭档根据你的反馈更新了计划
+- 根本方案需要重新思考
+
+**不要硬闯阻塞** - 停下来问。
+
+## 注意事项
+- 先批判性审查计划
+- 严格按照计划步骤执行
+- 不要跳过验证
+- 计划提到的 skill 要引用
+- 批次之间：只报告，然后等待
+- 遇到阻塞就停下来，不要猜
+- 未经用户明确同意，永远不要在 main/master 分支上开始实现
+
+## 集成
+
+**必需的工作流 skill：**
+- **specops:using-git-worktrees** - 必需：开始之前搭建隔离的工作空间
+- **specops:writing-plans** - 创建本 skill 要执行的计划
+- **specops:finishing-a-development-branch** - 所有任务完成后收尾开发

package/.opencode/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: finishing-a-development-branch
+description: 实现完成、所有测试通过后使用，指导如何集成工作，提供合并、PR 或清理的结构化选项
+---
+
+# 完成开发分支
+
+## 概述
+
+指导开发工作的收尾，提供清晰的选项并处理所选的工作流。
+
+**核心原则：** 验证测试 → 运行验收 → 展示选项 → 执行选择 → 清理。
+
+**开始时宣布：** "我正在使用 finishing-a-development-branch skill 来完成这项工作。"
+
+## 流程
+
+### 步骤 1：验证测试
+
+**展示选项之前，先验证测试通过：**
+
+```bash
+# 运行项目的测试套件
+npm test / cargo test / pytest / go test ./...
+```
+
+**如果测试失败：**
+```
+测试失败（<N> 个失败）。完成前必须修复：
+
+[展示失败信息]
+
+测试通过前无法进行合并/PR。
+```
+
+停下。不要进入步骤 2。
+
+**如果测试通过：** 继续步骤 2。
+
+### 步骤 1.5：运行 specops 验收
+
+**测试通过后，运行 specops 验收运行器确认全部通过：**
+
+```bash
+# 运行 specops 验收检查
+specops verify
+```
+
+**如果验收失败：**
+```
+验收检查未通过（<N> 项失败）。完成前必须修复：
+
+[展示失败项]
+
+验收全部通过前无法进行合并/PR。
+```
+
+停下。不要进入步骤 2。
+
+**如果验收通过：** 继续步骤 2。
+
+### 步骤 2：确定基准分支
+
+```bash
+# 尝试常见的基准分支
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+或者询问："这个分支是从 main 分出来的，对吗？"
+
+### 步骤 3：展示选项
+
+展示恰好这 4 个选项：
+
+```
+实现完成。你想怎么做？
+
+1. 本地合并回 <基准分支>
+2. 推送并创建 Pull Request
+3. 保持分支现状（我稍后处理）
+4. 丢弃这项工作
+
+选哪个？
+```
+
+**不要添加解释** - 保持选项简洁。
+
+### 步骤 4：执行选择
+
+#### 选项 1：本地合并
+
+```bash
+# 切换到基准分支
+git checkout <基准分支>
+
+# 拉取最新
+git pull
+
+# 合并功能分支
+git merge <功能分支>
+
+# 在合并结果上验证测试
+<测试命令>
+
+# 如果测试通过
+git branch -d <功能分支>
+```
+
+然后：清理工作树（步骤 5）
+
+#### 选项 2：推送并创建 PR
+
+```bash
+# 推送分支
+git push -u origin <功能分支>
+
+# 创建 PR
+gh pr create --title "<标题>" --body "$(cat <<'EOF'
+## 摘要
+<2-3 条变更要点>
+
+## 测试计划
+- [ ] <验证步骤>
+EOF
+)"
+```
+
+然后：清理工作树（步骤 5）
+
+#### 选项 3：保持现状
+
+报告："保持分支 <名称>。工作树保留在 <路径>。"
+
+**不要清理工作树。**
+
+#### 选项 4：丢弃
+
+**先确认：**
+```
+这将永久删除：
+- 分支 <名称>
+- 所有提交：<提交列表>
+- 工作树 <路径>
+
+输入 'discard' 确认。
+```
+
+等待精确确认。
+
+确认后：
+```bash
+git checkout <基准分支>
+git branch -D <功能分支>
+```
+
+然后：清理工作树（步骤 5）
+
+### 步骤 5：清理工作树
+
+**选项 1、2、4：**
+
+检查是否在工作树中：
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+如果是：
+```bash
+git worktree remove <工作树路径>
+```
+
+**选项 3：** 保留工作树。
+
+## 快速参考
+
+| 选项 | 合并 | 推送 | 保留工作树 | 清理分支 |
+|------|------|------|------------|----------|
+| 1. 本地合并 | ✓ | - | - | ✓ |
+| 2. 创建 PR | - | ✓ | ✓ | - |
+| 3. 保持现状 | - | - | ✓ | - |
+| 4. 丢弃 | - | - | - | ✓（强制） |
+
+## 常见错误
+
+**跳过测试验证**
+- **问题：** 合并了坏代码，创建了失败的 PR
+- **修正：** 展示选项前始终验证测试
+
+**开放式提问**
+- **问题：** "接下来该做什么？" → 模糊
+- **修正：** 展示恰好 4 个结构化选项
+
+**自动清理工作树**
+- **问题：** 可能还需要时移除了工作树（选项 2、3）
+- **修正：** 只在选项 1 和 4 时清理
+
+**丢弃不确认**
+- **问题：** 意外删除工作
+- **修正：** 要求输入 "discard" 确认
+
+## 红线
+
+**绝对不要：**
+- 测试失败时继续
+- 不验证合并结果的测试就合并
+- 不确认就删除工作
+- 未经明确要求就 force-push
+
+**始终：**
+- 展示选项前验证测试
+- 展示恰好 4 个选项
+- 选项 4 要求输入确认
+- 只在选项 1 和 4 时清理工作树
+
+## 集成
+
+**被调用方：**
+- **specops:subagent-driven-development**（步骤 7）- 所有任务完成后
+- **specops:executing-plans**（步骤 5）- 所有批次完成后
+
+**配合使用：**
+- **specops:using-git-worktrees** - 清理该 skill 创建的工作树

package/.opencode/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: receiving-code-review
+description: 收到代码审查反馈后、实现建议前使用，尤其当反馈不清楚或技术上有疑问时，需要技术严谨性和验证，而非表演性认同或盲目实现
+---
+
+# 接收代码审查
+
+## 概述
+
+代码审查需要技术评估，不是情绪表演。
+
+**核心原则：** 先验证再实现。先提问再假设。技术正确性优先于社交舒适。
+
+## 回应模式
+
+```
+收到代码审查反馈时：
+
+1. 阅读：完整阅读反馈，不要急于反应
+2. 理解：用自己的话复述需求（或提问）
+3. 验证：对照代码库实际情况检查
+4. 评估：对这个代码库来说技术上合理吗？
+5. 回应：技术性确认或有理有据的反驳
+6. 实现：一次一项，每项都测试
+```
+
+## 禁止的回应
+
+**绝对不要：**
+- "你说得太对了！"（明确违反 CLAUDE.md）
+- "好观点！" / "很好的反馈！"（表演性的）
+- "让我现在就实现"（验证之前）
+
+**应该：**
+- 复述技术需求
+- 提出澄清问题
+- 如果有误，用技术理由反驳
+- 直接开始做（行动 > 言语）
+
+## 处理不清楚的反馈
+
+```
+如果任何一项不清楚：
+  停下 - 先不要实现任何东西
+  对不清楚的项目提问
+
+为什么：各项可能相关。部分理解 = 错误实现。
+```
+
+**示例：**
+```
+你的人类搭档："修复 1-6"
+你理解 1,2,3,6。4,5 不清楚。
+
+❌ 错误：先实现 1,2,3,6，之后再问 4,5
+✅ 正确："我理解第 1,2,3,6 项。第 4 和第 5 项需要澄清后再继续。"
+```
+
+## 按来源处理
+
+### 来自你的人类搭档
+- **可信** - 理解后实现
+- **仍然要问** 如果范围不清楚
+- **不要表演性认同**
+- **直接行动** 或技术性确认
+
+### 来自外部审查者
+```
+实现之前：
+  1. 检查：对这个代码库来说技术上正确吗？
+  2. 检查：会破坏现有功能吗？
+  3. 检查：当前实现的原因是什么？
+  4. 检查：在所有平台/版本上都可用吗？
+  5. 检查：审查者是否理解完整上下文？
+
+如果建议似乎有误：
+  用技术理由反驳
+
+如果无法轻易验证：
+  说明："我无法在没有 [X] 的情况下验证这一点。我应该 [调查/询问/继续]？"
+
+如果与你的人类搭档之前的决策冲突：
+  先停下来和你的人类搭档讨论
+```
+
+**你的人类搭档的规则：** "外部反馈 - 保持怀疑，但仔细检查"
+
+## 对"专业"功能的 YAGNI 检查
+
+```
+如果审查者建议"正确实现"：
+  在代码库中搜索实际使用情况
+
+  如果未使用："这个端点没有被调用。移除它（YAGNI）？"
+  如果在用：那就正确实现
+```
+
+**你的人类搭档的规则：** "你和审查者都向我汇报。如果我们不需要这个功能，就不要加。"
+
+## 实现顺序
+
+```
+对于多项反馈：
+  1. 先澄清所有不清楚的项目
+  2. 然后按此顺序实现：
+     - 阻塞性问题（崩溃、安全）
+     - 简单修复（拼写、导入）
+     - 复杂修复（重构、逻辑）
+  3. 每个修复单独测试
+  4. 验证没有回归
+```
+
+## 何时反驳
+
+在以下情况反驳：
+- 建议会破坏现有功能
+- 审查者缺乏完整上下文
+- 违反 YAGNI（未使用的功能）
+- 对这个技术栈来说技术上不正确
+- 存在遗留/兼容性原因
+- 与你的人类搭档的架构决策冲突
+
+**如何反驳：**
+- 用技术理由，不要防御性
+- 提出具体问题
+- 引用可用的测试/代码
+- 如果涉及架构，让你的人类搭档参与
+
+**如果不方便大声反驳的信号：** "Strange things are afoot at the Circle K"
+
+## 确认正确的反馈
+
+当反馈确实正确时：
+```
+✅ "已修复。[简要描述改了什么]"
+✅ "好发现 - [具体问题]。已在 [位置] 修复。"
+✅ [直接修复并在代码中展示]
+
+❌ "你说得太对了！"
+❌ "好观点！"
+❌ "感谢指出！"
+❌ "感谢 [任何东西]"
+❌ 任何感谢表达
+```
+
+**为什么不感谢：** 行动说明一切。直接修复就好。代码本身就表明你听到了反馈。
+
+**如果你发现自己要写"感谢"：** 删掉它。改为描述修复内容。
+
+## 优雅地纠正你的反驳
+
+如果你反驳了但发现自己错了：
+```
+✅ "你是对的 - 我检查了 [X]，它确实 [Y]。现在实现。"
+✅ "验证了这一点，你是正确的。我最初的理解有误，因为 [原因]。修复中。"
+
+❌ 长篇道歉
+❌ 为什么反驳做辩护
+❌ 过度解释
+```
+
+陈述事实，继续前进。
+
+## 常见错误
+
+| 错误 | 修正 |
+|------|------|
+| 表演性认同 | 复述需求或直接行动 |
+| 盲目实现 | 先对照代码库验证 |
+| 批量处理不测试 | 一次一项，每项测试 |
+| 假设审查者正确 | 检查是否会破坏东西 |
+| 回避反驳 | 技术正确性 > 舒适 |
+| 部分实现 | 先澄清所有项目 |
+| 无法验证就继续 | 说明限制，请求指导 |
+
+## 真实案例
+
+**表演性认同（错误）：**
+```
+审查者："移除遗留代码"
+❌ "你说得太对了！让我移除..."
+```
+
+**技术验证（正确）：**
+```
+审查者："移除遗留代码"
+✅ "检查中... 构建目标是 10.15+，这个 API 需要 13+。需要遗留代码来向后兼容。当前实现的 bundle ID 有误 - 修复它还是放弃 pre-13 支持？"
+```
+
+**YAGNI（正确）：**
+```
+审查者："实现完整的指标追踪，包括数据库、日期过滤、CSV 导出"
+✅ "搜索了代码库 - 没有任何地方调用这个端点。移除它（YAGNI）？还是有我遗漏的使用场景？"
+```
+
+**不清楚的项目（正确）：**
+```
+你的人类搭档："修复第 1-6 项"
+你理解 1,2,3,6。4,5 不清楚。
+✅ "理解 1,2,3,6。第 4 和第 5 项需要澄清后再实现。"
+```
+
+## GitHub 评论回复
+
+在 GitHub 上回复行内审查评论时，在评论线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），不要作为顶层 PR 评论。
+
+## 底线
+
+**外部反馈 = 需要评估的建议，不是必须执行的命令。**
+
+验证。质疑。然后实现。
+
+不要表演性认同。始终保持技术严谨。