@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: dispatching-parallel-agents
+description: 非 plan 场景下，2+ 个独立任务需要并行派发时使用（典型：多个独立 bug 排查、多文件并行验证、多分支批量重试）。Plan 驱动场景请使用 parallel-execution。
+---
+
+# 并行分派智能体
+
+> **如果你正在执行一个 plan（来自 planning），不要用本 skill。**
+> `parallel-execution` 已经原生包含 wave 化并行调度（wave 内并发实现 + wave 间阻塞 gate + Wave FINAL 四审）。
+> 本 skill 用于 plan 之外的临时并行派发场景（多 bug 排查、多文件验证、多分支批量重试等）。
+
+## 概述
+
+你将任务委派给具有隔离上下文的专用智能体。通过精心设计它们的指令和上下文，确保它们专注并成功完成任务。它们不应继承你的会话上下文或历史记录——你要精确构造它们所需的一切。这样也能为你自己保留用于协调工作的上下文。
+
+当你遇到多个不相关的失败（不同的测试文件、不同的子系统、不同的 bug），逐一排查会浪费时间。每个排查都是独立的，可以并行进行。
+
+**核心原则：** 每个独立问题域分派一个智能体，让它们并发工作。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "存在多个失败?" [shape=diamond];
+    "它们是否独立?" [shape=diamond];
+    "单个智能体排查所有问题" [shape=box];
+    "每个问题域一个智能体" [shape=box];
+    "能否并行工作?" [shape=diamond];
+    "顺序执行智能体" [shape=box];
+    "并行分派" [shape=box];
+
+    "存在多个失败?" -> "它们是否独立?" [label="是"];
+    "它们是否独立?" -> "单个智能体排查所有问题" [label="否 - 有关联"];
+    "它们是否独立?" -> "能否并行工作?" [label="是"];
+    "能否并行工作?" -> "并行分派" [label="是"];
+    "能否并行工作?" -> "顺序执行智能体" [label="否 - 有共享状态"];
+}
+```
+
+**适用场景：**
+- 3 个以上测试文件因不同根因失败
+- 多个子系统独立出现故障
+- 每个问题无需其他问题的上下文即可理解
+- 排查之间无共享状态
+
+**不适用场景：**
+- 失败是相关的（修复一个可能修复其他的）
+- 需要理解完整的系统状态
+- 智能体之间会互相干扰
+
+## 模式
+
+### 1. 识别独立的问题域
+
+按故障分组：
+- 文件 A 测试：工具审批流程
+- 文件 B 测试：批量完成行为
+- 文件 C 测试：中止功能
+
+每个问题域是独立的——修复工具审批不会影响中止测试。
+
+### 2. 创建聚焦的智能体任务
+
+每个智能体获得：
+- **明确范围：** 一个测试文件或子系统
+- **清晰目标：** 让这些测试通过
+- **约束条件：** 不修改其他代码
+- **预期输出：** 你发现和修复内容的总结
+
+### 3. 并行分派
+
+```typescript
+// 在 Claude Code / AI 环境中
+Task("修复 agent-tool-abort.test.ts 的失败")
+Task("修复 batch-completion-behavior.test.ts 的失败")
+Task("修复 tool-approval-race-conditions.test.ts 的失败")
+// 三个任务并发运行
+```
+
+### 4. 审查与集成
+
+当智能体返回时：
+- 阅读每个总结
+- 验证修复之间没有冲突
+- 运行完整测试套件
+- 集成所有更改
+
+## 智能体提示词结构
+
+好的智能体提示词应该是：
+1. **聚焦的** - 一个清晰的问题域
+2. **自包含的** - 包含理解问题所需的所有上下文
+3. **明确输出要求** - 智能体应该返回什么？
+
+```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-tool-abort.test.ts" - 聚焦的范围
+
+**错误做法：无上下文：** "修复竞态条件" - 智能体不知道在哪里
+**正确做法：提供上下文：** 粘贴错误信息和测试名称
+
+**错误做法：无约束：** 智能体可能会重构所有代码
+**正确做法：设置约束：** "不要修改生产代码" 或 "只修复测试"
+
+**错误做法：模糊的输出要求：** "修好它" - 你不知道改了什么
+**正确做法：明确要求：** "返回根因和修改内容的总结"
+
+## 不适用的场景
+
+**关联性失败：** 修复一个可能修复其他的——先一起排查
+**需要完整上下文：** 理解问题需要看到整个系统
+**探索性调试：** 你还不知道什么坏了
+**共享状态：** 智能体会互相干扰（编辑同一文件、使用同一资源）
+
+## 实际案例
+
+**场景：** 大规模重构后，3 个文件中出现 6 个测试失败
+
+**失败情况：**
+- agent-tool-abort.test.ts：3 个失败（时序问题）
+- batch-completion-behavior.test.ts：2 个失败（工具未执行）
+- tool-approval-race-conditions.test.ts：1 个失败（执行计数 = 0）
+
+**决策：** 独立的问题域——中止逻辑、批量完成、竞态条件各自独立
+
+**分派：**
+```
+智能体 1 → 修复 agent-tool-abort.test.ts
+智能体 2 → 修复 batch-completion-behavior.test.ts
+智能体 3 → 修复 tool-approval-race-conditions.test.ts
+```
+
+**结果：**
+- 智能体 1：用基于事件的等待替换了超时
+- 智能体 2：修复了事件结构 bug（threadId 位置不对）
+- 智能体 3：添加了等待异步工具执行完成的逻辑
+
+**集成：** 所有修复互相独立，无冲突，完整测试套件全部通过
+
+**节省的时间：** 3 个问题并行解决 vs 顺序解决
+
+## 核心优势
+
+1. **并行化** - 多个排查同时进行
+2. **聚焦** - 每个智能体范围窄，需要跟踪的上下文少
+3. **独立性** - 智能体之间互不干扰
+4. **速度** - 3 个问题在 1 个问题的时间内解决
+
+## 验证
+
+智能体返回后：
+1. **审查每个总结** - 理解改了什么
+2. **检查冲突** - 智能体是否编辑了同一段代码？
+3. **运行完整套件** - 验证所有修复协同工作
+4. **抽查** - 智能体可能犯系统性错误
+
+## 实际效果
+
+来自调试会话（2025-10-03）：
+- 3 个文件中 6 个失败
+- 并行分派 3 个智能体
+- 所有排查并发完成
+- 所有修复成功集成
+- 智能体之间的更改零冲突

package/plugins/superharness/skills/exploration/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: exploration
+description: 用于只读深度探索——用户想理解代码是怎么实现的、对比多个方案/库/技术、做技术调研、看 API 用法、追溯一段历史、画依赖图、读源码、看实现细节、回答 "X 是怎么工作的"、"我们能不能用 Y" 这类问题时使用；本状态严格只读，不写代码、不改文件、不跑写命令；产出结构化分析报告，每个结论都引用 file_path:line_number
+metadata:
+  type: workflow-state
+---
+
+# Exploration —— 只读深度探索
+
+## 角色
+
+你处于只读探索态。三件事：
+
+1. **读代码、读文档、查外部资料**——回答用户的"是什么 / 怎么实现的 / 能不能 / 区别在哪"
+2. **结构化输出**——把发现整理成有断言、有证据、有引用的分析报告，而不是流水账
+3. **守住边界**——一发现需要改代码，立刻 transition 回 intake，**绝不**自己开始改
+
+**核心原则：** 探索就是探索。看清楚再下结论，下了结论给证据，**不写代码**。
+
+## 铁律
+
+```
+不写代码、不改文件、不跑任何会修改状态的命令
+```
+
+只要你的下一步是 Edit / Write / NotebookEdit / git commit / git push / 任何会落盘或改变外部状态的操作——**停下来**，先 transition_state 回 intake，让 intake 重新路由。
+
+**违反铁律的字面意思就是违反铁律的精神。** "我就改一行试试" / "我顺手把 typo 修了" / "我只是验证一下假设所以跑一下" 都不行。
+
+## 何时使用
+
+**典型触发场景：**
+
+- "X 是怎么实现的？" / "X 是什么？"
+- "我们能不能用 Y 库 / Y 方案？"
+- "A 和 B 的区别 / 取舍是什么？"
+- "这段代码为什么这么写？" / "为什么不这样做？"
+- "找出所有用到 X 的地方"
+- "画一下 X 模块的依赖关系"
+- "查一下 API Z 的用法 / 行为"
+- "调研一下 N 个方案"
+
+**不适用的场景：**
+
+- 用户明确说"改一下" / "修个 bug" / "加个功能"——回 intake，让 intake 路由到 trivial 或 brainstorming
+- 用户只是问一句话的概念问题（"什么是 SQLite WAL 模式"）——在 intake 里直接回答即可，不必切到 exploration
+- 探索做完了想顺便改——回 intake，**不要**在 exploration 里改
+
+## 工具白名单
+
+**允许：**
+
+- `Read`（读任意文件）
+- `Grep` / `Glob`（搜代码）
+- `WebFetch` / `WebSearch`（查外部文档、对比方案、找参考实现）
+- `Bash` **只读子集**：`ls`、`cat`、`head`、`tail`、`wc`、`stat`、`file`、`tree`、`pwd`
+- `Bash` **只读 git**：`git log`、`git show`、`git diff`（不带 `--apply`）、`git blame`、`git status`、`git rev-parse`、`git ls-files`、`git branch --list`、`git tag --list`
+- 同理只读 sqlite：`sqlite3 <db> .schema` / `sqlite3 <db> "SELECT ..."`
+
+**禁止：**
+
+- `Edit` / `Write` / `NotebookEdit`——任何写文件
+- 任何形式的 `git commit` / `git add` / `git push` / `git checkout <branch>` / `git merge` / `git rebase` / `git stash` / `git reset`
+- `Bash` 写命令：`>`、`>>`、`tee`、`rm`、`mv`、`cp`（目标侧写）、`mkdir`、`touch`、`chmod`、`chown`、`sed -i`、任何 `--write` / `--fix` / `--apply` 类参数
+- 任何 `npm install` / `pip install` / `cargo build` / `make` 等会产生构建产物或修改 lockfile 的命令
+- 调用 superharness MCP 的 `transition_state` 以外的写工具？**没有这类工具**——你只在转出的时候用 `transition_state`，其余时间不调用任何修改 superharness 状态的工具
+
+**判断规则：** 不确定一条命令属于读还是写？把它当成写，停下来想清楚。如果一条命令既能读也能写（如 `git checkout <file>` 会还原文件），它就是写命令。
+
+## 输出规范
+
+**最终交付物是一份结构化分析报告**，不是聊天流水。
+
+### 结构
+
+```markdown
+## 结论 / 摘要
+（2-5 句话，直接答用户的问题）
+
+## 证据
+（按发现的子主题分段，每段都有引用）
+
+### 子主题 1: <名字>
+- 观察 1：<断言> —— `plugins/superharness/workflow-state-server/state.js:42-58`
+- 观察 2：<断言> —— `docs/superharness/specs/2026-05-19-state-machine-v3-design.md:62`
+- 引用外部文档：<断言> —— [vitest run modes](https://vitest.dev/guide/cli.html)（WebFetch 摘录）
+
+### 子主题 2: <名字>
+...
+
+## 反驳 / 边界条件
+（哪些场景下结论不成立，或者你看不到证据的死角）
+
+## 建议下一步
+（如果用户接下来要做什么，应该 transition 到哪个状态——但你不替用户做决定，由 intake 路由）
+```
+
+### 引用规范
+
+- **每个断言都要有证据**。证据 = 代码引用 `file_path:line_number` 或 `file_path:line_start-line_end`，或外部链接 + 摘录
+- **断言和证据明确分开**：先说结论，再贴引用；不要把"我打开了 X 文件，看到 Y，然后我又..."这种叙事当报告
+- **不知道就说不知道**：找不到证据 → 写"未找到 / 推测，未验证"，不要硬编
+
+### 反模式（不要这样）
+
+```
+我看了一下 state.js，发现里面有一个 openWorkflowStateStore 函数，然后我又看了一下
+schema.sql，里面有两张表。然后 init.js 里调用了 openWorkflowStateStore。然后我觉得...
+```
+
+```markdown
+## 结论
+workflow-state DB 由 `openWorkflowStateStore` 单点初始化，schema 写死两张表。
+
+## 证据
+- `state.js:openWorkflowStateStore` 通过 `bun:sqlite` / `better-sqlite3` 二选一打开数据库 —— `plugins/superharness/workflow-state-server/state.js:88-104`
+- Schema 文件定义两张表：`workflow_state` 和 `workflow_transition_log` —— `plugins/superharness/workflow-state-server/schema.sql:1-30`
+- MCP server 启动时调用一次 `openWorkflowStateStore` —— `plugins/superharness/workflow-state-server/server.js:55`
+```
+
+## 完成后路径
+
+**唯一的出口是 transition 回 `intake`。** exploration 没有"直接跳别处"这条边。
+
+| 触发条件 | 行动 |
+|---|---|
+| 用户表示问题答完 / 满足 | `transition_state` → `intake`，reason 写"探索完成 + 主要结论 1 句话" |
+| 用户改主意要写代码 | `transition_state` → `intake`，reason 写"探索中用户要求改代码，回 intake 重新路由"。**不要**自己跳 trivial 或 brainstorming |
+| 探索过程中发现必须改代码才能继续验证假设 | `transition_state` → `intake`，reason 写"探索遇阻，需写代码验证，回 intake" |
+| 用户问了新问题但还是只读 | 留在 exploration 继续 |
+
+**为什么不能从 exploration 直接跳 trivial / brainstorming？** intake 是单一路由器。让 intake 重新判断范围（这次的需求是小改还是新功能），避免 exploration 里塞一份并行的"是否升级"判断逻辑，保持路由集中。
+
+## 边界守护：守住"只读"
+
+### 红线 —— 出现以下任一念头立刻停下
+
+- "让我改一下 X 看看效果"
+- "我先把这个 typo 顺手修了"
+- "我加个 console.log 试试"（这也是写）
+- "我跑一下 `npm install` 看看依赖能不能装"（修改 lockfile）
+- "我 checkout 一下别的分支看看"（动了 working tree）
+- "我建个临时文件存一下笔记"（写文件）
+- "反正就跑一次，影响小"
+
+**以上每一条都意味着：你即将违反铁律。** 处理方式：
+
+1. 停下当前操作
+2. `transition_state` → `intake`
+3. 在 reason 里说明"探索中需要执行 <某动作>，已超出只读范围，回 intake 重新路由"
+
+### 常见合理化借口
+
+| 借口 | 现实 |
+|---|---|
+| "只是改一行，不算改代码" | 一行也是改。回 intake 让 trivial 接手才有审计。 |
+| "我先在沙盒里试试" | 沙盒 = 写文件。不允许。用 Read + WebFetch 查文档替代。 |
+| "用户没说不让我改" | 用户进 exploration 就是要求你只读。默认禁止 = 显式禁止。 |
+| "改完马上还原，不会留痕" | git 历史会留痕。working tree 状态会变。不允许。 |
+| "这是为用户好——少切一次态" | 路由集中的价值高于省一次切态。回 intake。 |
+| "我就 commit 个 WIP 防止丢" | exploration 不应该有 "WIP" ——你没写东西。报告写在响应里，不写文件。 |
+
+### 探索笔记往哪写？
+
+**写在你给用户的响应里**，不写本地文件。如果报告很长，分段输出在对话里。
+
+需要长期保留分析结果？那是另一个任务——回 intake，让 intake 路由到 trivial（创建一份 `docs/.../<topic>.md`）。在 exploration 内部不允许落盘。
+
+## 速查表
+
+| 我想做的事 | 在 exploration 允许吗？ | 不允许的话怎么办 |
+|---|---|---|
+| 读源码、文档 | ✓ | —— |
+| Grep / Glob 搜代码 | ✓ | —— |
+| WebFetch / WebSearch 查外部资料 | ✓ | —— |
+| `git log` / `git show` / `git diff` | ✓ | —— |
+| `sqlite3 <db> .schema` 看 schema | ✓ | —— |
+| `sqlite3 <db> "SELECT ..."` 只读查询 | ✓ | —— |
+| 改一行代码 | ✗ | transition 回 intake |
+| 加 console.log 调试 | ✗ | transition 回 intake，让 intake 路由 trivial |
+| `npm install` 装依赖 | ✗ | transition 回 intake |
+| `git checkout <分支>` | ✗ | transition 回 intake |
+| 写笔记到 .md 文件 | ✗ | 写在对话响应里 |
+| 报告分析结论给用户 | ✓ | —— |
+| 在报告里建议下一步 | ✓ | —— |
+| 在报告里替用户决定要不要改 | ✗ | 让 intake 路由 |
+
+## 常见错误
+
+| 错误 | 修复 |
+|---|---|
+| 报告写成 "我看了 A，又看了 B" 流水账 | 改成 "结论 X，证据：A:line / B:line" |
+| 断言没有 `file_path:line_number` | 补上引用；找不到证据就标"未验证" |
+| 一边探索一边偷偷改了一个 typo | 立刻 transition 回 intake，在 reason 里如实记录"已修改 <文件>，请 intake 路由 trivial 继续" |
+| 探索完毕直接跳 brainstorming | 错。回 intake。 |
+| 在 exploration 里 commit 笔记 | 错。把笔记放在响应里。 |
+| 跑了 `npm test`（会落盘 coverage 报告） | 边界 case。如果你启用了 coverage 写出，就算写。优先看 CI 历史 / 读 test 文件本身。 |

package/plugins/superharness/skills/finishing/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: finishing
+description: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
+---
+
+# 完成开发分支
+
+## 概述
+
+通过提供清晰的选项并执行所选工作流来引导开发工作的收尾。
+
+**核心原则：** 验证测试 → 展示选项 → 执行选择 → 清理。
+
+**开始时宣布：** "我正在使用 finishing 技能来完成这项工作。"
+
+## 流程
+
+### 步骤 1：验证测试
+
+**在展示选项之前，验证测试通过：**
+
+```bash
+# 运行项目的测试套件
+npm test / cargo test / pytest / go test ./...
+```
+
+**如果测试失败：**
+```
+测试失败（<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. 在本地合并回 <base-branch>
+2. 推送并创建 Pull Request
+3. 保持分支现状（我稍后处理）
+4. 丢弃这项工作
+
+选哪个？
+```
+
+**不要添加解释** - 保持选项简洁。
+
+### 步骤 4：执行选择
+
+#### 选项 1：本地合并
+
+```bash
+# 切换到基础分支
+git checkout <base-branch>
+
+# 拉取最新代码
+git pull
+
+# 合并功能分支
+git merge <feature-branch>
+
+# 在合并结果上验证测试
+<test command>
+
+# 如果测试通过
+git branch -d <feature-branch>
+```
+
+然后：清理工作树（步骤 5）
+
+#### 选项 2：推送并创建 PR
+
+```bash
+# 推送分支
+git push -u origin <feature-branch>
+
+# 创建 PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## 摘要
+<2-3 条变更要点>
+
+## 测试计划
+- [ ] <验证步骤>
+EOF
+)"
+```
+
+然后：清理工作树（步骤 5）
+
+#### 选项 3：保持现状
+
+报告："保留分支 <name>。工作树保留在 <path>。"
+
+**不要清理工作树。**
+
+#### 选项 4：丢弃
+
+**先确认：**
+```
+这将永久删除：
+- 分支 <name>
+- 所有提交：<commit-list>
+- 工作树 <path>
+
+输入 'discard' 确认。
+```
+
+等待精确的确认。
+
+确认后：
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+然后：清理工作树（步骤 5）
+
+### 步骤 5：清理工作树
+
+**对于选项 1、2、4：**
+
+检查是否在工作树中：
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+如果是：
+```bash
+git worktree remove <worktree-path>
+```
+
+**对于选项 3：** 保留工作树。
+
+## 快速参考
+
+| 选项 | 合并 | 推送 | 保留工作树 | 清理分支 |
+|------|------|------|-----------|---------|
+| 1. 本地合并 | ✓ | - | - | ✓ |
+| 2. 创建 PR | - | ✓ | ✓ | - |
+| 3. 保持现状 | - | - | ✓ | - |
+| 4. 丢弃 | - | - | - | ✓（强制） |
+
+## 常见错误
+
+**跳过测试验证**
+- **问题：** 合并损坏的代码、创建失败的 PR
+- **修复：** 在提供选项前始终验证测试
+
+**开放式问题**
+- **问题：** "接下来该做什么？" → 含糊不清
+- **修复：** 准确展示 4 个结构化选项
+
+**自动清理工作树**
+- **问题：** 在可能还需要工作树时就删除了（选项 2、3）
+- **修复：** 只在选项 1 和 4 时清理
+
+**丢弃时不确认**
+- **问题：** 意外删除工作成果
+- **修复：** 要求输入 "discard" 确认
+
+## 红线
+
+**绝不：**
+- 在测试失败时继续
+- 合并前不验证测试结果
+- 不确认就删除工作成果
+- 未经明确请求就强制推送
+
+**始终：**
+- 在提供选项前验证测试
+- 准确展示 4 个选项
+- 选项 4 要求输入确认
+- 只在选项 1 和 4 时清理工作树
+
+## 集成
+
+**被以下技能调用：**
+- **parallel-execution**（步骤 7）- 所有任务完成后
+- **serial-execution**（步骤 5）- 所有批次完成后
+
+**配合使用：**
+- **using-git-worktrees** - 清理由该技能创建的工作树