@wenaixi/dsh-superpower 7.4.1 → 7.5.2

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 (72) hide show
  1. package/README.md +112 -105
  2. package/README.zh.md +218 -0
  3. package/lib/catalog.d.ts +8 -2
  4. package/lib/catalog.d.ts.map +1 -1
  5. package/lib/catalog.js +64 -9
  6. package/lib/catalog.js.map +1 -1
  7. package/lib/client.js +68 -22
  8. package/lib/document.d.ts +8 -2
  9. package/lib/document.d.ts.map +1 -1
  10. package/lib/document.js +14 -4
  11. package/lib/document.js.map +1 -1
  12. package/lib/superpowers.d.ts +2 -0
  13. package/lib/superpowers.d.ts.map +1 -1
  14. package/lib/superpowers.js +32 -0
  15. package/lib/superpowers.js.map +1 -1
  16. package/lib/switches.d.ts +2 -10
  17. package/lib/switches.d.ts.map +1 -1
  18. package/lib/switches.js +33 -5
  19. package/lib/switches.js.map +1 -1
  20. package/package.json +3 -3
  21. package/skills/brainstorming/SKILL.md +235 -171
  22. package/skills/brainstorming/spec-document-reviewer-prompt.md +27 -25
  23. package/skills/brainstorming/visual-companion.md +65 -69
  24. package/skills/diagnosing-superpowers/SKILL.md +107 -43
  25. package/skills/diagnosing-superpowers/prompts/analyst-common.md +32 -18
  26. package/skills/diagnosing-superpowers/prompts/cost-and-time.md +25 -9
  27. package/skills/diagnosing-superpowers/prompts/plan-adherence.md +26 -12
  28. package/skills/diagnosing-superpowers/prompts/quality-evidence.md +23 -8
  29. package/skills/diagnosing-superpowers/prompts/repeated-work.md +25 -14
  30. package/skills/diagnosing-superpowers/prompts/request-conflicts.md +18 -9
  31. package/skills/diagnosing-superpowers/prompts/scrub-audit.md +23 -10
  32. package/skills/diagnosing-superpowers/prompts/scrub.md +25 -12
  33. package/skills/diagnosing-superpowers/prompts/similar-session.md +30 -22
  34. package/skills/diagnosing-superpowers/prompts/skill-timeline.md +26 -12
  35. package/skills/diagnosing-superpowers/prompts/stumbles.md +24 -12
  36. package/skills/diagnosing-superpowers/references/context-safety.md +15 -7
  37. package/skills/diagnosing-superpowers/references/github-issues.md +17 -9
  38. package/skills/diagnosing-superpowers/references/redaction-policy.md +27 -15
  39. package/skills/diagnosing-superpowers/references/session-discovery.md +31 -20
  40. package/skills/diagnosing-superpowers/templates/bundle-README.md +66 -40
  41. package/skills/diagnosing-superpowers/templates/case.md +49 -42
  42. package/skills/diagnosing-superpowers/templates/issue.md +32 -26
  43. package/skills/diagnosing-superpowers/templates/report.md +54 -48
  44. package/skills/dispatching-parallel-agents/SKILL.md +92 -90
  45. package/skills/executing-plans/SKILL.md +345 -197
  46. package/skills/finishing-a-development-branch/SKILL.md +107 -82
  47. package/skills/receiving-code-review/SKILL.md +129 -127
  48. package/skills/requesting-code-review/SKILL.md +52 -50
  49. package/skills/requesting-code-review/code-reviewer.md +132 -111
  50. package/skills/subagent-driven-development/SKILL.md +521 -298
  51. package/skills/subagent-driven-development/implementer-prompt.md +138 -117
  52. package/skills/subagent-driven-development/re-review-prompt.md +80 -48
  53. package/skills/subagent-driven-development/task-reviewer-prompt.md +189 -110
  54. package/skills/systematic-debugging/CREATION-LOG.md +85 -85
  55. package/skills/systematic-debugging/SKILL.md +221 -219
  56. package/skills/systematic-debugging/condition-based-waiting.md +48 -49
  57. package/skills/systematic-debugging/defense-in-depth.md +46 -46
  58. package/skills/systematic-debugging/root-cause-tracing.md +63 -63
  59. package/skills/systematic-debugging/test-academic.md +10 -10
  60. package/skills/systematic-debugging/test-pressure-1.md +40 -40
  61. package/skills/systematic-debugging/test-pressure-2.md +58 -58
  62. package/skills/systematic-debugging/test-pressure-3.md +48 -48
  63. package/skills/test-driven-development/SKILL.md +161 -153
  64. package/skills/test-driven-development/writing-good-tests.md +137 -84
  65. package/skills/using-git-worktrees/SKILL.md +74 -72
  66. package/skills/using-superpowers/SKILL.md +40 -39
  67. package/skills/using-superpowers/references/dsh-tools.md +36 -36
  68. package/skills/verification-before-completion/SKILL.md +85 -83
  69. package/skills/writing-plans/SKILL.md +123 -84
  70. package/skills/writing-skills/SKILL.md +419 -417
  71. package/skills/writing-skills/persuasion-principles.md +118 -118
  72. package/skills/writing-skills/testing-skills-with-subagents.md +190 -190
@@ -1,57 +1,64 @@
1
- # Case:<session-id>
1
+ # Case: <session-id>
2
2
 
3
- workspace:~/.superpowers/diagnosing-superpowers/<session-id>/
4
- 创建时间:<ISO 时间戳>
3
+ Workspace: ~/.superpowers/diagnosing-superpowers/<session-id>/
4
+ Created: <ISO timestamp>
5
5
 
6
- ## 问题陈述(与你的 human partner 达成一致)
6
+ ## Problem statement (agreed with your human partner)
7
7
 
8
- <一段话。指明会话(们)、已知的回合范围、期望什么、发生了什么、以及重要的可观察量:墙钟时间、token 数、重复动作、某个具体的意外动作。>
8
+ <One paragraph. Names the session(s), the turn range if known, what was
9
+ expected, what happened, and the observable that matters: wall-clock,
10
+ tokens, repeated actions, a specific unexpected action.>
9
11
 
10
- 目标是提交 superpowers 缺陷报告:是 | 否
12
+ Goal is a superpowers bug report: yes | no
11
13
 
12
- ## 会话
14
+ ## Sessions
13
15
 
14
- | 角色 | 会话 id | 绝对路径 | 行数 | 字节 | 最长行(字节) | 首个 prompt(前 120 字符) | 首个时间戳 |
16
+ | Role | Session id | Absolute path | Lines | Bytes | Longest line (bytes) | First prompt (first 120 chars) | First timestamp |
15
17
  |---|---|---|---|---|---|---|---|
16
- | 主会话 | | | | | | | |
18
+ | main | | | | | | | |
17
19
  | subagent | | | | | | | |
18
20
 
19
- 被拒候选:<id — 路径 — 拒绝原因>,或"无"。
21
+ Rejected candidates: <id — path — why rejected>, or "none".
20
22
 
21
- 读取时会话仍在运行:是 | 否(mtime <ISO>,行数 <N>)
23
+ Session still running at read time: yes | no (mtime <ISO>, lines <N>)
22
24
 
23
- ## 环境
25
+ ## Environment
24
26
 
25
- - OS:<名称与版本>
26
- - harness:<name> <version>
27
- - 所见模型:<model id — 位置(主会话 / subagent id)>
28
- - superpowers 安装根:<路径>;版本 <x.y.z>;git sha <sha 或 "not a checkout">
29
- - 会话期间读取或注入的技能文件:
27
+ - OS: <name and version>
28
+ - Harness: <name> <version>
29
+ - Models seen: <model id — where (main / subagent id)>
30
+ - Superpowers install root: <path>; version <x.y.z>; git sha <sha or "not a checkout">
31
+ - Skill files read or injected during the session:
30
32
 
31
- | 技能 / 来源路径 | sha1 或不可用 | 来源 | 支撑位置 |
33
+ | Skill / source path | sha1 or unavailable | Provenance | Supporting location |
32
34
  |---|---|---|---|
33
35
 
34
- 把环境与技能观察标记为 历史证据 / 未验证快照 / 当前观察 / 未知。在宣布历史信息不可用之前,检查提供的来源说明、归档与被捕获的技能正文。缺失原始路径不会抹去保留的副本。当前版本/mtime 不能确立历史版本;一份被捕获的技能正文不能认证整个安装。
35
-
36
- - 已配置的其他插件 / 扩展 / MCP 服务器:<列表,或 "none found">
37
- - 存在的指令文件(仅路径):<列表>
38
-
39
- ## 这些文件的每个读者都应遵守的上下文安全规则
40
-
41
- - 读取此处列出的任何文件前,遵循 `references/context-safety.md`。
42
- - 在 subagent transcript 中,"user"是父代理。
43
-
44
- ## 已发现来源与记录含义
45
-
46
- - 查阅的来源:<绝对路径、工具、帮助或文档来源>
47
- - 提取命令或查询:<对每个来源使用的有界命令或工具查询>
48
- - 目标身份证据:<会话 id、工作目录、时间戳、匹配内容与支撑记录位置>
49
- - 关联会话:<会话 id、关系与支撑记录位置,或 "none found">
50
- - 人类消息:<记录形状与含义证据>
51
- - 注入消息与父代理派发:<记录形状与含义证据>
52
- - 助手消息:<记录形状与含义证据>
53
- - 工具调用与结果:<记录形状、如何匹配及含义证据>
54
- - 用量计数器:<字段、增量或累计语义、单位与证据,或 "unavailable">
55
- - 时序:<字段、单位、事件边界与证据,或 "unavailable">
56
- - 其他相关记录:<模型、版本、压缩或其它含义与证据>
57
- - 未解决信息:<缺失、不可访问、歧义或不存在的信息,或 "none">
36
+ Label environment and skill observations as historical evidence, unverified
37
+ snapshot, current observation, or unknown. Check supplied provenance notes,
38
+ archives and captured skill bodies before declaring historical information
39
+ unavailable. Missing original paths do not erase retained copies. Current
40
+ versions/mtimes do not establish historical versions; one captured skill body
41
+ does not authenticate an entire installation.
42
+
43
+ - Other plugins / extensions / MCP servers configured: <list, or "none found">
44
+ - Instruction files present (paths only): <list>
45
+
46
+ ## Context-safety rules for every reader of these files
47
+
48
+ - Follow `references/context-safety.md` before reading any file listed here.
49
+ - In a subagent transcript, "user" is the parent agent.
50
+
51
+ ## Discovered sources and record meanings
52
+
53
+ - Sources consulted: <absolute path, tool, help, or documentation source>
54
+ - Extraction commands or queries: <bounded commands or tool queries used for each source>
55
+ - Target identity evidence: <session id, working directory, timestamps, matching content, and supporting record locations>
56
+ - Associated sessions: <session id, relationship, and supporting record locations, or "none found">
57
+ - Human messages: <record shape and evidence for its meaning>
58
+ - Injected messages and parent dispatches: <record shape and evidence for its meaning>
59
+ - Assistant messages: <record shape and evidence for its meaning>
60
+ - Tool calls and results: <record shapes, how they match, and evidence for those meanings>
61
+ - Usage counters: <fields, incremental or cumulative semantics, units, and evidence, or "unavailable">
62
+ - Timing: <fields, units, event boundaries, and evidence, or "unavailable">
63
+ - Other relevant records: <models, versions, compactions, or other meanings and evidence>
64
+ - Unresolved information: <missing, inaccessible, ambiguous, or absent information, or "none">
@@ -1,45 +1,51 @@
1
- 标题:<技能或症状>:<一行可观察量>(<harness>)
1
+ Title: <skill or symptom>: <one-line observable> (<harness>)
2
2
 
3
- - [x] 我已搜索现有 issue 且这不是重复(搜索:<查询词>;最接近:<#n 标题,或 "none">)
3
+ - [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
4
4
 
5
- ## 环境(必填)
5
+ ## Environment (required)
6
6
 
7
- | 字段 | 值 | 来源 / 支撑证据 |
7
+ | Field | Value | Provenance / supporting evidence |
8
8
  |-------|-------|-------------------------------|
9
- | superpowers 版本 | <version>(<sha 或 "not a checkout">) | <历史证据 / 未验证快照 / 当前观察 / 未知>;<位置> |
10
- | harness (DSH) | <harness> | <标签>;<位置> |
11
- | harness 版本 | <version> | <标签>;<位置> |
12
- | 你的模型 + 版本 | <所见 model ids> | <标签>;<位置> |
13
- | 已安装的全部插件 | <列表> | <标签>;<位置> |
14
- | OS + shell | <os 版本>, <shell> | <标签>;<位置> |
9
+ | Superpowers version | <version> (<sha or "not a checkout">) | <historical evidence / unverified snapshot / current observation / unknown>; <location> |
10
+ | Harness (Claude Code, Cursor, etc.) | <harness> | <label>; <location> |
11
+ | Harness version | <version> | <label>; <location> |
12
+ | Your model + version | <model ids seen> | <label>; <location> |
13
+ | All plugins installed | <list> | <label>; <location> |
14
+ | OS + shell | <os version>, <shell> | <label>; <location> |
15
15
 
16
- ## 这是 superpowers 问题还是平台问题?
16
+ ## Is this a Superpowers issue or a platform issue?
17
17
 
18
- - [ ] 我确认未安装 superpowers 时该问题不会出现
18
+ - [ ] I confirmed this issue does not occur without Superpowers installed
19
19
 
20
- 报告者尚未尝试在不安装 superpowers 的情况下复现。参与程度的证据见下;它不确立因果。
20
+ The reporter has not tried reproducing without superpowers. Evidence for
21
+ involvement is below; it does not establish cause.
21
22
 
22
- ## 发生了什么?
23
+ ## What happened?
23
24
 
24
- <问题陈述,然后是分诊结论,`path:line` 引用改写为 `transcript line <n>`。>
25
+ <Problem statement, then the triage verdict, with `path:line` citations
26
+ rewritten as `transcript line <n>`.>
25
27
 
26
- ## 复现步骤
28
+ ## Steps to reproduce
27
29
 
28
- 1. <首个人类 prompt,已脱敏>
29
- 2. <导致问题的回合,每行一个>
30
- 3. <可观察量>
30
+ 1. <first human prompt, scrubbed>
31
+ 2. <the turns leading to the problem, one line each>
32
+ 3. <the observable>
31
33
 
32
- ## 预期行为
34
+ ## Expected behavior
33
35
 
34
- <来自问题陈述>
36
+ <from the problem statement>
35
37
 
36
- ## 实际行为
38
+ ## Actual behavior
37
39
 
38
- <来自分诊结论>
40
+ <from the triage verdict>
39
41
 
40
- ## 调试日志或会话 transcript
42
+ ## Debug log or conversation transcript
41
43
 
42
- 会话 id:<ids>。交付的本地归档:<路径,脱敏级别 <级别> | 未构建>。附加 bundle:<不声明;仅在批准后附加>。诊断报告所述的 superpowers 参与程度:<possible | likely>,证据位于 <transcript 行>。本报告不提出修复。
44
+ Session id(s): <ids>. Delivered local archive: <path, redaction level <level>
45
+ | none built>. Attached bundle: <no claim; attach only after approval>.
46
+ Superpowers involvement per the diagnosis report: <possible | likely>, with
47
+ evidence at <transcript lines>. This report does not propose a fix.
43
48
 
44
49
  ---
45
- 使用 `diagnosing-superpowers` 技能提交。模型、harness、harness 版本与已安装插件列于上方。
50
+ Filed with the `diagnosing-superpowers` skill. Model, harness, harness
51
+ version, and installed plugins are listed above.
@@ -1,76 +1,82 @@
1
- # 会话诊断:<session-id>
1
+ # Session diagnosis: <session-id>
2
2
 
3
- 报告路径:~/.superpowers/diagnosing-superpowers/<session-id>/report.md
4
- 撰写时间:<ISO 时间戳>
3
+ Report path: ~/.superpowers/diagnosing-superpowers/<session-id>/report.md
4
+ Written: <ISO timestamp>
5
5
 
6
- ## 1. 问题陈述(必填)
6
+ ## 1. Problem statement (REQUIRED)
7
7
 
8
- <从 case 文件复制。>
8
+ <Copied from the case file.>
9
9
 
10
- ## 2. 分诊结论(必填)
10
+ ## 2. Triage verdict (REQUIRED)
11
11
 
12
- <证据显示报告问题周围实际发生了什么。散文式,每条论断后带 `path:line`。说明置信度:高 / 中 / 低,以及什么能提高它。不陈述 superpowers 应该做什么。>
12
+ <What the evidence shows happened around the reported problem. Prose, with
13
+ `path:line` after every claim. State confidence: high / medium / low, and
14
+ what would raise it. No statement about what superpowers should do.>
13
15
 
14
- ## 3. 环境(必填)
16
+ ## 3. Environment (REQUIRED)
15
17
 
16
- - OS:
17
- - harness 与版本:
18
- - 所见模型:
19
- - superpowers 安装根 / 版本 / git sha:
20
- - 读取或注入的技能文件(来自 case 文件的 sha1 表):
21
- - 其他插件、扩展、MCP 服务器:
22
- - 存在的指令文件(仅路径):
18
+ - OS:
19
+ - Harness and version:
20
+ - Models seen:
21
+ - Superpowers install root / version / git sha:
22
+ - Skill files read or injected (sha1 table from the case file):
23
+ - Other plugins, extensions, MCP servers:
24
+ - Instruction files present (paths only):
23
25
 
24
- 把每个环境字段与技能观察标记为 历史证据 / 未验证快照 / 当前观察 / 未知,并记录其支撑证据位置。
26
+ Label every environment field and skill observation as historical evidence,
27
+ unverified snapshot, current observation, or unknown, and record its
28
+ supporting evidence location.
25
29
 
26
- ## 4. 检视的会话(必填)
30
+ ## 4. Sessions examined (REQUIRED)
27
31
 
28
- | 角色 | 会话 id | 绝对路径 | 行数 | 字节 |
32
+ | Role | Session id | Absolute path | Lines | Bytes |
29
33
  |---|---|---|---|---|
30
34
 
31
- 被拒候选:<id — 路径 — 原因>,或"无"。
35
+ Rejected candidates: <id — path — why>, or "none".
32
36
 
33
- ## 5. 时间线(必填)
37
+ ## 5. Timeline (REQUIRED)
34
38
 
35
- 每条人类输入的 prompt 一行。事件列列出被调用的技能、派发的 subagent、压缩、错误、恢复、中止。
39
+ One row per human-typed prompt. Events column lists skills invoked,
40
+ subagents dispatched, compaction, errors, resumes, aborts.
36
41
 
37
- | 回合 | 行 | 时间 | 请求(一行) | 事件 |
42
+ | Turn | Line | Time | Request (one line) | Events |
38
43
  |---|---|---|---|---|
39
44
 
40
- ## 6. 发现(必填,每个维度一小节)
45
+ ## 6. Findings (REQUIRED, one subsection per dimension)
41
46
 
42
- 每条发现:
47
+ Each finding:
43
48
  ```
44
- - finding: <一句话>
45
- evidence: <path:line> — "<短引文>"
46
- turns: <首>–<末>
47
- confidence: 高 | 中 | 低
49
+ - finding: <one sentence>
50
+ evidence: <path:line> — "<short quote>"
51
+ turns: <first>–<last>
52
+ confidence: high | medium | low
48
53
  ```
49
- 无内容可报的维度写 `none found — checked: <检查了什么>`。
54
+ A dimension with nothing to report says `none found — checked: <what was checked>`.
50
55
 
51
- ### 6.1 技能时间线
52
- ### 6.2 计划遵守
53
- ### 6.3 重复工作
54
- ### 6.4 磕绊
55
- ### 6.5 质量证据
56
- ### 6.6 请求冲突
57
- ### 6.7 成本与时间
58
- ### 6.8 使用的其他插件与技能
56
+ ### 6.1 Skill timeline
57
+ ### 6.2 Plan adherence
58
+ ### 6.3 Repeated work
59
+ ### 6.4 Stumbles
60
+ ### 6.5 Quality evidence
61
+ ### 6.6 Request conflicts
62
+ ### 6.7 Cost and time
63
+ ### 6.8 Other plugins and skills used
59
64
 
60
- ## 7. superpowers 参与程度(必填)
65
+ ## 7. Superpowers involvement (REQUIRED)
61
66
 
62
- 未指示 | 可能 | 很可能
67
+ not indicated | possible | likely
63
68
 
64
- 证据行:<path:line 列表>。本节仅陈述参与程度。它不指认缺陷,也不提出修改。
69
+ Evidence lines: <path:line list>. This section states involvement only. It
70
+ does not name a defect and does not propose a change.
65
71
 
66
- ## 8. 覆盖范围说明(必填)
72
+ ## 8. Coverage notes (REQUIRED)
67
73
 
68
- - 未读:<范围、文件与原因>
69
- - harness 功能不可用:<列表或无>
70
- - 读取时会话在进行中:是/否
71
- - 需要你的 human partner 复核:<列表或无>
74
+ - Not read: <ranges, files, and why>
75
+ - Harness features unavailable: <list or none>
76
+ - Session was in progress at read time: yes/no
77
+ - For your human partner to double-check: <list or none>
72
78
 
73
- ## 9. 相似会话(仅应要求时)
79
+ ## 9. Similar sessions (only when requested)
74
80
 
75
- | 会话 id | 路径 | 日期 | harness | 匹配 | 未匹配 |
76
- |---|---|---|---|---|---|
81
+ | Session id | Path | Date | Harness | Matched | Did not match |
82
+ |---|---|---|---|---|---|
@@ -1,95 +1,97 @@
1
1
  ---
2
2
  name: dispatching-parallel-agents
3
- description: "Superpower Skill:面向 2 个以上无共享状态、无前后依赖的独立任务,并行委派多个 subagent 协同处理的高效分发模式。"
3
+ description: "Superpower Skill: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies"
4
+ description_zh: "Superpower Skill:面向 2 个以上无共享状态、无前后依赖的独立任务,并行委派多个 subagent 协同处理的高效分发模式。"
4
5
  ---
5
6
 
6
- # 并行分发 agent
7
7
 
8
- ## 概述
8
+ # Dispatching Parallel Agents
9
9
 
10
- 你将任务委派给拥有隔离上下文的专用 agent。通过精确构造指令与上下文,确保它们保持专注并成功完成任务。它们不应继承你当前会话的上下文或历史——你需要按需精确构造所需信息。这也能保留你自身的上下文,用于统筹协调工作。
10
+ ## Overview
11
11
 
12
- 当存在多个互不相关的失败时(不同的测试文件、不同的子系统、不同的缺陷),串行排查会浪费大量时间。每一项排查都是独立的,可以并行进行。
12
+ You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
13
13
 
14
- **核心原则:** 每个独立的问题域分派一个 agent,让它们并发执行。
14
+ When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
15
15
 
16
- ## 何时使用
16
+ **Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
17
+
18
+ ## When to Use
17
19
 
18
20
  ```dot
19
21
  digraph when_to_use {
20
- "存在多个失败?" [shape=diamond];
21
- "是否相互独立?" [shape=diamond];
22
- "由单个 agent 统一排查" [shape=box];
23
- "每个问题域分配一个 agent" [shape=box];
24
- "能否并行执行?" [shape=diamond];
25
- "串行分发 agent" [shape=box];
26
- "并行分发" [shape=box];
27
-
28
- "存在多个失败?" -> "是否相互独立?" [label="是"];
29
- "是否相互独立?" -> "由单个 agent 统一排查" [label="否 - 存在关联"];
30
- "是否相互独立?" -> "能否并行执行?" [label="是"];
31
- "能否并行执行?" -> "并行分发" [label="是"];
32
- "能否并行执行?" -> "串行分发 agent" [label="否 - 存在共享状态"];
22
+ "Multiple failures?" [shape=diamond];
23
+ "Are they independent?" [shape=diamond];
24
+ "Single agent investigates all" [shape=box];
25
+ "One agent per problem domain" [shape=box];
26
+ "Can they work in parallel?" [shape=diamond];
27
+ "Sequential agents" [shape=box];
28
+ "Parallel dispatch" [shape=box];
29
+
30
+ "Multiple failures?" -> "Are they independent?" [label="yes"];
31
+ "Are they independent?" -> "Single agent investigates all" [label="no - related"];
32
+ "Are they independent?" -> "Can they work in parallel?" [label="yes"];
33
+ "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
34
+ "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
33
35
  }
34
36
  ```
35
37
 
36
- **适用场景:**
37
- - 3 个以上测试文件失败,且根因各不相同
38
- - 多个子系统各自独立出现故障
39
- - 每个问题无需依赖其他问题的上下文即可理解
40
- - 各排查过程之间不存在共享状态
38
+ **Use when:**
39
+ - 3+ test files failing with different root causes
40
+ - Multiple subsystems broken independently
41
+ - Each problem can be understood without context from others
42
+ - No shared state between investigations
41
43
 
42
- **不适用场景:**
43
- - 失败之间存在关联(修复一个可能顺带修复其他)
44
- - 需要理解完整的系统状态
45
- - agent 之间会相互干扰
44
+ **Don't use when:**
45
+ - Failures are related (fix one might fix others)
46
+ - Need to understand full system state
47
+ - Agents would interfere with each other
46
48
 
47
- ## 使用模式
49
+ ## The Pattern
48
50
 
49
- ### 1. 识别独立的问题域
51
+ ### 1. Identify Independent Domains
50
52
 
51
- 按故障点对失败进行分组:
52
- - 文件 A 测试:工具审批流程
53
- - 文件 B 测试:批量完成行为
54
- - 文件 C 测试:中止功能
53
+ Group failures by what's broken:
54
+ - File A tests: Tool approval flow
55
+ - File B tests: Batch completion behavior
56
+ - File C tests: Abort functionality
55
57
 
56
- 每个领域都是独立的——修复工具审批不会影响中止相关的测试。
58
+ Each domain is independent - fixing tool approval doesn't affect abort tests.
57
59
 
58
- ### 2. 创建聚焦的 agent 任务
60
+ ### 2. Create Focused Agent Tasks
59
61
 
60
- 每个 agent 应获得:
61
- - **明确范围:** 单个测试文件或子系统
62
- - **清晰目标:** 让这些测试通过
63
- - **约束条件:** 不得改动其他代码
64
- - **预期输出:** 发现了什么、修复了什么的总结
62
+ Each agent gets:
63
+ - **Specific scope:** One test file or subsystem
64
+ - **Clear goal:** Make these tests pass
65
+ - **Constraints:** Don't change other code
66
+ - **Expected output:** Summary of what you found and fixed
65
67
 
66
- ### 3. 并行分发
68
+ ### 3. Dispatch in Parallel
67
69
 
68
- 在同一条回复中一次性发起全部三个 subagent 分发——它们将并行运行:
70
+ Issue all three subagent dispatches in the same response — they run in parallel:
69
71
 
70
72
  ```text
71
73
  Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
72
74
  Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
73
75
  Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
74
- # 全部三个并发执行。
76
+ # All three run concurrently.
75
77
  ```
76
78
 
77
- 在同一条回复中发起多次分发调用 = 并行执行。每条回复只发一次 = 串行执行。
79
+ Multiple dispatch calls in one response = parallel execution. One per response = sequential.
78
80
 
79
- ### 4. 复核与集成
81
+ ### 4. Review and Integrate
80
82
 
81
- 当 agent 返回后:
82
- - 阅读每一份总结
83
- - 验证各修复之间是否存在冲突
84
- - 运行完整测试套件
85
- - 整合所有变更
83
+ When agents return:
84
+ - Read each summary
85
+ - Verify fixes don't conflict
86
+ - Run full test suite
87
+ - Integrate all changes
86
88
 
87
- ## agent prompt 结构
89
+ ## Agent Prompt Structure
88
90
 
89
- 优秀的 agent prompt应具备:
90
- 1. **聚焦** - 一个清晰的问题域
91
- 2. **自包含** - 包含理解问题所需的全部上下文
92
- 3. **输出明确** - agent 应该返回什么?
91
+ Good agent prompts are:
92
+ 1. **Focused** - One clear problem domain
93
+ 2. **Self-contained** - All context needed to understand the problem
94
+ 3. **Specific about output** - What should the agent return?
93
95
 
94
96
  ```markdown
95
97
  Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
@@ -112,56 +114,56 @@ Do NOT just increase timeouts - find the real issue.
112
114
  Return: Summary of what you found and what you fixed.
113
115
  ```
114
116
 
115
- ## 常见错误
117
+ ## Common Mistakes
116
118
 
117
- **[FAIL] 范围过大:** "修复所有测试" - agent 容易迷失方向
118
- **[OK] 具体明确:** "修复 agent-tool-abort.test.ts" - 范围聚焦
119
+ **[FAIL] Too broad:** "Fix all the tests" - agent gets lost
120
+ **[OK] Specific:** "Fix agent-tool-abort.test.ts" - focused scope
119
121
 
120
- **[FAIL] 缺乏上下文:** "修复竞态条件" - agent 不知道位置
121
- **[OK] 提供上下文:** 粘贴错误信息和测试名称
122
+ **[FAIL] No context:** "Fix the race condition" - agent doesn't know where
123
+ **[OK] Context:** Paste the error messages and test names
122
124
 
123
- **[FAIL] 缺少约束:** agent 可能会重构所有内容
124
- **[OK] 明确约束:** "不要改动生产代码" 或 "仅修复测试"
125
+ **[FAIL] No constraints:** Agent might refactor everything
126
+ **[OK] Constraints:** "Do NOT change production code" or "Fix tests only"
125
127
 
126
- **[FAIL] 输出模糊:** "修好它" - 你无法知道改了什么
127
- **[OK] 输出具体:** "返回根因与变更总结"
128
+ **[FAIL] Vague output:** "Fix it" - you don't know what changed
129
+ **[OK] Specific:** "Return summary of root cause and changes"
128
130
 
129
- ## 何时不应使用
131
+ ## When NOT to Use
130
132
 
131
- **存在关联的失败:** 修复一个可能顺带修复其他——应先一起排查
132
- **需要完整上下文:** 理解问题需要看到整个系统
133
- **探索式调试:** 尚不清楚哪里出了问题
134
- **存在共享状态:** agent 会相互干扰(编辑同一文件、占用同一资源)
133
+ **Related failures:** Fixing one might fix others - investigate together first
134
+ **Need full context:** Understanding requires seeing entire system
135
+ **Exploratory debugging:** You don't know what's broken yet
136
+ **Shared state:** Agents would interfere (editing same files, using same resources)
135
137
 
136
- ## 来自真实会话的示例
138
+ ## Real Example from Session
137
139
 
138
- **场景:** 大规模重构后,3 个文件共出现 6 个测试失败
140
+ **Scenario:** 6 test failures across 3 files after major refactoring
139
141
 
140
- **失败情况:**
141
- - agent-tool-abort.test.ts:3 个失败(时序问题)
142
- - batch-completion-behavior.test.ts:2 个失败(工具未执行)
143
- - tool-approval-race-conditions.test.ts:1 个失败(执行次数为 0)
142
+ **Failures:**
143
+ - agent-tool-abort.test.ts: 3 failures (timing issues)
144
+ - batch-completion-behavior.test.ts: 2 failures (tools not executing)
145
+ - tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
144
146
 
145
- **决策:** 属于独立领域——中止逻辑、批量完成、竞态条件三者相互分离
147
+ **Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
146
148
 
147
- **分发:**
149
+ **Dispatch:**
148
150
  ```
149
151
  Agent 1 → Fix agent-tool-abort.test.ts
150
152
  Agent 2 → Fix batch-completion-behavior.test.ts
151
153
  Agent 3 → Fix tool-approval-race-conditions.test.ts
152
154
  ```
153
155
 
154
- **结果:**
155
- - Agent 1:用基于事件的等待替代了固定超时
156
- - Agent 2:修复了事件结构缺陷(threadId 位置错误)
157
- - Agent 3:增加了对异步工具执行完成的等待
156
+ **Results:**
157
+ - Agent 1: Replaced timeouts with event-based waiting
158
+ - Agent 2: Fixed event structure bug (threadId in wrong place)
159
+ - Agent 3: Added wait for async tool execution to complete
158
160
 
159
- **集成:** 所有修复相互独立,无冲突,全量测试通过
161
+ **Integration:** All fixes independent, no conflicts, full suite green
160
162
 
161
- ## 验证
163
+ ## Verification
162
164
 
163
- agent 返回后:
164
- 1. **复核每份总结** - 理解变更内容
165
- 2. **检查是否存在冲突** - agent 是否编辑了同一段代码?
166
- 3. **运行全量测试** - 验证所有修复协同工作正常
167
- 4. **抽样检查** - agent 可能存在系统性错误
165
+ After agents return:
166
+ 1. **Review each summary** - Understand what changed
167
+ 2. **Check for conflicts** - Did agents edit same code?
168
+ 3. **Run full suite** - Verify all fixes work together
169
+ 4. **Spot check** - Agents can make systematic errors