sdd-full 4.0.0 → 4.2.0

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

@@ -0,0 +1,182 @@
+---
+name: dispatching-parallel-agents
+description: 当面对 2 个以上可以独立进行、无共享状态或顺序依赖的任务时使用
+---
+
+# 并行分派智能体
+
+## 概述
+
+你将任务委派给具有隔离上下文的专用智能体。通过精心设计它们的指令和上下文，确保它们专注并成功完成任务。它们不应继承你的会话上下文或历史记录——你要精确构造它们所需的一切。这样也能为你自己保留用于协调工作的上下文。
+
+当你遇到多个不相关的失败（不同的测试文件、不同的子系统、不同的 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/skills/executing-plans/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: executing-plans
+description: 当你有一份书面实现计划需要在单独的会话中执行，并设有审查检查点时使用
+---
+
+# 执行计划
+
+## 概述
+
+加载计划，批判性审查，执行所有任务，完成后报告。
+
+**开始时宣布：** "我正在使用 executing-plans 技能来实现此计划。"
+
+**注意：** 告诉你的人类伙伴，Superpowers 在有子代理支持时效果好得多。如果在支持子代理的平台上运行（如 Claude Code 或 Codex），其工作质量会显著提高。如果子代理可用，请使用 superpowers:subagent-driven-development 而非此技能。
+
+## 流程
+
+### 步骤 1：加载并审查计划
+
+1. 读取计划文件
+2. 批判性审查——识别计划中的任何问题或疑虑
+3. 如果有疑虑：在开始之前向你的人类伙伴提出
+4. 如果没有疑虑：创建 TodoWrite 并继续
+
+**审查时重点检查：**
+- 步骤之间是否有依赖遗漏？（A 依赖 B，但 B 排在 A 之后）
+- 验证条件是否明确？（"确认可用"不算，"运行 `npm test` 全部通过"才算）
+- 是否有隐含的环境假设？（Node 版本、数据库连接、API Key）
+
+**审查示例：**
+```
+计划文件：docs/plan.md
+任务清单：5 个任务
+
+审查发现：
+- 任务 3（添加数据库迁移）应在任务 2（编写数据模型）之后，顺序正确 ✓
+- 任务 4 的验证条件写的是"确认功能正常"→ 需澄清：具体跑什么测试？
+- 计划未提及 Python 版本要求 → 需确认
+
+向伙伴提出：
+"计划整体可执行。有两个问题：(1) 任务 4 的验证条件不够具体，建议改为
+'运行 pytest tests/test_api.py 全部通过'；(2) 需要确认 Python 版本要求。"
+```
+
+### 步骤 2：执行任务
+
+对于每个任务：
+
+1. **标记为进行中** — 更新 TodoWrite
+2. **理解目标** — 重读任务描述，明确完成标准
+3. **执行实现** — 严格按照计划步骤执行（计划已有小步骤）
+4. **运行验证** — 按要求运行测试或检查
+5. **提交变更** — 每完成一个任务提交一次，commit message 引用任务编号
+6. **标记为已完成** — 更新 TodoWrite
+
+**每个任务的节奏：**
+```
+--- 任务 2/5：添加用户验证 ---
+[标记进行中]
+
+目标：为 /api/users 添加输入验证
+完成标准：所有验证测试通过，无效输入返回 400
+
+[实现]
+- 添加 validateUser() 中间件
+- 编写 3 个验证规则（email 格式、密码强度、用户名长度）
+
+[验证]
+$ npm test -- --grep "validation"
+  ✓ 拒绝无效 email (12ms)
+  ✓ 拒绝弱密码 (8ms)
+  ✓ 拒绝过长用户名 (5ms)
+  3 passing
+
+[提交]
+$ git add src/middleware/validate.js tests/validation.test.js
+$ git commit -m "feat: 添加用户输入验证（任务 2/5）"
+
+[标记完成]
+--- 任务 2/5 完成 ---
+```
+
+**批量审查检查点：**
+- 每完成 3 个任务后，暂停回顾：整体方向还对吗？有没有偏离计划？
+- 如果发现前面的实现有问题，先修复再继续，不要带着问题往下走
+
+### 步骤 3：处理常见异常
+
+**测试失败：**
+1. 读错误信息，定位失败原因
+2. 区分：是实现 bug？还是测试本身有问题？还是计划描述有误？
+3. 实现 bug → 修复并重跑
+4. 测试有问题 → 修复测试，向伙伴说明
+5. 计划有误 → 停下来，向伙伴报告并建议修正
+
+**依赖缺失：**
+```
+任务 3 需要 Redis 连接，但计划中没有提及 Redis 配置。
+→ 停止执行
+→ 向伙伴报告："任务 3 需要 Redis，计划中未包含配置步骤。
+   建议：在任务 3 前插入 '配置 Redis 连接' 步骤。"
+```
+
+**指令不清：**
+- 不要猜测意图，不要"合理推断"
+- 列出你的理解和困惑，让伙伴澄清
+- 等待回复后再继续
+
+### 步骤 4：完成开发
+
+所有任务完成并验证后：
+- 宣布："我正在使用 finishing-a-development-branch 技能来完成此工作。"
+- **必需子技能：** 使用 superpowers:finishing-a-development-branch
+- 按照该技能的指引验证测试、展示选项、执行选择
+
+**完成报告模板：**
+```
+## 执行报告
+
+**计划：** docs/plan.md
+**分支：** feature/user-validation
+**任务：** 5/5 已完成
+
+### 完成的任务
+1. ✅ 初始化项目结构
+2. ✅ 添加用户验证
+3. ✅ 添加数据库迁移
+4. ✅ 实现 API 端点
+5. ✅ 添加集成测试
+
+### 验证结果
+- 单元测试：23/23 通过
+- 集成测试：8/8 通过
+- lint 检查：0 个警告
+
+### 偏离计划的地方
+- 任务 3：Redis 配置从 env 改为 config.yaml（经伙伴同意）
+
+### 下一步
+按 finishing-a-development-branch 技能处理合并/PR
+```
+
+## 何时停下来求助
+
+**在以下情况立即停止执行：**
+- 遇到阻塞（缺少依赖、测试失败、指令不清）
+- 计划有严重缺陷导致无法开始
+- 你不理解某条指令
+- 验证反复失败（同一测试失败 2 次以上）
+
+**不确定时就问，不要猜测。**
+
+## 何时回到之前的步骤
+
+**回到审查（步骤 1）当：**
+- 伙伴根据你的反馈更新了计划
+- 根本性的方案需要重新考虑
+
+**不要硬闯阻塞** — 停下来问。
+
+## 注意事项
+- 先批判性审查计划
+- 严格按照计划步骤执行
+- 不要跳过验证
+- 每个任务单独提交，commit message 引用任务编号
+- 计划要求时引用相应技能
+- 遇到阻塞时停下来，不要猜测
+- 未经用户明确同意，绝不在 main/master 分支上开始实现
+
+## 集成
+
+**必需的工作流技能：**
+- **superpowers:using-git-worktrees** - 必需：开始前建立隔离的工作空间
+- **superpowers:writing-plans** - 创建此技能要执行的计划
+- **superpowers:finishing-a-development-branch** - 所有任务完成后收尾开发

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

@@ -0,0 +1,200 @@
+---
+name: finishing-a-development-branch
+description: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
+---
+
+# 完成开发分支
+
+## 概述
+
+通过提供清晰的选项并执行所选工作流来引导开发工作的收尾。
+
+**核心原则：** 验证测试 → 展示选项 → 执行选择 → 清理。
+
+**开始时宣布：** "我正在使用 finishing-a-development-branch 技能来完成这项工作。"
+
+## 流程
+
+### 步骤 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 时清理工作树
+
+## 集成
+
+**被以下技能调用：**
+- **subagent-driven-development**（步骤 7）- 所有任务完成后
+- **executing-plans**（步骤 5）- 所有批次完成后
+
+**配合使用：**
+- **using-git-worktrees** - 清理由该技能创建的工作树