@wenaixi/dsh-superpower 7.4.1 → 7.5.1
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.
- package/README.md +110 -105
- package/README.zh.md +216 -0
- package/lib/catalog.d.ts +8 -2
- package/lib/catalog.d.ts.map +1 -1
- package/lib/catalog.js +64 -9
- package/lib/catalog.js.map +1 -1
- package/lib/client.js +68 -21
- package/lib/document.d.ts +8 -2
- package/lib/document.d.ts.map +1 -1
- package/lib/document.js +14 -4
- package/lib/document.js.map +1 -1
- package/lib/superpowers.d.ts +2 -0
- package/lib/superpowers.d.ts.map +1 -1
- package/lib/superpowers.js +8 -0
- package/lib/superpowers.js.map +1 -1
- package/lib/switches.d.ts +2 -10
- package/lib/switches.d.ts.map +1 -1
- package/lib/switches.js +29 -5
- package/lib/switches.js.map +1 -1
- package/package.json +3 -3
- package/skills/brainstorming/SKILL.md +235 -171
- package/skills/brainstorming/spec-document-reviewer-prompt.md +27 -25
- package/skills/brainstorming/visual-companion.md +65 -69
- package/skills/diagnosing-superpowers/SKILL.md +107 -43
- package/skills/diagnosing-superpowers/prompts/analyst-common.md +32 -18
- package/skills/diagnosing-superpowers/prompts/cost-and-time.md +25 -9
- package/skills/diagnosing-superpowers/prompts/plan-adherence.md +26 -12
- package/skills/diagnosing-superpowers/prompts/quality-evidence.md +23 -8
- package/skills/diagnosing-superpowers/prompts/repeated-work.md +25 -14
- package/skills/diagnosing-superpowers/prompts/request-conflicts.md +18 -9
- package/skills/diagnosing-superpowers/prompts/scrub-audit.md +23 -10
- package/skills/diagnosing-superpowers/prompts/scrub.md +25 -12
- package/skills/diagnosing-superpowers/prompts/similar-session.md +30 -22
- package/skills/diagnosing-superpowers/prompts/skill-timeline.md +26 -12
- package/skills/diagnosing-superpowers/prompts/stumbles.md +24 -12
- package/skills/diagnosing-superpowers/references/context-safety.md +15 -7
- package/skills/diagnosing-superpowers/references/github-issues.md +17 -9
- package/skills/diagnosing-superpowers/references/redaction-policy.md +27 -15
- package/skills/diagnosing-superpowers/references/session-discovery.md +31 -20
- package/skills/diagnosing-superpowers/templates/bundle-README.md +66 -40
- package/skills/diagnosing-superpowers/templates/case.md +49 -42
- package/skills/diagnosing-superpowers/templates/issue.md +32 -26
- package/skills/diagnosing-superpowers/templates/report.md +54 -48
- package/skills/dispatching-parallel-agents/SKILL.md +92 -90
- package/skills/executing-plans/SKILL.md +345 -197
- package/skills/finishing-a-development-branch/SKILL.md +107 -82
- package/skills/receiving-code-review/SKILL.md +129 -127
- package/skills/requesting-code-review/SKILL.md +52 -50
- package/skills/requesting-code-review/code-reviewer.md +132 -111
- package/skills/subagent-driven-development/SKILL.md +521 -298
- package/skills/subagent-driven-development/implementer-prompt.md +138 -117
- package/skills/subagent-driven-development/re-review-prompt.md +80 -48
- package/skills/subagent-driven-development/task-reviewer-prompt.md +189 -110
- package/skills/systematic-debugging/CREATION-LOG.md +85 -85
- package/skills/systematic-debugging/SKILL.md +221 -219
- package/skills/systematic-debugging/condition-based-waiting.md +48 -49
- package/skills/systematic-debugging/defense-in-depth.md +46 -46
- package/skills/systematic-debugging/root-cause-tracing.md +63 -63
- package/skills/systematic-debugging/test-academic.md +10 -10
- package/skills/systematic-debugging/test-pressure-1.md +40 -40
- package/skills/systematic-debugging/test-pressure-2.md +58 -58
- package/skills/systematic-debugging/test-pressure-3.md +48 -48
- package/skills/test-driven-development/SKILL.md +161 -153
- package/skills/test-driven-development/writing-good-tests.md +137 -84
- package/skills/using-git-worktrees/SKILL.md +74 -72
- package/skills/using-superpowers/SKILL.md +40 -39
- package/skills/using-superpowers/references/dsh-tools.md +36 -36
- package/skills/verification-before-completion/SKILL.md +85 -83
- package/skills/writing-plans/SKILL.md +123 -84
- package/skills/writing-skills/SKILL.md +419 -417
- package/skills/writing-skills/persuasion-principles.md +118 -118
- package/skills/writing-skills/testing-skills-with-subagents.md +190 -190
|
@@ -1,57 +1,64 @@
|
|
|
1
|
-
# Case
|
|
1
|
+
# Case: <session-id>
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Workspace: ~/.superpowers/diagnosing-superpowers/<session-id>/
|
|
4
|
+
Created: <ISO timestamp>
|
|
5
5
|
|
|
6
|
-
##
|
|
6
|
+
## Problem statement (agreed with your human partner)
|
|
7
7
|
|
|
8
|
-
|
|
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
|
-
|
|
12
|
+
Goal is a superpowers bug report: yes | no
|
|
11
13
|
|
|
12
|
-
##
|
|
14
|
+
## Sessions
|
|
13
15
|
|
|
14
|
-
|
|
|
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
|
-
|
|
21
|
+
Rejected candidates: <id — path — why rejected>, or "none".
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
Session still running at read time: yes | no (mtime <ISO>, lines <N>)
|
|
22
24
|
|
|
23
|
-
##
|
|
25
|
+
## Environment
|
|
24
26
|
|
|
25
|
-
- OS
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
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
|
-
|
|
|
33
|
+
| Skill / source path | sha1 or unavailable | Provenance | Supporting location |
|
|
32
34
|
|---|---|---|---|
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
##
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
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
|
-
|
|
1
|
+
Title: <skill or symptom>: <one-line observable> (<harness>)
|
|
2
2
|
|
|
3
|
-
- [x]
|
|
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
|
-
|
|
|
10
|
-
|
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
| OS + shell | <os
|
|
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
|
-
##
|
|
16
|
+
## Is this a Superpowers issue or a platform issue?
|
|
17
17
|
|
|
18
|
-
- [ ]
|
|
18
|
+
- [ ] I confirmed this issue does not occur without Superpowers installed
|
|
19
19
|
|
|
20
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
##
|
|
42
|
+
## Debug log or conversation transcript
|
|
41
43
|
|
|
42
|
-
|
|
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
|
-
|
|
50
|
+
Filed with the `diagnosing-superpowers` skill. Model, harness, harness
|
|
51
|
+
version, and installed plugins are listed above.
|
|
@@ -1,76 +1,82 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Session diagnosis: <session-id>
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
|
|
8
|
+
<Copied from the case file.>
|
|
9
9
|
|
|
10
|
-
## 2.
|
|
10
|
+
## 2. Triage verdict (REQUIRED)
|
|
11
11
|
|
|
12
|
-
|
|
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
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
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
|
-
|
|
|
32
|
+
| Role | Session id | Absolute path | Lines | Bytes |
|
|
29
33
|
|---|---|---|---|---|
|
|
30
34
|
|
|
31
|
-
|
|
35
|
+
Rejected candidates: <id — path — why>, or "none".
|
|
32
36
|
|
|
33
|
-
## 5.
|
|
37
|
+
## 5. Timeline (REQUIRED)
|
|
34
38
|
|
|
35
|
-
|
|
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
|
-
|
|
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.
|
|
65
|
+
## 7. Superpowers involvement (REQUIRED)
|
|
61
66
|
|
|
62
|
-
|
|
67
|
+
not indicated | possible | likely
|
|
63
68
|
|
|
64
|
-
|
|
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
|
-
-
|
|
70
|
-
-
|
|
71
|
-
-
|
|
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
|
-
|
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
"
|
|
21
|
-
"
|
|
22
|
-
"
|
|
23
|
-
"
|
|
24
|
-
"
|
|
25
|
-
"
|
|
26
|
-
"
|
|
27
|
-
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
"
|
|
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
|
-
-
|
|
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
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
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.
|
|
60
|
+
### 2. Create Focused Agent Tasks
|
|
59
61
|
|
|
60
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
89
|
+
## Agent Prompt Structure
|
|
88
90
|
|
|
89
|
-
|
|
90
|
-
1.
|
|
91
|
-
2.
|
|
92
|
-
3.
|
|
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]
|
|
118
|
-
**[OK]
|
|
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]
|
|
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]
|
|
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
|
-
|
|
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
|
-
|
|
140
|
+
**Scenario:** 6 test failures across 3 files after major refactoring
|
|
139
141
|
|
|
140
|
-
|
|
141
|
-
- agent-tool-abort.test.ts
|
|
142
|
-
- batch-completion-behavior.test.ts
|
|
143
|
-
- tool-approval-race-conditions.test.ts
|
|
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
|
|
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
|
-
|
|
164
|
-
1.
|
|
165
|
-
2.
|
|
166
|
-
3.
|
|
167
|
-
4.
|
|
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
|