superpowers-zh 1.7.12 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/.claude-plugin/marketplace.json +3 -3
  2. package/.claude-plugin/plugin.json +2 -2
  3. package/.codex-plugin/plugin.json +1 -1
  4. package/.cursor-plugin/plugin.json +2 -2
  5. package/.opencode/INSTALL.md +82 -14
  6. package/.opencode/plugins/superpowers.js +319 -31
  7. package/GEMINI.md +3 -2
  8. package/README.md +68 -36
  9. package/README.zh-Hant.md +66 -37
  10. package/RELEASE-NOTES.zh.md +154 -0
  11. package/assets/sponsors/88api.jpg +0 -0
  12. package/assets/sponsors/apinebula.png +0 -0
  13. package/assets/sponsors/logo-infistar-icon.png +0 -0
  14. package/assets/sponsors/logo-sidrune-ai.png +0 -0
  15. package/assets/sponsors/logo-volcengine-icon.png +0 -0
  16. package/assets/sponsors/volcengine.png +0 -0
  17. package/bin/superpowers-zh.js +21 -2
  18. package/docs/README.aider.md +2 -2
  19. package/docs/README.claw.md +1 -1
  20. package/docs/README.cline.md +3 -3
  21. package/docs/README.codearts.md +1 -1
  22. package/docs/README.codebuddy.md +1 -1
  23. package/docs/README.codex.md +26 -0
  24. package/docs/README.crush.md +1 -1
  25. package/docs/README.deepseek-harness.md +1 -1
  26. package/docs/README.deerflow.md +1 -1
  27. package/docs/README.hermes.md +1 -1
  28. package/docs/README.kilocode.md +3 -3
  29. package/docs/README.kiro.md +1 -1
  30. package/docs/README.opencode.md +128 -19
  31. package/docs/README.qoder.md +1 -1
  32. package/docs/README.qwen.md +1 -1
  33. package/docs/README.trae-cn.md +62 -0
  34. package/docs/README.vscode.md +1 -1
  35. package/docs/README.zcode.md +2 -2
  36. package/gemini-extension.json +1 -1
  37. package/hooks/run-hook.cmd +34 -18
  38. package/hooks/session-start +45 -9
  39. package/index.js +9 -0
  40. package/package.json +4 -3
  41. package/skills/brainstorming/SKILL.md +111 -181
  42. package/skills/brainstorming/builder-check-prompt.md +15 -0
  43. package/skills/brainstorming/scripts/server.cjs +1 -1
  44. package/skills/brainstorming/visual-companion.md +36 -33
  45. package/skills/chinese-code-review/SKILL.md +1 -1
  46. package/skills/chinese-commit-conventions/SKILL.md +1 -1
  47. package/skills/diagnosing-superpowers/SKILL.md +102 -0
  48. package/skills/diagnosing-superpowers/prompts/analyst-common.md +32 -0
  49. package/skills/diagnosing-superpowers/prompts/cost-and-time.md +20 -0
  50. package/skills/diagnosing-superpowers/prompts/plan-adherence.md +21 -0
  51. package/skills/diagnosing-superpowers/prompts/quality-evidence.md +20 -0
  52. package/skills/diagnosing-superpowers/prompts/repeated-work.md +24 -0
  53. package/skills/diagnosing-superpowers/prompts/request-conflicts.md +14 -0
  54. package/skills/diagnosing-superpowers/prompts/scrub-audit.md +26 -0
  55. package/skills/diagnosing-superpowers/prompts/scrub.md +22 -0
  56. package/skills/diagnosing-superpowers/prompts/similar-session.md +34 -0
  57. package/skills/diagnosing-superpowers/prompts/skill-timeline.md +23 -0
  58. package/skills/diagnosing-superpowers/prompts/stumbles.md +20 -0
  59. package/skills/diagnosing-superpowers/references/context-safety.md +20 -0
  60. package/skills/diagnosing-superpowers/references/github-issues.md +46 -0
  61. package/skills/diagnosing-superpowers/references/redaction-policy.md +29 -0
  62. package/skills/diagnosing-superpowers/references/session-discovery.md +23 -0
  63. package/skills/diagnosing-superpowers/templates/bundle-README.md +65 -0
  64. package/skills/diagnosing-superpowers/templates/case.md +61 -0
  65. package/skills/diagnosing-superpowers/templates/issue.md +48 -0
  66. package/skills/diagnosing-superpowers/templates/report.md +78 -0
  67. package/skills/executing-plans/SKILL.md +176 -125
  68. package/skills/executing-plans/scripts/task-done +52 -0
  69. package/skills/executing-plans/scripts/task-start +28 -0
  70. package/skills/mcp-builder/SKILL.md +1 -1
  71. package/skills/requesting-code-review/SKILL.md +2 -2
  72. package/skills/requesting-code-review/code-reviewer.md +8 -0
  73. package/skills/subagent-driven-development/SKILL.md +17 -17
  74. package/skills/subagent-driven-development/re-review-prompt.md +1 -1
  75. package/skills/subagent-driven-development/scripts/review-package +8 -1
  76. package/skills/subagent-driven-development/scripts/sdd-workspace +51 -4
  77. package/skills/subagent-driven-development/scripts/task-brief +3 -1
  78. package/skills/subagent-driven-development/task-reviewer-prompt.md +2 -2
  79. package/skills/systematic-debugging/CREATION-LOG.md +1 -1
  80. package/skills/systematic-debugging/SKILL.md +2 -2
  81. package/skills/systematic-debugging/root-cause-tracing.md +1 -1
  82. package/skills/test-driven-development/SKILL.md +2 -0
  83. package/skills/using-superpowers/SKILL.md +19 -14
  84. package/skills/using-superpowers/references/claude-code-tools.md +11 -0
  85. package/skills/using-superpowers/references/muse-tools.md +35 -0
  86. package/skills/writing-plans/SKILL.md +34 -27
  87. package/skills/writing-skills/SKILL.md +5 -3
  88. package/assets/sponsors/apimart.jpg +0 -0
  89. package/assets/sponsors/compshare.jpg +0 -0
  90. package/assets/sponsors/logo-apimart-icon.png +0 -0
  91. package/assets/sponsors/logo-compshare-icon.png +0 -0
  92. package/skills/brainstorming/spec-document-reviewer-prompt.md +0 -48
  93. package/skills/writing-plans/plan-document-reviewer-prompt.md +0 -49
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: executing-plans
3
- description: 当你有一份书面实现计划需要在单独的会话中执行,并设有审查检查点时使用
3
+ description: 当你要在当前会话里亲自担任实现者执行一份实现计划时使用——你的人类伙伴选择了内联执行,或者没有可用的子智能体工具
4
4
  version: "1.0.0"
5
5
  license: MIT
6
6
  metadata:
@@ -10,172 +10,223 @@ metadata:
10
10
 
11
11
  # 执行计划
12
12
 
13
- ## 概述
13
+ 在本会话里亲自执行计划,一个任务接一个任务:不为每个任务派实现子智能体,也不为每个任务派审查者。只在最后对整个分支做一次全新上下文的审查。
14
14
 
15
- 加载计划,批判性审查,执行所有任务,完成后报告。
15
+ **为什么内联:** 子智能体驱动开发为每个任务付一个全新实现者和一个全新审查者的钱,每一个都要从零重读代码库。内联执行只付一个上下文(你自己的)外加最后一个审查者。它放弃的是每个任务一份全新上下文、每个任务第二双眼睛。本技能用别的办法保住那两样东西换来的好处:简报就是规格,账本就是你的记忆,TDD 是每个任务的关卡,最终审查者就是第二双眼睛。
16
16
 
17
- **开始时宣布:** "我正在使用 executing-plans 技能来实现此计划。"
17
+ **核心原则:** 计划已经把该想的都想过了。严格照它执行,每一步都用一个你亲眼看着失败、又亲眼看着通过的测试来证明,并留下一份在你自己遗忘之后依然存在的记录。
18
18
 
19
- **注意:** 告诉你的人类伙伴,Superpowers 在有子代理支持时效果好得多(Claude Code、Codex CLI、Codex App、Copilot CLI 与 Gemini CLI 都算;见 `../using-superpowers/references/` 下的各平台工具参考)。如果子代理可用,请使用 subagent-driven-development 而非此技能。
19
+ **旁白:** 工具调用之间最多说一句简短的旁白——账本和工具结果本身就是记录。
20
20
 
21
- ## 流程
21
+ **持续执行:** 不要在任务之间停下来向你的人类伙伴确认。他们选内联执行是为了少花钱,不是为了每做完一个任务就回答一次"我该继续吗?"。不间断地执行计划里的所有任务。
22
22
 
23
- ### 步骤 1:加载并审查计划
23
+ **做裁决,不要停摆。** 冲突、歧义、计划缺陷——你自己定。规格是有约束力的权威,计划是它的论证,两者都答不上来的部分由你的判断来定。每个决定都以 `Ruling: <你决定了什么> — <为什么> — <如果错了代价是什么>` 记进账本,然后继续。没有记进账本的裁决就偏离计划,等于一个暗中做出的决定。
24
24
 
25
- 1. 确保有一个隔离的工作区:用 using-git-worktrees 创建一个,或者核实已有的那个
26
- 2. 读取计划文件
27
- 3. 批判性审查——识别计划中的任何问题或疑虑
28
- 4. 如果有疑虑:在开始之前向你的人类伙伴提出
29
- 5. 如果没有疑虑:创建 TodoWrite 并继续
25
+ 只有四件事会让你停下,也只有这四件:不可逆或破坏性的操作;涉及安全的动作;这个工作树之外、按惯例应当先问一声的副作用(合并、推送到共享分支、发布);以及一个坏到每条前进路径都只能靠猜的计划。遇到这四类,停下来问。
30
26
 
31
- **审查时重点检查:**
32
- - 步骤之间是否有依赖遗漏?(A 依赖 B,但 B 排在 A 之后)
33
- - 验证条件是否明确?("确认可用"不算,"运行 `npm test` 全部通过"才算)
34
- - 是否有隐含的环境假设?(Node 版本、数据库连接、API Key)
27
+ ## 何时使用
35
28
 
36
- **审查示例:**
37
- ```
38
- 计划文件:docs/plan.md
39
- 任务清单:5 个任务
29
+ - 你有一份来自 writing-plans 的计划,而你的人类伙伴在交接时选择了内联执行。
30
+ - 你的运行环境没有子智能体工具(见 `../using-superpowers/references/` 下的各平台参考)。绝不编造一次分派;就在这里执行计划。
31
+ - 任务基本相互独立——与 subagent-driven-development 的前提相同。
32
+
33
+ 一份写得完整的计划,会让内联执行变成"照抄 + 测试":它在中档的会话模型上就能跑得很好,而最强模型唯一值回票价的地方是最终审查——本技能会单独分派它。你的人类伙伴选择内联时,把这一点告诉他们。
34
+
35
+ 当你的人类伙伴希望每个任务都有一道审查关卡,或者计划长到后面的任务会在压缩过的上下文上运行时,优先选 subagent-driven-development。在长计划上内联执行依然可行——账本让它可以恢复——但最后那几个任务分到的是最少的你。
40
36
 
41
- 审查发现:
42
- - 任务 3(添加数据库迁移)应在任务 2(编写数据模型)之后,顺序正确 ✓
43
- - 任务 4 的验证条件写的是"确认功能正常"→ 需澄清:具体跑什么测试?
44
- - 计划未提及 Python 版本要求 → 需确认
37
+ ## 流程
45
38
 
46
- 向伙伴提出:
47
- "计划整体可执行。有两个问题:(1) 任务 4 的验证条件不够具体,建议改为
48
- '运行 pytest tests/test_api.py 全部通过';(2) 需要确认 Python 版本要求。"
39
+ ```dot
40
+ digraph process {
41
+ rankdir=TB;
42
+
43
+ subgraph cluster_per_task {
44
+ label="每个任务";
45
+ "task-start: 简报 + BASE; 读简报" [shape=box];
46
+ "按顺序做各步: TDD, 跑每个验证, 读每份输出" [shape=box];
47
+ "步骤输出与计划的 Expected 一致?" [shape=diamond];
48
+ "计划错了? 裁决并记账。代码错了? systematic-debugging" [shape=box];
49
+ "按计划的提交步骤提交" [shape=box];
50
+ "完成契约满足?" [shape=diamond];
51
+ "task-done: 跑测试, 结果记进账本; 标记待办完成" [shape=box];
52
+ }
53
+
54
+ "准备: 工作树、工作区 + 账本、读计划 + 规格、起飞前扫描" [shape=box];
55
+ "还有任务?" [shape=diamond];
56
+ "最终整分支审查 (有条件就用全新审查者)" [shape=box];
57
+ "重新定级, 然后: Critical/Important → 一轮修复, 每个修复 RED→GREEN + 全套件绿; Minor → 账本" [shape=box];
58
+ "最终审查干净: 删除本计划的工作区" [shape=box];
59
+ "使用 finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
60
+
61
+ "准备: 工作树、工作区 + 账本、读计划 + 规格、起飞前扫描" -> "task-start: 简报 + BASE; 读简报";
62
+ "task-start: 简报 + BASE; 读简报" -> "按顺序做各步: TDD, 跑每个验证, 读每份输出";
63
+ "按顺序做各步: TDD, 跑每个验证, 读每份输出" -> "步骤输出与计划的 Expected 一致?";
64
+ "步骤输出与计划的 Expected 一致?" -> "计划错了? 裁决并记账。代码错了? systematic-debugging" [label="否"];
65
+ "计划错了? 裁决并记账。代码错了? systematic-debugging" -> "按顺序做各步: TDD, 跑每个验证, 读每份输出";
66
+ "步骤输出与计划的 Expected 一致?" -> "按计划的提交步骤提交" [label="是, 最后一步"];
67
+ "按计划的提交步骤提交" -> "完成契约满足?";
68
+ "完成契约满足?" -> "按顺序做各步: TDD, 跑每个验证, 读每份输出" [label="否 - 把任务做完"];
69
+ "完成契约满足?" -> "task-done: 跑测试, 结果记进账本; 标记待办完成" [label="是"];
70
+ "task-done: 跑测试, 结果记进账本; 标记待办完成" -> "还有任务?";
71
+ "还有任务?" -> "task-start: 简报 + BASE; 读简报" [label="是"];
72
+ "还有任务?" -> "最终整分支审查 (有条件就用全新审查者)" [label="否"];
73
+ "最终整分支审查 (有条件就用全新审查者)" -> "重新定级, 然后: Critical/Important → 一轮修复, 每个修复 RED→GREEN + 全套件绿; Minor → 账本";
74
+ "重新定级, 然后: Critical/Important → 一轮修复, 每个修复 RED→GREEN + 全套件绿; Minor → 账本" -> "最终审查干净: 删除本计划的工作区";
75
+ "最终审查干净: 删除本计划的工作区" -> "使用 finishing-a-development-branch";
76
+ }
49
77
  ```
50
78
 
51
- ### 步骤 2:执行任务
79
+ ## 准备
52
80
 
53
- 对于每个任务:
81
+ 确保工作发生在一个隔离的工作区里:用 using-git-worktrees 创建一个,或者核实已有的那个。未经你的人类伙伴明确同意,绝不在 main/master 分支上开始实现。
54
82
 
55
- 1. **标记为进行中** — 更新 TodoWrite
56
- 2. **理解目标** — 重读任务描述,明确完成标准
57
- 3. **执行实现** — 严格按照计划步骤执行(计划已有小步骤)
58
- 4. **运行验证** — 按要求运行测试或检查
59
- 5. **提交变更** — 每完成一个任务提交一次,commit message 引用任务编号
60
- 6. **标记为已完成** — 更新 TodoWrite
83
+ 会话记忆无法在上下文压缩(compaction)中存活。一个丢失了位置的内联执行者,会重新实现那些提交早已存在的任务——和控制者重新分派它们是同一种失败,只不过代价付在你自己的上下文里。把进度记在一个账本文件里,而不只是记在待办里。运行环境的待办只是实时视图;账本才是记录。
61
84
 
62
- **每个任务的节奏:**
63
- ```
64
- --- 任务 2/5:添加用户验证 ---
65
- [标记进行中]
85
+ 工作区和账本与 subagent-driven-development 共用——同一个目录、同一种格式——所以一个计划可以在执行中途换执行方式,新的执行者从同一个账本接着做。
66
86
 
67
- 目标:为 /api/users 添加输入验证
68
- 完成标准:所有验证测试通过,无效输入返回 400
87
+ - **每个计划拥有自己的工作区:** 技能启动时,运行 `../subagent-driven-development/scripts/sdd-workspace PLAN_FILE`——它会打印这个计划专属的、被 git 忽略的目录(`<repo-root>/.superpowers/sdd/<计划文件名>/`),**本计划**的一切产物都放在那里:账本、简报、审查包。别的计划的目录不属于你,不读也不写。
88
+ - 到 `<工作区>/progress.md` 查本计划的账本。如果它的第一行点名的是你的计划文件,那么带有 `Task <N>: complete` 行的任务就是**已完成**——不要重做;从第一个没有该行的任务处继续。即使你的上下文已经不记得做过它们,它们的提交也确实存在于 git 中:压缩之后,相信账本和 `git log`,而不是你自己的记忆。如果账本第一行点名的是另一个计划文件,那是另一个计划的进度:原地别动,另起你自己的新账本。
89
+ - 创建账本时,把它的身份写在第一行:`# SDD ledger — plan: <计划文件路径>`。
90
+ - `git clean -fdx` 会毁掉工作区(它是被 git 忽略的草稿区);如果发生了,从 `git log` 恢复。
69
91
 
70
- [实现]
71
- - 添加 validateUser() 中间件
72
- - 编写 3 个验证规则(email 格式、密码强度、用户名长度)
92
+ 把计划**读一遍**,记下它的上下文和全局约束,并为每个任务建一条待办。如果计划点名了一份规格(Spec),把规格也读了:规格是计划据以论证的权威,计划内部的冲突要拿它来裁。计划里找不到可达的规格,就在账本里记一条说明——没有规格作出的裁决都是临时的。
73
93
 
74
- [验证]
75
- $ npm test -- --grep "validation"
76
- ✓ 拒绝无效 email (12ms)
77
- ✓ 拒绝弱密码 (8ms)
78
- ✓ 拒绝过长用户名 (5ms)
79
- 3 passing
94
+ **必需子技能:** 现在、在任务 1 之前,加载 test-driven-development。它管着下面每个任务的每一步;一份步骤里已经写着"先写失败的测试"的计划,并不能让你免于读它。
80
95
 
81
- [提交]
82
- $ git add src/middleware/validate.js tests/validation.test.js
83
- $ git commit -m "feat: 添加用户输入验证(任务 2/5)"
96
+ 任务 1 之前,扫描计划中任务之间的冲突。计划的 Interfaces 块告诉你该看哪里:每个消费前序任务产出的任务,对应账本里的一行——两个任务、一方产出的东西对照另一方消费的东西、以及你的发现。什么都不共享的任务不占行;任务之间什么都不共享的计划,只记一行 `Pre-flight: no shared interfaces`。以规格为有约束力的权威,对每一行翻出的冲突作出裁决,把裁决记在那一行旁边,然后开始任务 1。每个任务自身的文本在你读它的简报时再检查,不在这里。
84
97
 
85
- [标记完成]
86
- --- 任务 2/5 完成 ---
87
- ```
98
+ ## 任务循环
88
99
 
89
- **持续自查:**
90
- - 执行过程中持续留意:整体方向还对吗?有没有偏离计划?
91
- - 如果发现前面的实现有问题,先修复再继续,不要带着问题往下走
100
+ 你打印的一切、每一个工具结果,都会在会话剩下的时间里常驻在你的上下文中。把冗长的测试输出重定向到工作区里的文件,只读它的末尾;读简报,而不是整个计划。
92
101
 
93
- ### 步骤 3:完成开发
102
+ ### 1. 接下任务
94
103
 
95
- 所有任务完成并验证后:
96
- - 宣布:"我正在使用 finishing-a-development-branch 技能来完成此工作。"
97
- - **必需子技能:** 使用 finishing-a-development-branch
98
- - 按照该技能的指引验证测试、展示选项、执行选择
104
+ - 运行本技能的 `scripts/task-start PLAN_FILE N`。它一次调用就打印出简报路径和 BASE(这个任务的范围从哪个提交切出)。每个任务都要读简报,包括你在准备阶段就记得的那些:你记得的是摘要,简报里有精确的取值、签名和测试用例。
105
+ - 把该任务的待办标为 in_progress。
99
106
 
100
- **完成报告模板:**
101
- ```
102
- ## 执行报告
107
+ 每一次工具调用都是一轮,要把你的整个上下文重读一遍。记账顺着干活一起做——账本追加和提交放在同一次调用里,绝不单独占一次调用。
103
108
 
104
- **计划:** docs/plan.md
105
- **分支:** feature/user-validation
106
- **任务:** 5/5 已完成
109
+ ### 2. 做各个步骤
107
110
 
108
- ### 完成的任务
109
- 1. ✅ 初始化项目结构
110
- 2. ✅ 添加用户验证
111
- 3. ✅ 添加数据库迁移
112
- 4. ✅ 实现 API 端点
113
- 5. ✅ 添加集成测试
111
+ 计划的步骤已经是 RED-GREEN 的顺序;在准备阶段加载的 test-driven-development 之下,按这个顺序做。测试步骤的代码先写、先跑。看着它失败是一个步骤,不是走过场——一个在实现还不存在时就通过的测试,本身就是一条关于这个测试的发现。
114
112
 
115
- ### 验证结果
116
- - 单元测试:23/23 通过
117
- - 集成测试:8/8 通过
118
- - lint 检查:0 个警告
113
+ 每个会运行命令的步骤都有一行 `Expected:`。运行命令,读它的输出,然后对照。三种结果:
119
114
 
120
- ### 偏离计划的地方
121
- - 任务 3:Redis 配置从 env 改为 config.yaml(经伙伴同意)
115
+ - **一致。** 下一步。
116
+ - **代码错了。** 使用 systematic-debugging。找到原因;绝不为了让步骤输出对上而去修补症状。
117
+ - **计划错了**——某一步与规格矛盾、前序任务的接口与本任务消费的不一致、一条根本跑不通的命令。对能满足规格的最小改动作出裁决,以 `Task <N>: Ruling: <发现> — <你决定了什么,以及为什么>` 记进账本,然后继续。裁决是被携带的,而不是被记住的:后面碰同一个接口的任务,从账本里读到它。
122
118
 
123
- ### 下一步
124
- 按 finishing-a-development-branch 技能处理合并/PR
125
- ```
119
+ 按计划的提交步骤提交。一个任务跨好几个提交没问题;审查范围从 BASE 切出,绝不用 `HEAD~1`。
126
120
 
127
- ## 何时停下来求助
121
+ ### 3. 完成契约
128
122
 
129
- **在以下情况立即停止执行:**
130
- - 遇到阻塞(缺少依赖、测试失败、指令不清)
131
- - 计划有严重缺陷导致无法开始
132
- - 你不理解某条指令
133
- - 验证反复失败(同一测试失败 2 次以上)
123
+ 在一个任务写账本行之前,下面各项都必须为真,并且在本会话中有证据——而不是因为 diff 看起来没问题就推断出来:
134
124
 
135
- **不确定时就问,不要猜测。**
125
+ - 简报点名的每一个测试都存在、都在本任务中跑过,并且你读了输出。
126
+ - 本任务最后一次测试运行通过了——`task-done` 就是那次运行,它会把命令和结果写进账本行。
127
+ - 简报里的每一行 `Expected:` 都和真实输出对照过。
128
+ - 每一处对简报的偏离,在账本里都有一行 `Ruling:`。
136
129
 
137
- ## 常见异常处理
130
+ **必需子技能:** 这个声明由 verification-before-completion 管辖。任何一项缺失,任务就没有完成:把它做完。
138
131
 
139
- > 🇨🇳 **本节是 superpowers-zh 的增量内容,上游 obra/superpowers 没有。**
140
- > 它展开的是上一节「遇到阻塞(缺少依赖、测试失败、指令不清)」的三种具体情形。
141
- > 上游的步骤 1–3 与其余各节均为逐节翻译,未被本节改动。
132
+ ### 4. 完成任务
142
133
 
134
+ 运行本技能的 `scripts/task-done PLAN_FILE N BASE -- <测试命令>`,测试命令用简报为整个任务点名的那一条。它会跑测试、把完整输出保存在工作区、打印末尾,并且——只有在测试通过时——往账本追加完成行:
143
135
 
144
- **测试失败:**
145
- 1. 读错误信息,定位失败原因
146
- 2. 区分:是实现 bug?还是测试本身有问题?还是计划描述有误?
147
- 3. 实现 bug → 修复并重跑
148
- 4. 测试有问题 → 修复测试,向伙伴说明
149
- 5. 计划有误 → 停下来,向伙伴报告并建议修正
136
+ `Task <N>: complete (commits <base7>..<head7>, tests: <command> → <result>)`
137
+
138
+ 失败的运行什么都不记录;任务没有完成。记录成功后,把待办标为完成,接下一个任务。
139
+
140
+ ## 最终审查
141
+
142
+ 运行 `../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD`(MERGE_BASE = 分支起点的那个提交,例如 `git merge-base main HEAD`),并基于它打印出的文件做审查。
143
+
144
+ **有子智能体工具时:** 在可用的最强模型上分派审查者——整分支审查是一项判断性任务——使用 requesting-code-review 的 [code-reviewer.md](../requesting-code-review/code-reviewer.md),附上审查包路径、计划和规格的路径、计划的「审查重点(Review Focus)」一节(如果有的话)原文照录(即计划的测试没有覆盖到的输入类别和失败模式——审查者会逐条刻意检查),以及一个指向账本中 `Ruling:` 行的指针,好让它掂量你做过的那些决定。显式指定模型;省略模型会继承会话的模型,而那未必是最强的。这是整次运行唯一买下的全新上下文。不要跳过它,也不要用你自己读一遍 diff 来代替它。
145
+
146
+ **没有子智能体工具时:** 读 code-reviewer.md,并在最后一个任务的账本行之后,作为单独的一轮,自己对着审查包做那次审查。往账本写 `Final review: self-review (no subagent tool)`,并在你的最终消息里说明:作者自审比全新审查者弱,合并前这是否足够,由你的人类伙伴决定。
147
+
148
+ 在对任何一条发现动手之前,先把它们分拣好。审查者的严重程度标签只是建议;关卡在你手里。它的「不予判断的项」列表(Declined to judge)也归你:那里的每一行都是一个你要作出并记进账本的裁决,和计划冲突一模一样——`Final: Ruling: <审查者搁置的行为> — <使用这个软件的一个合理的人会得到什么,以及为什么维持原样、或为什么现在它算一条发现> — <如果错了代价是什么>`。先按影响重新定级:规格是一份愿景文档,一条发现的级别取决于它上线后使用这个软件的一个合理的人会遭遇什么,而不是规格有没有点名触发它的那个输入——因为规格没提就把发现定为 Minor 的审查者,评的是规格,不是影响。然后:
149
+
150
+ - **Critical 和 Important** 进入修复轮。
151
+ - **Minor** 以 `Final: minor (deferred): <一句话>` 记进账本,并写进你最终消息的"延后的 Minor"一节。Minor 永远不进入修复轮,也永远不会变成裁决——裁决是针对冲突的决定,不是一条"我没采纳这个打磨建议"的备注。
152
+
153
+ Critical 和 Important 发现由你自己修——在这里你就是实现者——**一轮**修完。每个修复由 TDD 验证,而不是由第二个审查者验证:写出复现该发现的测试,看着它失败,让它通过,然后跑整个套件。每一条都以 `Final: fixed <发现> — <测试名> RED→GREEN, suite <N>/<N>` 记进账本。一个没有先失败过的测试的修复不算验证过;修复轮结束后套件不是全绿,就说明这一轮还没结束。不要分派复审:它要重读的那份 diff,覆盖它的测试已经回答了"是否已解决",套件运行已经回答了"有没有弄坏别的"。
154
+
155
+ 一条你决定不修的发现,就是一个裁决——`Final: Ruling: <发现> — <为什么代码可以维持原样> — <如果错了代价是什么>`——它会通过裁决清单送到你的人类伙伴面前。没有第二轮修复。
156
+
157
+ ## 收尾
158
+
159
+ 在删除任何东西之前,把账本里所有含 `Ruling:` 的行按你作出它们的顺序收集到最终消息的"我作出的裁决"一节,每条都带上如果错了的代价;把每一行 `minor (deferred)` 收集到"延后的 Minor"一节。两份清单都必须完整。你的最终消息,是你代表你的人类伙伴作出的那些决定——以及你选择不处理的那些发现——送到他们面前的唯一地方。
160
+
161
+ 最终审查干净、它的修复都已提交后,删除本计划的工作区目录——现在 git 历史就是记录。同级目录属于其他计划;别碰它们。
162
+
163
+ 使用 finishing-a-development-branch。
164
+
165
+ ## 常见的合理化借口
166
+
167
+ | 借口 | 现实 |
168
+ |------|------|
169
+ | "我记得任务 N 说了什么" | 你记得的是摘要。简报里有精确取值。去读它。 |
170
+ | "计划里的代码是对的,跳过看测试失败这一步" | 一个你从没见它失败过的测试什么也证明不了。它就是一步。跑它。 |
171
+ | "我最后再跑全套件,不用每一步都跑" | 每步都跑,你才知道是哪一步弄坏的。任务结束时那次运行是契约,不是替代品。 |
172
+ | "这里计划错了,我直接做对的就行" | 做对的,并且把裁决记进账本。不记账的偏离是一个暗中做出的决定。 |
173
+ | "我做完几个任务再补账本行" | 压缩不会挑一个方便的时机。每个任务一行,和提交在同一条消息里。 |
174
+ | "下一个任务之前我先确认一下" | 他们选内联是为了少花钱。进度询问花的是他们的时间。只有那四类情况能让你停下。 |
175
+ | "我已经仔细读过自己的 diff,最终审查者是多余的" | 同一个作者,同样的盲区。审查者是这次运行唯一买下的全新上下文。 |
176
+ | "改动很小,测试应该能过" | "应该"不是证据。契约要求的是命令和它的输出。 |
177
+ | "子智能体又慢又贵,最终审查我也跳过吧" | 内联已经去掉了每个任务的审查者。对整个分支的一次审查是底线,不是上限。 |
178
+ | "审查者说是 Minor,那就是 Minor" | 那个标签评的是规格的沉默。评一评使用者会得到什么。先重新定级,再过关卡。 |
179
+ | "修复很明显,不需要先写一个失败的测试" | 失败的测试是这条发现真实存在、并且现在已经消失的唯一证明。没有它,你手里只有一份 diff 和一个希望。 |
180
+ | "我顺手把 Minor 也修了吧" | 你修的每个 Minor,都是一个你伙伴没要的测试、一次修复、一次套件运行。记进账本;由你伙伴决定。 |
181
+
182
+ ## 示例工作流
150
183
 
151
- **依赖缺失:**
152
- ```
153
- 任务 3 需要 Redis 连接,但计划中没有提及 Redis 配置。
154
- → 停止执行
155
- → 向伙伴报告:"任务 3 需要 Redis,计划中未包含配置步骤。
156
- 建议:在任务 3 前插入 '配置 Redis 连接' 步骤。"
157
184
  ```
185
+ 你:我正在使用 executing-plans 技能以内联方式实现这份计划。
186
+
187
+ [准备:工作树已核实]
188
+ [读计划一次:docs/superpowers/plans/feature-plan.md;规格已读]
189
+ [解析工作区:sdd-workspace docs/superpowers/plans/feature-plan.md —— 里面没有账本,全新开始]
190
+ [起飞前扫描:2 行共享接口、4 行自洽性,均无问题;已写入账本]
191
+ [为所有任务创建待办]
192
+
193
+ 任务 1:钩子安装脚本
158
194
 
159
- **指令不清:**
160
- - 不要猜测意图,不要"合理推断"
161
- - 列出你的理解和困惑,让伙伴澄清
162
- - 等待回复后再继续
195
+ [task-start plan 1 → 简报已读;BASE a1b2c3d]
196
+ [步骤 1:写失败的测试 —— 已写]
197
+ [步骤 2:运行 —— FAIL:install_hook not defined。与 Expected 一致。]
198
+ [步骤 3:实现 —— 已写]
199
+ [步骤 4:运行 —— PASS 1/1。与 Expected 一致。]
200
+ [步骤 5:提交 —— d4e5f6a]
201
+ [契约:测试已运行,输出已读,无偏离]
202
+ [task-done plan 1 a1b2c3d -- npm test -- hooks → 账本:Task 1: complete (commits a1b2c3d..d4e5f6a, tests: npm test -- hooks → 1/1 pass)]
163
203
 
164
- **提交粒度:** 每个任务单独提交,commit message 引用任务编号。
204
+ 任务 2:恢复模式
165
205
 
166
- ## 何时回到之前的步骤
206
+ [task-start plan 2 → 简报已读;BASE d4e5f6a]
207
+ [步骤 2:运行失败的测试 —— FAIL,但是导入错误:任务 1 导出的是
208
+ installHook,简报消费的是 install_hook]
209
+ [裁决:简报里的消费方名称相对于任务 1 的 Produces 块是笔误;
210
+ 用 installHook —— 账本:Task 2: Ruling: install_hook → installHook — matches Task 1 Produces — cost if wrong: one rename]
211
+ [步骤 2-5 按计划进行;提交 b7c8d9e]
212
+ [task-done plan 2 d4e5f6a -- npm test -- recovery → 账本:Task 2: complete (commits d4e5f6a..b7c8d9e, tests: npm test -- recovery → 8/8 pass)]
167
213
 
168
- **回到审查(步骤 1)当:**
169
- - 伙伴根据你的反馈更新了计划
170
- - 根本性的方案需要重新考虑
214
+ ...
171
215
 
172
- **不要硬闯阻塞** — 停下来问。
216
+ [所有任务之后:review-package plan MERGE_BASE HEAD;分派 code-reviewer,最强模型]
217
+ 审查者:一条 Important 发现 —— 进度上报间隔被写死了。两条 Minor。
218
+ [重新定级:Important 成立;Minor → 作为延后项记进账本]
219
+ [修复轮:test_progress_interval_configurable RED → 抽出 PROGRESS_INTERVAL → GREEN;套件 12/12;提交]
220
+ [账本:Final: fixed hardcoded interval — test_progress_interval_configurable RED→GREEN, suite 12/12]
173
221
 
174
- ## 注意事项
175
- - 先批判性审查计划
176
- - 严格按照计划步骤执行
177
- - 不要跳过验证
178
- - 计划要求时引用相应技能
179
- - 遇到阻塞时停下来,不要猜测
180
- - 未经用户明确同意,绝不在 main/master 分支上开始实现
222
+ 我作出的裁决:
223
+ - 任务 2:install_hook → installHook(简报笔误;如果错了的代价:一次重命名)
181
224
 
225
+ 延后的 Minor:
226
+ - README 缺少用法示例
227
+ - recovery.js 可以把 verify/repair 拆成两个文件
228
+
229
+ [删除本计划的工作区 —— 记录现在在 git 里]
230
+
231
+ 正在使用 finishing-a-development-branch。
232
+ ```
@@ -0,0 +1,52 @@
1
+ #!/usr/bin/env bash
2
+ # Close one task of an inline plan execution in a single call: run the task's
3
+ # test command, keep its full output in the workspace, print the tail, and —
4
+ # only if the command succeeded — append the completion line to the ledger.
5
+ # A failing command records nothing: the task is not complete.
6
+ #
7
+ # Usage: task-done PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]
8
+ # BASE is the SHA task-start printed; the completion line records BASE..HEAD.
9
+ # Exit: the test command's exit status.
10
+ set -euo pipefail
11
+
12
+ if [ $# -lt 5 ] || [ "$4" != "--" ]; then
13
+ echo "usage: task-done PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]" >&2
14
+ exit 2
15
+ fi
16
+
17
+ plan=$1
18
+ n=$2
19
+ base=$3
20
+ shift 4
21
+ sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)"
22
+
23
+ git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
24
+
25
+ dir=$("$sdd/sdd-workspace" "$plan")
26
+ log="$dir/task-${n}-tests.log"
27
+ ledger="$dir/progress.md"
28
+
29
+ # Render the command the way a person would type it, for the ledger line.
30
+ cmd=""
31
+ for a in "$@"; do
32
+ case "$a" in
33
+ *[[:space:]\"\;\|\&]*) cmd="$cmd '$a'" ;;
34
+ *) cmd="$cmd $a" ;;
35
+ esac
36
+ done
37
+ cmd=${cmd# }
38
+
39
+ rc=0
40
+ "$@" > "$log" 2>&1 || rc=$?
41
+
42
+ tail -n 5 "$log"
43
+ if [ "$rc" -ne 0 ]; then
44
+ echo "task-done: test command exited $rc; Task $n NOT recorded (full output: $log)" >&2
45
+ exit "$rc"
46
+ fi
47
+
48
+ last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1) || last="(no output)"
49
+ [ -f "$ledger" ] || printf '# SDD ledger — plan: %s\n' "$plan" > "$ledger"
50
+ line="Task $n: complete (commits $(git rev-parse --short=7 "$base")..$(git rev-parse --short=7 HEAD), tests: $cmd → $last)"
51
+ printf '%s\n' "$line" >> "$ledger"
52
+ echo "ledger: $line"
@@ -0,0 +1,28 @@
1
+ #!/usr/bin/env bash
2
+ # Begin one task of an inline plan execution in a single call: extract the
3
+ # task's brief (via subagent-driven-development's task-brief, so both skills
4
+ # share one workspace) and record BASE, the commit the task's review range is
5
+ # cut from. One tool call instead of two, because every call in an inline
6
+ # session is a turn that re-reads the whole context.
7
+ #
8
+ # Usage: task-start PLAN_FILE TASK_NUMBER
9
+ # Prints:
10
+ # brief: <path to the task's brief file>
11
+ # base: <full SHA of HEAD>
12
+ set -euo pipefail
13
+
14
+ if [ $# -ne 2 ]; then
15
+ echo "usage: task-start PLAN_FILE TASK_NUMBER" >&2
16
+ exit 2
17
+ fi
18
+
19
+ plan=$1
20
+ n=$2
21
+ sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)"
22
+
23
+ out=$("$sdd/task-brief" "$plan" "$n")
24
+ brief=$(printf '%s\n' "$out" | sed -n 's/^wrote \(.*\): [0-9][0-9]* lines$/\1/p')
25
+ [ -n "$brief" ] || { echo "task-brief did not report a path: $out" >&2; exit 1; }
26
+
27
+ echo "brief: $brief"
28
+ echo "base: $(git rev-parse HEAD)"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mcp-builder
3
- description: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具,让 AI 助手连接外部能力
3
+ description: 在构建 MCP 服务器或 MCP 工具时使用 —— 系统化的生产级 MCP 构建方法论,覆盖工具设计、错误处理、传输层选择与测试,让 AI 助手连接外部能力
4
4
  version: "1.0.0"
5
5
  license: MIT
6
6
  metadata:
@@ -30,7 +30,7 @@ metadata:
30
30
 
31
31
  **1. 获取 git SHA:**
32
32
  ```bash
33
- BASE_SHA=$(git rev-parse HEAD~1) # 或 origin/main
33
+ BASE_SHA=$(git rev-parse HEAD~1) # 或:git merge-base origin/main HEAD
34
34
  HEAD_SHA=$(git rev-parse HEAD)
35
35
  ```
36
36
 
@@ -57,7 +57,7 @@ HEAD_SHA=$(git rev-parse HEAD)
57
57
 
58
58
  你:让我在继续之前请求代码审查。
59
59
 
60
- BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
60
+ BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | cut -d' ' -f1)
61
61
  HEAD_SHA=$(git rev-parse HEAD)
62
62
 
63
63
  [派遣代码审查子代理]
@@ -29,6 +29,14 @@ Task tool(general-purpose):
29
29
  git diff {BASE_SHA}..{HEAD_SHA}
30
30
  ```
31
31
 
32
+ ## 规格是一份愿景文档
33
+
34
+ 规格说的是软件必须做什么。它不会把软件将遇到的每一种输入、环境或条件都列举出来。对于规格没有提到的行为,按一个使用这个软件的正常人会期待什么来判断:正常人的期待就是需求,规格没提不等于允许。给这类发现定级,看的是它对那个人的影响,而不是规格有没有提到触发它的条件。
35
+
36
+ ## 不予判断的项
37
+
38
+ 在给出结论之前,列出你考虑过、但作为计划或规格范围之外而搁置的每一项行为,一行一项,附上理由。执行者会对每一行作出裁决;你搁置的任何东西都不会被悄悄丢掉。列表为空,意味着你什么都没搁置。
39
+
32
40
  ## 只读审查
33
41
 
34
42
  你的审查在这个检出上是**只读**的。不要以任何方式改动工作区、索引、HEAD 或分支状态。用 `git show`、`git diff`、`git log` 这类命令查看历史。如果你需要某个其他版本的工作副本,把它检出到一个独立的临时目录(例如 `git worktree add /tmp/review-[SHA] [SHA]`)—— 绝不要移动这个检出上的 HEAD。
@@ -30,25 +30,25 @@ metadata:
30
30
  digraph when_to_use {
31
31
  "有实现计划?" [shape=diamond];
32
32
  "任务基本独立?" [shape=diamond];
33
- "留在当前会话?" [shape=diamond];
33
+ "伙伴选了内联执行,或没有子智能体工具?" [shape=diamond];
34
34
  "subagent-driven-development" [shape=box];
35
35
  "executing-plans" [shape=box];
36
36
  "手动执行或先头脑风暴" [shape=box];
37
37
 
38
38
  "有实现计划?" -> "任务基本独立?" [label="是"];
39
39
  "有实现计划?" -> "手动执行或先头脑风暴" [label="否"];
40
- "任务基本独立?" -> "留在当前会话?" [label="是"];
40
+ "任务基本独立?" -> "伙伴选了内联执行,或没有子智能体工具?" [label="是"];
41
41
  "任务基本独立?" -> "手动执行或先头脑风暴" [label="否 - 紧密耦合"];
42
- "留在当前会话?" -> "subagent-driven-development" [label="是"];
43
- "留在当前会话?" -> "executing-plans" [label="否 - 并行会话"];
42
+ "伙伴选了内联执行,或没有子智能体工具?" -> "executing-plans" [label="是"];
43
+ "伙伴选了内联执行,或没有子智能体工具?" -> "subagent-driven-development" [label="否"];
44
44
  }
45
45
  ```
46
46
 
47
- **与 Executing Plans(并行会话)的对比:**
48
- - 同一会话(无上下文切换)
49
- - 每个任务全新子智能体(无上下文污染)
50
- - 每个任务后做审查(规格合规性 + 代码质量),结尾做宽范围审查
51
- - 更快的迭代(任务间无需人工介入)
47
+ **与 Executing Plans(内联执行)的对比:**
48
+ - 每个任务一个全新子智能体(无上下文污染),而不是一个上下文包揽所有任务
49
+ - 每个任务后做审查(规格合规性 + 代码质量),而不是只在结尾审查
50
+ - 代价是每个任务、每次审查各一个全新上下文;内联执行的代价是一个上下文加一个最终审查者
51
+ - 两者都在当前会话里运行,共用同一个计划工作区和账本,任务之间都不停顿
52
52
 
53
53
  ## 流程
54
54
 
@@ -121,7 +121,7 @@ digraph process {
121
121
 
122
122
  会话记忆无法在上下文压缩(compaction)中存活。在真实会话里,丢失了位置的控制者曾重新分派整段已经完成的任务序列——这是观察到的最昂贵的失败。把进度记在一个账本文件里,而不只是记在待办里。
123
123
 
124
- - **每个计划拥有自己的工作区:** 技能启动时,运行本技能的 `scripts/sdd-workspace PLAN_FILE`——它会打印这个计划专属的、被 git 忽略的目录(`<repo-root>/.superpowers/sdd/<计划文件名>/`),**本计划**的一切产物都放在那里:账本、简报、报告、审查包。别的计划的目录不属于你,不读也不写。
124
+ - **每个计划拥有自己的工作区:** 技能启动时,运行本技能的 `bash scripts/sdd-workspace PLAN_FILE`——它会打印这个计划专属的、被 git 忽略的目录(位于 `<repo-root>/.superpowers/sdd/` 之下),**本计划**的一切产物都放在那里:账本、简报、报告、审查包。别的计划的目录不属于你,不读也不写。
125
125
  - 到 `<工作区>/progress.md` 查本计划的账本。如果它的第一行点名的是你的计划文件,那么带有 `Task <N>: complete` 行的任务就是**已完成**——不要重新分派它们;从第一个没有该行的任务处继续。如果某个任务的最后一行是一轮修复,说明它正卡在修复循环中:从下一轮继续。如果账本第一行点名的是**另一个**计划文件——或者你在旧的扁平路径 `.superpowers/sdd/progress.md` 发现了一个游离的账本——那是别人的进度:原地别动,另起你自己的新账本。
126
126
  - 创建账本时,把它的身份写在第一行:`# SDD ledger — plan: <计划文件路径>`。
127
127
  - 这个账本是你的恢复地图:它点名的那些提交,即使你的上下文已经不记得创建过它们,也确实存在于 git 中。压缩之后,相信账本和 `git log`,而不是你自己的记忆。
@@ -173,7 +173,7 @@ digraph process {
173
173
 
174
174
  分派之前记录 BASE(`git rev-parse HEAD`)——审查包和各轮修复的 diff 都要用它。
175
175
 
176
- - **任务简报:** 分派实现者之前,运行本技能的 `scripts/task-brief PLAN_FILE N`——它把该任务的完整文本抽取到一个唯一命名的文件并打印路径。组织你的分派,让这份简报保持为需求的唯一来源。你的分派应包含:(1) 一行说明这个任务在项目中的位置;(2) 简报路径,引入语为"先读这个——它是你的需求,里面有要逐字使用的精确取值";(3) 简报无从知晓的、来自前序任务的接口和决策;(4) 你对简报中注意到的任何歧义的裁定;(5) 报告文件路径和报告契约。精确取值(数字、魔法字符串、签名、测试用例)只出现在简报里。**绝不**让子智能体去读整个计划文件。
176
+ - **任务简报:** 分派实现者之前,运行本技能的 `bash scripts/task-brief PLAN_FILE N`——它把该任务的完整文本抽取到一个唯一命名的文件并打印路径。组织你的分派,让这份简报保持为需求的唯一来源。你的分派应包含:(1) 一行说明这个任务在项目中的位置;(2) 简报路径,引入语为"先读这个——它是你的需求,里面有要逐字使用的精确取值";(3) 简报无从知晓的、来自前序任务的接口和决策;(4) 你对简报中注意到的任何歧义的裁定;(5) 报告文件路径和报告契约。精确取值(数字、魔法字符串、签名、测试用例)只出现在简报里。**绝不**让子智能体去读整个计划文件。
177
177
  - **报告文件:** 实现者的报告文件按简报来命名(简报 `…/task-N-brief.md` → 报告 `…/task-N-report.md`),并写进分派提示词。实现者把完整报告写在那里,只回传状态、提交、一行测试小结和疑虑。
178
178
  - 一个分派提示词描述的是**一个任务**,不是会话的历史。不要把累积的前序任务小结("任务 1-3 之后的状态")粘进后面的分派——真实会话里曾出现过 42k 字符的分派,其中 99% 是粘贴的历史。一个全新的子智能体需要的是:它的任务、它要碰的接口、以及全局约束。别无其他。
179
179
  - 如果前面某个任务把一条发现搁置在本任务要碰的区域,就在分派里带上指向那条账本记录的指针。
@@ -187,7 +187,7 @@ digraph process {
187
187
 
188
188
  实现子智能体会回传四种状态之一。分别处理:
189
189
 
190
- **DONE:** 生成审查包(在本技能目录下运行 `scripts/review-package PLAN_FILE BASE HEAD`——它会打印出自己写入的那个唯一文件路径;BASE 是你在分派实现者之前记录下来的那个提交——**绝不用** `HEAD~1`,那会悄悄丢掉多提交任务里除最后一个之外的所有提交),然后把打印出的路径交给任务审查者去分派。
190
+ **DONE:** 生成审查包(在本技能目录下运行 `bash scripts/review-package PLAN_FILE BASE HEAD`——它会打印出自己写入的那个唯一文件路径;BASE 是你在分派实现者之前记录下来的那个提交——**绝不用** `HEAD~1`,那会悄悄丢掉多提交任务里除最后一个之外的所有提交),然后把打印出的路径交给任务审查者去分派。
191
191
 
192
192
  **DONE_WITH_CONCERNS:** 实现者完成了工作但提出了疑虑。继续之前先读这些疑虑。如果疑虑关乎正确性或范围,在审查之前先处理掉。如果只是观察(比如"这个文件变大了"),记下来,继续走审查。
193
193
 
@@ -207,7 +207,7 @@ digraph process {
207
207
 
208
208
  逐任务审查是**任务范围内的关卡**。宽范围审查只做一次,在最终的整分支审查那里。绝不跳过任务审查,也绝不接受一份缺少任一结论的报告——规格合规性**和**任务质量两者都必须有。实现者的自审永远不能替代任务审查;两者都需要。
209
209
 
210
- - **把 diff 作为文件交给审查者:** 运行本技能的 `scripts/review-package PLAN_FILE BASE HEAD`,把它打印出的文件路径交给审查者(若没有 bash:对该区间跑 `git log --oneline`、`git diff --stat`、`git diff -U10`,重定向到一个唯一命名的文件)。这些输出永远不会进入你自己的上下文,而审查者在一次 Read 调用里就能看到提交列表、stat 摘要和带上下文的完整 diff。用你在分派实现者之前记录下的 BASE——**绝不用** `HEAD~1`,那会悄悄截断多提交任务。**绝不**在没有 diff 文件的情况下分派任务审查者。
210
+ - **把 diff 作为文件交给审查者:** 运行本技能的 `bash scripts/review-package PLAN_FILE BASE HEAD`,把它打印出的文件路径交给审查者(若没有 bash:对该区间跑 `git log --oneline`、`git diff --stat`、`git diff -U10`,重定向到一个唯一命名的文件)。这些输出永远不会进入你自己的上下文,而审查者在一次 Read 调用里就能看到提交列表、stat 摘要和带上下文的完整 diff。用你在分派实现者之前记录下的 BASE——**绝不用** `HEAD~1`,那会悄悄截断多提交任务。**绝不**在没有 diff 文件的情况下分派任务审查者。
211
211
  - **审查者的输入:** 任务审查者拿到三个路径——同一份简报文件、报告文件、审查包——外加约束该任务的全局约束。
212
212
  - 你交给审查者的全局约束块是它的**注意力透镜**。从计划的"全局约束"一节或规格里**逐字**抄下有约束力的需求:精确的取值、精确的格式,以及组件之间被明确规定的关系("与 X 相同的布局"、"匹配 Y")。审查者的模板里已经带了流程规则(YAGNI、测试卫生、审查方法)——约束块是用来装**这个项目**的规格所要求的东西的。
213
213
  - 不要在没有具体的、任务专属的理由时,加上"检查所有用法"或"有用的话跑一下竞态测试"这类开放式指令
@@ -235,7 +235,7 @@ digraph process {
235
235
 
236
236
  **每一轮,无论走哪条路:** 实现者修复、重跑覆盖被改动代码的测试、把修复报告追加到**同一个**报告文件、回传那个简短契约。重新分派审查者之前,先确认修复报告里含有覆盖用的测试、跑过的命令、以及输出;三者齐备才分派复审。在修复消息里点名覆盖用的测试文件——一行的修复不需要整包套件。
237
237
 
238
- **复审是定向的。** 运行 `scripts/review-package PLAN_FILE FIX_BASE HEAD`,其中 FIX_BASE 是上一次审查所看到的那个 head,然后用 [re-review-prompt.md](re-review-prompt.md) 分派,附上发现清单、简报、报告文件和打印出的 diff 路径。复审者对每条发现给出 ADDRESSED 或 NOT ADDRESSED 的结论,并且**只**标记修复 diff 里的新破坏。修复 diff 里新出现的 Critical/Important 破坏加入未解决发现清单。范围外的观察作为延后的 Minor 进账本——它们永远不延长循环。
238
+ **复审是定向的。** 运行 `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`,其中 FIX_BASE 是上一次审查所看到的那个 head,然后用 [re-review-prompt.md](re-review-prompt.md) 分派,附上发现清单、简报、报告文件和打印出的 diff 路径。复审者对每条发现给出 ADDRESSED 或 NOT ADDRESSED 的结论,并且**只**标记修复 diff 里的新破坏。修复 diff 里新出现的 Critical/Important 破坏加入未解决发现清单。范围外的观察作为延后的 Minor 进账本——它们永远不延长循环。
239
239
 
240
240
  **每轮结束后**往账本追加:
241
241
  `Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <发现的一句话概括>; commits <a7>..<b7>)`
@@ -261,9 +261,9 @@ digraph process {
261
261
 
262
262
  ## 最终审查
263
263
 
264
- 覆盖整个分支的最终审查也拿到一个审查包:运行 `scripts/review-package PLAN_FILE MERGE_BASE HEAD`(MERGE_BASE = 分支起点的那个提交,例如 `git merge-base main HEAD`),把打印出的路径放进最终审查的分派里,这样最终审查者读一个文件就行,不必用 git 命令重新推导整个分支的 diff。用可用的最强模型分派(见"模型选择"),使用 requesting-code-review 的 [code-reviewer.md](../requesting-code-review/code-reviewer.md)。把它指向账本里那些"延后的 Minor"和"已搁置"的行,让它甄别哪些必须在合并前修掉。
264
+ 覆盖整个分支的最终审查也拿到一个审查包:运行 `bash scripts/review-package PLAN_FILE MERGE_BASE HEAD`(MERGE_BASE = 分支起点的那个提交,例如 `git merge-base main HEAD`),把打印出的路径放进最终审查的分派里,这样最终审查者读一个文件就行,不必用 git 命令重新推导整个分支的 diff。用可用的最强模型分派(见"模型选择"),使用 requesting-code-review 的 [code-reviewer.md](../requesting-code-review/code-reviewer.md)。把它指向账本里那些"延后的 Minor"和"已搁置"的行,让它甄别哪些必须在合并前修掉。
265
265
 
266
- 如果覆盖整个分支的最终审查返回了发现,用**一个**修复子智能体带着**完整的**发现清单去分派——不要一条发现一个修复者。逐条发现各派一个修复者,每个都要重建上下文、重跑测试套件;真实会话里,一次最终审查的修复浪潮花掉的成本超过它全部任务的总和。然后对这波修复跑**恰好一次**定向复审(对修复区间跑 `scripts/review-package PLAN_FILE FIX_BASE HEAD`,用 [re-review-prompt.md](re-review-prompt.md))。残留的发现按任务循环里熔断那套来裁定:带裁定搁置,或者对承重项作出裁决并把你的决定记进账本。只有上面那四类才会在这里让你停下。**没有第二波修复**——残留的承重发现会在 finishing-a-development-branch 呈现选项时浮到你人类伙伴面前。
266
+ 如果覆盖整个分支的最终审查返回了发现,用**一个**修复子智能体带着**完整的**发现清单去分派——不要一条发现一个修复者。逐条发现各派一个修复者,每个都要重建上下文、重跑测试套件;真实会话里,一次最终审查的修复浪潮花掉的成本超过它全部任务的总和。然后对这波修复跑**恰好一次**定向复审(对修复区间跑 `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`,用 [re-review-prompt.md](re-review-prompt.md))。残留的发现按任务循环里熔断那套来裁定:带裁定搁置,或者对承重项作出裁决并把你的决定记进账本。只有上面那四类才会在这里让你停下。**没有第二波修复**——残留的承重发现会在 finishing-a-development-branch 呈现选项时浮到你人类伙伴面前。
267
267
 
268
268
  ## 收尾
269
269
 
@@ -294,7 +294,7 @@ digraph process {
294
294
 
295
295
  [准备:工作树已核实]
296
296
  [把计划文件读一遍:docs/superpowers/plans/feature-plan.md]
297
- [解析工作区:scripts/sdd-workspace docs/superpowers/plans/feature-plan.md —— 里面没有账本,全新开始]
297
+ [解析工作区:bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md —— 里面没有账本,全新开始]
298
298
  [为所有任务创建待办]
299
299
 
300
300
  任务 1:Hook 安装脚本
@@ -98,7 +98,7 @@ Subagent (general-purpose):
98
98
  - `[REPORT_FILE]` —— 实现者的报告文件(修复报告追加在其末尾)
99
99
  - `[FIX_BASE_SHA]` —— 上一次审查所看到的那个 head
100
100
  - `[HEAD_SHA]` —— 当前提交
101
- - `[DIFF_FILE]` —— `scripts/review-package PLAN_FILE FIX_BASE HEAD` 打印出的那个路径
101
+ - `[DIFF_FILE]` —— `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` 打印出的那个路径
102
102
 
103
103
  **复审者返回:** 逐条发现的结论(ADDRESSED / NOT ADDRESSED)、
104
104
  修复 diff 里的新破坏、范围外的观察,以及一个本轮结论。