dsh-superpower 6.3.0

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

@@ -0,0 +1,167 @@
+---
+name: dispatching-parallel-agents
+description: "面向 2 个以上无共享状态、无前后依赖的独立任务，并行委派多个子智能体协同处理的高效分发模式"
+---
+
+# 并行分发智能体
+
+## 概述
+
+你将任务委派给拥有隔离上下文的专用智能体。通过精确构造指令与上下文，确保它们保持专注并成功完成任务。它们不应继承你当前会话的上下文或历史——你需要按需精确构造所需信息。这也能保留你自身的上下文，用于统筹协调工作。
+
+当存在多个互不相关的失败时（不同的测试文件、不同的子系统、不同的缺陷），串行排查会浪费大量时间。每一项排查都是独立的，可以并行进行。
+
+**核心原则：** 每个独立的问题域分派一个智能体，让它们并发执行。
+
+## 何时使用
+
+```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. 并行分发
+
+在同一条回复中一次性发起全部三个子智能体分发——它们将并行运行：
+
+```text
+Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
+Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
+Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
+# All three run concurrently.
+```
+
+在同一条回复中发起多次分发调用 = 并行执行。每条回复只发一次 = 串行执行。
+
+### 4. 复核与集成
+
+当智能体返回后：
+- 阅读每一份总结
+- 验证各修复之间是否存在冲突
+- 运行完整测试套件
+- 整合所有变更
+
+## 智能体提示词结构
+
+优秀的智能体提示词应具备：
+1. **聚焦** - 一个清晰的问题域
+2. **自包含** - 包含理解问题所需的全部上下文
+3. **输出明确** - 智能体应该返回什么？
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## 常见错误
+
+**❌ 范围过大：** "修复所有测试" - 智能体容易迷失方向
+**✅ 具体明确：** "修复 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）
+
+**决策：** 属于独立领域——中止逻辑、批量完成、竞态条件三者相互分离
+
+**分发：**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**结果：**
+- Agent 1：用基于事件的等待替代了固定超时
+- Agent 2：修复了事件结构缺陷（threadId 位置错误）
+- Agent 3：增加了对异步工具执行完成的等待
+
+**集成：** 所有修复相互独立，无冲突，全量测试通过
+
+## 验证
+
+智能体返回后：
+1. **复核每份总结** - 理解变更内容
+2. **检查是否存在冲突** - 智能体是否编辑了同一段代码？
+3. **运行全量测试** - 验证所有修复协同工作正常
+4. **抽样检查** - 智能体可能存在系统性错误

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: executing-plans
+description: "适用于已有详细实现计划的场景，在隔离会话中逐项执行、严格校验并在关键节点复核的执行流程"
+---
+
+# 执行计划
+
+## 概述
+
+加载计划、批判性复审、执行全部任务、完成后汇报。
+
+**开始时声明：** "I'm using the executing-plans skill to implement this plan."
+
+**提示：** 告知你的协作伙伴，Superpowers 在可使用 subagent 时效果更好（Claude Code、Codex CLI、Codex App、Copilot CLI 和 Gemini CLI 均符合条件；各平台工具说明见 `../using-superpowers/references/`）。如可使用 subagent，请使用 superpowers:subagent-driven-development 替代本 skill。
+
+## 执行流程
+
+### 步骤 1：加载并复审计划
+1. 确保工作区已隔离：使用 superpowers:using-git-worktrees 创建新工作区或校验现有工作区
+2. 读取计划文件
+3. 批判性复审——识别计划中的疑问或风险点
+4. 如有疑问：开始前向协作伙伴提出
+5. 如无疑问：为计划条目创建 todos 并继续执行
+
+### 步骤 2：执行任务
+
+针对每项任务：
+1. 标记为 in_progress
+2. 严格按步骤执行（计划已拆分为小粒度步骤）
+3. 按要求执行校验
+4. 标记为 completed
+
+### 步骤 3：完成开发
+
+所有任务完成并校验通过后：
+- 声明："I'm using the finishing-a-development-branch skill to complete this work."
+- **必选子 skill：** 使用 superpowers:finishing-a-development-branch
+- 按该 skill 流程校验测试、提供选项并执行所选方案
+
+## 何时停止并寻求帮助
+
+**出现以下情况时立即停止执行：**
+- 遇到阻碍（缺失依赖、测试失败、指令不清晰）
+- 计划存在关键缺口导致无法启动
+- 无法理解某条指令
+- 校验反复失败
+
+**不要猜测，主动澄清。**
+
+## 何时回溯到 earlier 步骤
+
+**回到复审（步骤 1），当：**
+- 协作伙伴根据你的反馈更新了计划
+- 基础方案需要重新思考
+
+**不要强行突破阻碍**——停下来并提问。
+
+## 牢记
+- 首先对计划进行批判性复审
+- 严格按计划步骤执行
+- 不要跳过校验
+- 计划要求引用 skill 时按要求引用
+- 受阻时停止，不要猜测
+- 未经用户明确同意，绝不在 main/master 分支上开始实现

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

@@ -0,0 +1,202 @@
+---
+name: finishing-a-development-branch
+description: "实现完成且全部测试通过后，用于决定分支集成方式，支持本地合并、创建 PR 或保留分支等完整收尾流程。"
+---
+
+# 完成开发分支
+
+## 概述
+
+**核心原则：** 验证测试 → 检测环境 → 提供选项 → 执行选择 → 清理收尾。
+
+**开始时声明：** “我将使用 finishing-a-development-branch 技能来完成收尾工作。”
+
+## 步骤 1：验证测试
+
+运行项目的完整测试套件（`npm test` / `cargo test` / `pytest` / `go test ./...`）。
+
+**若测试失败**，报告失败信息并停止——只有测试全通过后才展示选项菜单：
+
+```
+测试未通过（<N> 项失败），需修复后才能完成：
+
+[展示失败详情]
+```
+
+**若测试通过：** 继续进入步骤 2。
+
+## 步骤 2：检测环境
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+# Capture now, while still inside the workspace — Step 5 changes directory
+# before cleanup (Step 6) needs this value
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+```
+
+下表决定展示哪种菜单以及如何执行清理：
+
+| 状态 | 菜单 | 清理方式 |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON`（普通仓库） | 标准 3 项选项 | 无需清理 worktree |
+| `GIT_DIR != GIT_COMMON`，具名分支 | 标准 3 项选项 | 按来源判定（见步骤 6） |
+| `GIT_DIR != GIT_COMMON`，游离 HEAD | 精简 2 项选项（无合并） | 由外部托管——保持原样 |
+
+## 步骤 3：确定基线分支
+
+基线分支即本次工作分叉时的来源分支——通常在计划、对话记录或分支的上游中已注明。若尚未明确，请询问：“该分支是从 <你的最佳推测> 分叉出来的，这样对吗？” 合并前务必确认：合错基线分支的回滚成本很高。
+
+## 步骤 4：提供选项
+
+**普通仓库与具名分支 worktree——请严格按以下 3 项呈现：**
+
+```
+实现已完成。接下来怎么处理？
+
+1. 本地合并回 <base-branch>
+2. 推送并创建 Pull Request
+3. 保持分支现状（稍后自行处理）
+
+请选择：
+```
+
+**游离 HEAD——请严格按以下 2 项呈现：**
+
+```
+实现已完成。当前处于游离 HEAD（外部托管的工作区）。
+
+1. 以新分支推送并创建 Pull Request
+2. 保持现状（稍后自行处理）
+
+请选择：
+```
+
+请严格按原文呈现菜单——保持简洁，所有选项均来自上表。仅当人类协作者明确要求丢弃工作时才处理丢弃流程（见下文“若协作者要求丢弃工作”）。等待对方答复；集成决策权归协作者所有。
+
+## 步骤 5：执行选择
+
+### 选项 1：本地合并
+
+```bash
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+```
+
+若合并后的测试失败：立即停止，保留 worktree 与分支并展开排查——此时尚未推送，合并仅在本地，可恢复。
+
+合并结果测试通过后：清理 worktree（步骤 6），然后删除分支：
+
+```bash
+git branch -d <feature-branch>
+```
+
+### 选项 2：推送并创建 PR
+
+```bash
+git push -u origin <feature-branch>
+# From a detached HEAD, name the new branch on the remote:
+# git push origin HEAD:refs/heads/<new-branch>
+```
+
+然后针对 <base-branch> 创建 pull/merge request——优先使用代码托管平台的命令行工具，若无则使用推送后打印的创建链接——遵循仓库现有的 PR 模板与规范，并将 URL 汇报给协作者。
+
+保留 worktree——协作者将在此处理 PR 反馈并继续迭代。
+
+### 选项 3：保持现状
+
+汇报：“已保留分支 <name>，worktree 保留于 <path>。”
+
+### 若协作者要求丢弃工作
+
+此路径仅在明确要求丢弃工作时触发，需先进行确认：
+
+```
+此操作将永久删除：
+- 分支 <name>
+- 全部提交：<commit-list>
+- 位于 <path> 的 worktree
+
+请输入 'discard' 以确认。
+```
+
+等待该确切确认。确认后：
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+```
+
+然后清理 worktree（步骤 6）并强制删除分支：
+
+```bash
+git branch -D <feature-branch>
+```
+
+## 步骤 6：清理工作区
+
+**仅在选项 1 与已确认的丢弃操作中执行。** 选项 2 与选项 3 始终保留 worktree。两种调用方已切换至主仓库根目录——worktree 移除必须在 worktree 外部执行——并使用步骤 2 捕获的 `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` 值（目录切换前已保存）。
+
+**若 `GIT_DIR == GIT_COMMON`：** 普通仓库，无需清理 worktree，流程结束。
+
+**若 `WORKTREE_PATH` 位于 `.worktrees/` 或 `worktrees/` 之下：** 该 worktree 由 Superpowers 创建——由我们负责清理：
+
+```bash
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # Self-healing: clean up any stale registrations
+```
+
+**若移除被拒绝**（提示 `contains modified or untracked files`）：说明 worktree 中存在仅存于此的未提交文件——可能是计划、笔记或临时文件。切勿自行使用 `--force`。向协作者展示涉及的文件并征询意见：
+
+```bash
+git -C "$WORKTREE_PATH" status --porcelain -uall
+```
+
+```
+worktree 移除被拒绝——以下文件尚未提交：
+
+<file list>
+
+1. 清理前提交至 <branch>
+2. 移动至 <主仓库根目录>
+3. 删除（不可恢复）
+
+请选择：
+```
+
+按选择执行，随后移除 worktree。
+
+**其他情况：** 该工作区由宿主环境托管——保持原样。若平台提供了工作区退出工具，请使用它。
+
+## 快速参考
+
+| 选项 | 合并 | 推送 | 保留 Worktree | 清理分支 |
+|--------|-------|------|---------------|----------------|
+| 1. 本地合并 | 是 | - | - | 是 |
+| 2. 创建 PR | - | 是 | 是 | - |
+| 3. 保持现状 | - | - | 是 | - |
+| 丢弃（仅在明确要求时） | - | - | - | 是（强制） |
+
+## 常见借口与实际情况
+
+| 借口 | 实际情况 |
+|--------|---------|
+| “本会话早些时候测试已通过” | 请在即将集成的代码树上重新运行完整测试套件，一次通过仅能证明当时的代码树。 |
+| “他们显然想直接合并” | 集成方式由协作者决定，请呈现菜单并等待选择。 |
+| “他们似乎已完成该功能——我来提议丢弃吧” | 菜单已完整，无需额外提议，仅当协作者明确要求丢弃时才处理。 |
+| “‘好，删掉吧’也算确认” | 只有输入 `discard` 才视为有效确认并授权删除。 |
+| “PR 已提交，worktree 就是冗余了” | PR 反馈需在该 worktree 中修复，工作落盘前应予以保留。 |
+| “这个 worktree 看起来废弃了——顺手一起清理” | 仅清理位于 `.worktrees/` 或 `worktrees/` 下的 worktree，其余均归宿主环境所有。 |
+| “移除被拒——用 `--force` 收个尾就行” | 拒绝意味着文件仅存在于该 worktree，`--force` 会永久销毁它们，请向协作者展示并征询意见。 |
+| “合并后失败大概是偶发问题” | 合并结果失败则立即中止，保留分支与 worktree 以便排查。 |
+| “基线分支显然是 main” | 请确认分叉点或主动询问，合错基线的回滚成本很高。 |
+| “推送被拒——强制推送就能解决” | 推送被拒说明远端已有更新，请先排查；仅在协作者明确要求时才执行强制推送。 |

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

@@ -0,0 +1,205 @@
+---
+name: receiving-code-review
+description: "收到代码评审意见时使用，实施建议前需技术验证与澄清，适用于反馈模糊或存疑场景，强调严谨核实而非盲从"
+---
+
+# 接收代码评审
+
+## 概述
+
+代码评审需要的是技术研判，而非情绪化表演。
+
+**核心原则：** 先验证，再实施；先提问，再假设。技术正确性优先于社交舒适度。
+
+## 响应模式
+
+```
+WHEN 收到代码评审反馈时：
+
+1. 阅读：完整阅读全部反馈，不急于回应
+2. 理解：用自己的话复述需求（或提问澄清）
+3. 核实：对照代码库实际情况进行校验
+4. 评估：对当前代码库而言是否技术上合理？
+5. 回应：技术性确认或有理有据的异议
+6. 实施：一次处理一项，逐项验证
+```
+
+## 禁止的回应方式
+
+**严禁：**
+- "你完全正确！"（明确违反指令文件）
+- "好建议！" / "非常棒的反馈！"（表演式认同）
+- "我马上来实现"（未经核实就承诺）
+
+**应改为：**
+- 复述技术需求
+- 提出澄清问题
+- 若判断有误，用技术理由提出异议
+- 直接开始动手（行动胜于空话）
+
+## 处理模糊的反馈
+
+```
+IF 存在表述不清的条目：
+  停止 - 在澄清前不要实施任何内容
+  针对不清晰的条目请求澄清
+
+原因：各条目之间可能存在关联。理解不完整会导致实现错误。
+```
+
+**示例：**
+```
+你的协作人："修复 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. 检查：评审者是否了解完整上下文？
+
+IF 建议看似有误：
+  用技术理由提出异议
+
+IF 无法轻易核实：
+  直接说明："没有 [X] 我无法核实这一点。是否需要我[去调研/去询问/继续推进]？"
+
+IF 与协作人之前的决策冲突：
+  先与协作人讨论，再做决定
+```
+
+**你的协作人的原则：** "对待外部反馈——保持怀疑，但要认真核查"
+
+## 对“专业化”功能的 YAGNI 检查
+
+```
+IF 评审者建议"按规范完整实现"：
+  grep 代码库，检查实际调用情况
+
+  IF 未被调用："该接口未被调用。是否直接移除（YAGNI）？"
+  IF 已被调用：再按规范完整实现
+```
+
+**你的协作人的原则：** "你和评审者都向我汇报。如果我们不需要这个功能，就不要添加。"
+
+## 实施顺序
+
+```
+FOR 多条反馈：
+  1. 先澄清所有不清晰的项
+  2. 然后按以下顺序实施：
+      - 阻塞性问题（崩溃、安全）
+      - 简单修复（拼写、导入）
+      - 复杂修复（重构、逻辑）
+  3. 逐项单独测试
+  4. 验证无回归
+```
+
+## 何时提出异议
+
+出现以下情况时应提出异议：
+- 建议会破坏现有功能
+- 评审者缺乏完整上下文
+- 违反 YAGNI（功能未被使用）
+- 在当前技术栈下技术上不正确
+- 存在历史/兼容性原因需要保留现状
+- 与协作人的架构决策冲突
+
+**如何提出异议：**
+- 使用技术理由，而非防御性措辞
+- 提出具体问题
+- 引用可运行的测试/代码
+- 若涉及架构问题，请协作人介入
+
+**如果你不便当面提出异议：** 先点明这种顾虑，然后私下告知协作人你发现的问题。他们会欣赏你的坦诚。
+
+## 确认正确的反馈
+
+当反馈确实正确时：
+```
+✅ "已修复。[简要说明改了什么]"
+✅ "捉得好——[具体问题]。已在[位置]修复。"
+✅ [直接修复，并在代码中体现]
+
+❌ "你完全正确！"
+❌ "好建议！"
+❌ "感谢指出！"
+❌ "谢谢你的[任何内容]"
+❌ 任何形式的感谢措辞
+```
+
+**为何不说感谢：** 行动即回应。直接修复即可。代码本身就能证明你已听取反馈。
+
+**如果你发现自己正要写"感谢"：** 删掉它。改为陈述修复内容。
+
+## 优雅地纠正你的异议
+
+如果你提出异议后发现自己错了：
+```
+✅ "你是对的——我检查了 [X]，确实会 [Y]。正在实现。"
+✅ "已核实，你是正确的。我最初理解有误是因为[原因]。正在修复。"
+
+❌ 长篇道歉
+❌ 为何当初要提出异议的辩解
+❌ 过度解释
+```
+
+客观陈述纠正事实，然后继续推进。
+
+## 常见错误
+
+| 错误 | 修正方法 |
+|---------|-----|
+| 表演式认同 | 陈述需求或直接行动 |
+| 盲目实施 | 先对照代码库核实 |
+| 批量修改且不测试 | 一次一项，逐项测试 |
+| 默认评审者一定正确 | 检查是否会引发破坏 |
+| 回避异议 | 技术正确性优先于舒适度 |
+| 部分实现 | 先澄清所有条目 |
+| 无法核实仍继续推进 | 说明局限性，请求指示 |
+
+## 实际示例
+
+**表演式认同（错误）：**
+```
+评审者："移除历史遗留代码"
+❌ "你完全正确！我来移除……"
+```
+
+**技术核实（正确）：**
+```
+评审者："移除历史遗留代码"
+✅ "核查中……构建目标是 10.15+，该 API 需要 13+。为兼容旧版本仍需保留历史代码。当前实现 bundle ID 有误——是修复它，还是放弃对 13 以下版本的支持？"
+```
+
+**YAGNI（正确）：**
+```
+评审者："用数据库、日期筛选、CSV 导出完整实现指标统计"
+✅ "已 grep 代码库——没有地方调用该接口。是否直接移除（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 的顶层评论。