@loneexile/omp-superpowers 7.0.0-omp.3 → 7.0.1-omp.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.
Files changed (26) hide show
  1. package/CHANGELOG.md +26 -1
  2. package/README.md +9 -6
  3. package/agents/sdd-escalation-implementer.md +3 -2
  4. package/agents/sdd-implementer.md +1 -1
  5. package/package.json +1 -1
  6. package/skills/brainstorming/SKILL.md +96 -34
  7. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  8. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  9. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  10. package/skills/executing-plans/SKILL.md +22 -57
  11. package/skills/finishing-a-development-branch/SKILL.md +5 -1
  12. package/skills/subagent-driven-development/SKILL.md +145 -50
  13. package/skills/subagent-driven-development/implementer-prompt.md +12 -4
  14. package/skills/subagent-driven-development/re-review-prompt.md +4 -2
  15. package/skills/subagent-driven-development/task-reviewer-prompt.md +3 -1
  16. package/skills/using-superpowers/references/pi-tools.md +1 -1
  17. package/skills/writing-plans/SKILL.md +8 -5
  18. package/skills/writing-skills/SKILL.md +21 -303
  19. package/skills/writing-skills/references/bulletproofing.md +80 -0
  20. package/skills/writing-skills/references/discovery.md +201 -0
  21. package/skills/writing-skills/references/flowcharts.md +37 -0
  22. package/skills/writing-skills/{testing-skills-with-subagents.md → references/testing-skills-with-subagents.md} +2 -2
  23. /package/skills/writing-skills/{examples → references}/CLAUDE_MD_TESTING.md +0 -0
  24. /package/skills/writing-skills/{anthropic-best-practices.md → references/anthropic-best-practices.md} +0 -0
  25. /package/skills/writing-skills/{graphviz-conventions.dot → references/graphviz-conventions.dot} +0 -0
  26. /package/skills/writing-skills/{persuasion-principles.md → references/persuasion-principles.md} +0 -0
@@ -29,7 +29,9 @@ operation; a security-sensitive action; a side effect outside this worktree
29
29
  that norms say you ask about first (a merge, a push to a shared branch, a
30
30
  publish); and a plan so broken that every path forward is a guess. For those,
31
31
  stop and ask. This skill's own wave merges into the plan branch, and the task
32
- worktrees it creates and removes, are not among them.
32
+ worktrees it creates and removes, are not among them. It adds two stops of
33
+ its own: a wave task that still will not merge after its rounds (`merge
34
+ stuck`), and a wave suite still red after its one fix.
33
35
 
34
36
  **On omp in vibe mode** (your tools include `vibe_spawn` but not `task`)
35
37
  you are the director, and this loop cannot run in your session: you have
@@ -153,12 +155,29 @@ digraph process {
153
155
 
154
156
  ## Setup
155
157
 
156
- Ensure the work happens in an isolated workspace: use
157
- superpowers:using-git-worktrees to create one or verify the existing one.
158
- Never start implementation on a main/master branch without your human
159
- partner's explicit consent.
160
-
161
- **On omp, the session must be in the worktree before you dispatch.** A
158
+ Ensure the work happens in an isolated workspace. If the plan's approval
159
+ named a new branch in this checkout (writing-plans' default), that approval
160
+ was your human partner's answer to superpowers:using-git-worktrees' consent
161
+ question: work in place, with no worktree and no `/move`.
162
+
163
+ - **A ledger for this plan exists** (below): `git switch` to the branch its
164
+ `Setup:` line names, and resume from the ledger. Run nothing else here.
165
+ - **First run:** run `git status --porcelain`. If it lists a change to a
166
+ tracked file, or anything staged, ask your human partner to commit or
167
+ stash it first: a run in place commits from this index and tests this
168
+ working tree, so their uncommitted work would land in task commits and in
169
+ every test result. Untracked files may stay; note them, and they stay out
170
+ of every commit. If a branch with the approved name already exists, ask,
171
+ or name another. Then `git switch -c <branch>`, run
172
+ using-git-worktrees' Step 2 (project setup) and Step 3 (baseline tests)
173
+ here, and, once the ledger exists, ledger `Setup: branch <branch> in this
174
+ checkout; untracked before start: <paths | none>`.
175
+
176
+ Otherwise use superpowers:using-git-worktrees to create a worktree or
177
+ verify the existing one. Never start implementation on a main/master branch
178
+ without your human partner's explicit consent.
179
+
180
+ **On omp, a session worktree needs `/move` before you dispatch.** A
162
181
  subagent starts in the session's cwd (the `task` tool has no `cwd`
163
182
  argument), so after `omp worktree add` every SDD subagent still works in the
164
183
  ORIGINAL checkout until your human partner runs `/move <path>`. Get `/move`
@@ -193,19 +212,43 @@ a ledger file, not only in todos.
193
212
  working directory at the repo root — the scripts call `git rev-parse`.
194
213
  The invocation lines in this skill stay as upstream wrote them.
195
214
  - Check for this plan's ledger at `<workspace>/progress.md`. If its first
196
- line names your plan file, tasks with a `Task <N>: complete` line are DONE
197
- — do not re-dispatch them; resume at the first task without one. A task
198
- whose last line is `dispatched` or `re-dispatched` is mid-implementation:
199
- check `git log` from its BASE (on its task branch, for a wave task whose
200
- `dispatched` line names a worktree) and read `agent://<id>` before you
201
- dispatch anything. A wave task whose last line is `merged` is merged: clean
202
- up its worktree and branch (Complete the task) and write its `complete`
203
- line. A wave task whose branch tip is already an ancestor of the plan
204
- branch (`git merge-base --is-ancestor <branch> HEAD`) merged before the
205
- ledger caught up: ledger `merged` and do the same. A worktree that exists
206
- for a task with no `dispatched` line is reused, not added again. A task
207
- whose last line is a fix round is mid-loop: resume the loop at the next
208
- round. A ledger whose first line names a different plan file — or a stray
215
+ line names your plan file, first find wave tasks that merged before the
216
+ ledger caught up: for every wave task whose branch still exists and that
217
+ has no `merged` line, whatever its last line, the merge happened when the
218
+ branch has commits past its BASE (`git rev-list --count <BASE>..<branch>`
219
+ is 1 or more) AND its tip is an ancestor of the plan branch (`git
220
+ merge-base --is-ancestor <branch> HEAD`); ledger `merged` for it. A
221
+ branch with no commits past BASE also passes the ancestor test; it is an
222
+ unstarted or lost task, never a merged one. Then take each task by its
223
+ last ledger line:
224
+ - `complete`: DONE — do not re-dispatch it; resume at the first task
225
+ without one.
226
+ - `merged`: clean up its worktree and branch (Complete the task) and
227
+ write its `complete` line.
228
+ - `dispatched` or `re-dispatched`: mid-implementation. Check `git log`
229
+ from its BASE (on its task branch, for a wave task whose line names a
230
+ worktree) and read `agent://<id>` before you dispatch anything.
231
+ - `fix round` or `rebased`: read `agent://<id>` first, and wait for a
232
+ round still running. A `rebased` round that reported goes back to its
233
+ merge; a `fix round` line with findings open goes to the next round,
234
+ and one with none open completes the task. The two kinds of line
235
+ together count toward the task's three rounds.
236
+ - `review per-task — <class or reason>`: with no `dispatched` line before
237
+ it, the task has not started; after one, the task reported and awaits
238
+ that review.
239
+ - `merge stuck`: the run is stopped; wait for your human partner.
240
+ - A worktree that exists for a task with no `dispatched` line is reused,
241
+ not added again, and gets the install step and its check again
242
+ (Dispatch the implementer).
243
+
244
+ Then check the plan checkout. A merge in progress (`git rev-parse -q
245
+ --verify MERGE_HEAD` prints a commit) was interrupted: run `git merge
246
+ --abort` and redo that task's merge (Complete the task). A wave of two or
247
+ more whose tasks are all complete still needs its suite run, or its fix
248
+ and rerun, before the next wave or the final review unless its last
249
+ `Wave <K>:` line is `suite pass`.
250
+
251
+ A ledger whose first line names a different plan file — or a stray
209
252
  ledger at the old flat path `.superpowers/sdd/progress.md` — is another
210
253
  plan's progress: leave it in place and start your own, fresh.
211
254
  - Create the ledger with its identity as the first line:
@@ -253,8 +296,8 @@ batch (below) counts as one task. Ledger one line per task, `Task <N>:
253
296
  review per-task — <class>` or `Task <N>: review at final`. The final
254
297
  whole-branch review does the task review's work for every `review at final`
255
298
  task. A task joins the list mid-run, ledgered as `Task <N>: review per-task
256
- — <reason>`, when its report is DONE_WITH_CONCERNS about correctness, it
257
- went BLOCKED, or its implementer needed 100+ turns.
299
+ — <reason>`, when its report is DONE_WITH_CONCERNS about correctness or
300
+ scope, it went BLOCKED, or its implementer needed 100+ turns.
258
301
 
259
302
  **The waves.** Tasks with no row between them in the scan table (no shared
260
303
  file, no shared interface), whose `Consumes` all come from earlier waves,
@@ -267,7 +310,8 @@ time (a fixed port, a database, a cache directory). Ledger
267
310
  is one long chain gets one task per wave and runs in sequence, and so does
268
311
  every plan whose checkout has uncommitted changes to tracked files
269
312
  (`git status --porcelain --untracked-files=no` not empty): a merge needs
270
- them committed or stashed. Untracked files do not block a wave.
313
+ them committed or stashed. Untracked files keep waves on, but git refuses
314
+ to start a merge that would overwrite one (Complete the task).
271
315
 
272
316
  ## Agent Selection
273
317
 
@@ -531,20 +575,36 @@ the wave's BASE.
531
575
 
532
576
  `<plan>` is the plan file's name without `.md`;
533
577
  superpowers:using-git-worktrees says why `omp worktree add` and
534
- `~/.omp/wt/`. If the add warns that the clone fell back to a plain
535
- checkout, the worktree lacks `node_modules` and other ignored build
536
- output: run the plan's install step there before dispatching. A wave of
537
- one runs in the plan checkout, with no extra worktree.
578
+ `~/.omp/wt/`. Then, in each new worktree and before dispatching, run the
579
+ project's install step there (`npm ci`, `uv sync`, the plan's setup
580
+ command), even when the clone succeeded. A clone that fell back to a
581
+ plain checkout has no `node_modules` or other build output at all, and a
582
+ successful clone copies an in-project virtualenv (`.venv`) that keeps
583
+ absolute paths into the plan checkout — its scripts' interpreter, any
584
+ editable install — so tests run with it would run the plan checkout's
585
+ code. Remove a cloned in-project virtualenv before the install step
586
+ recreates it (`uv sync`, or `python3 -m venv .venv` and `.venv/bin/python
587
+ -m pip install -e .` — the venv's own pip, not the one on `PATH`). Then
588
+ check that the code resolves in the worktree, with `cwd` outside it (`/`)
589
+ so the current directory is not on the import path: for Python,
590
+ `<worktree>/.venv/bin/python -c 'import <package>;
591
+ print(<package>.__file__)'` must print a path under the worktree. Record
592
+ `git -C <worktree> status --porcelain` after the install: files the
593
+ install wrote are not the implementer's (DONE compares against this). A
594
+ wave of one runs in the plan checkout, with no extra worktree.
538
595
 
539
596
  **Until it merges, a wave task lives in its worktree, not in yours.** The
540
597
  `task` tool has no `cwd`, so every subagent starts in your checkout, which
541
598
  does not have the task's commits yet. So every dispatch for the task —
542
599
  implementer, re-dispatch, escalation, reviewer, re-reviewer — carries its
543
- worktree's absolute path: the implementer template's `Work from:` line,
544
- and for a reviewer a `Checkout: <path>` line saying to read the changed
545
- files and their call sites there. Every command you run for the task
546
- (its tests, a proven-trivial fix and its commit) runs with the `bash`
547
- tool's `cwd` set to that path, and its branch `sdd/<plan>/task-<N>` stands
600
+ worktree's absolute path: the implementer template's `Work from:` line
601
+ and its wave line (in a wave of two or more, the implementer runs only
602
+ the covering tests before committing; you run the full suite after the
603
+ wave merges), and for a reviewer a `Checkout: <path>` line saying to
604
+ read the changed files and their call sites there. Every command you
605
+ run for the task (its tests, a proven-trivial fix and its commit) runs
606
+ with the `bash` tool's `cwd` set to that path, and its branch
607
+ `sdd/<plan>/task-<N>` stands
548
608
  in for HEAD in every review-package command for it. The skill's scripts
549
609
  (`task-brief`, `review-package`) still run from the plan checkout, never
550
610
  from a task worktree: they write into the workspace of the checkout they
@@ -561,7 +621,8 @@ Implementer subagents report one of four statuses. Handle each appropriately:
561
621
  **DONE:** For a wave task, first check it worked where it should: its
562
622
  worktree has commits past BASE (`git -C <worktree> rev-list --count
563
623
  BASE..HEAD` is 1 or more), its worktree is clean (`git -C <worktree> status
564
- --porcelain` empty; untracked leftovers go back to the implementer), and
624
+ --porcelain` lists nothing beyond what it listed after the install; other
625
+ untracked leftovers go back to the implementer), and
565
626
  your own checkout gained no changes. A task that wrote into your checkout
566
627
  goes back to its implementer with the paths. Then check the task's line in
567
628
  the review list.
@@ -569,7 +630,7 @@ the review list.
569
630
  - **`review per-task`:** generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task; for a wave task, its branch `sdd/<plan>/task-<N>` stands in for HEAD), then dispatch `sdd-reviewer` with the printed path.
570
631
  - **`review at final`:** run the covering test command from the brief yourself, once, in the task's checkout, with its output redirected to a file in the plan's workspace; read the tail. A brief that names no test (docs, configuration) gets the cheapest check that can fail instead (a build, a lint, a parse), or goes on the review list. That run is the only check this task gets before the final review, so never take the implementer's report in its place. A pass completes the task (step 5). A failure goes back to the implementer with the output file's path: rounds 1-2 resume it, round 3 is a fresh `sdd-escalation-implementer`, as in the fix loop, and each round ends when your rerun passes, with no re-review. A failure after round 3 is a plan the tests disagree with: stop and ask.
571
632
 
572
- **DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness, address them before review, and put a `review at final` task on the review list (`Task <N>: review per-task — <concern>`). If they're observations (e.g., "this file is getting large"), note them and proceed.
633
+ **DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review, and put a `review at final` task on the review list (`Task <N>: review per-task — <concern>`). A wave task that changed a file outside its brief's Files list broke its wave's independence: merge it after its wave's other tasks, and run their covering tests too on the merged tree. If the concerns are observations (e.g., "this file is getting large"), note them and proceed.
573
634
 
574
635
  **NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch. On omp, message the idle agent instead (`write agent://<id>`, the id from the ledger's `dispatched` line): it keeps its context and yields again. Only a write error means re-dispatch, with the context carried in the brief.
575
636
 
@@ -741,7 +802,9 @@ covering test files in the fix message — a one-line fix does not need the
741
802
  whole suite.
742
803
 
743
804
  **The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
744
- where FIX_BASE is the head the previous review saw, and dispatch
805
+ where FIX_BASE is the head the previous review saw, as a commit SHA (for a
806
+ wave task, its branch tip then: `git rev-parse sdd/<plan>/task-<N>`; never
807
+ the branch name, which moves with the fix), and dispatch
745
808
  `sdd-rereviewer` with [re-review-prompt.md](re-review-prompt.md): the
746
809
  findings list, the brief, the report file, and the printed diff path. It
747
810
  has no bash, edit, or file-write tool and a four-call working budget plus its
@@ -801,18 +864,37 @@ git merge --no-ff --no-commit "sdd/<plan>/task-<N>"
801
864
  git commit --no-edit
802
865
  ```
803
866
 
867
+ If git refuses to start the merge (`untracked working tree files would be
868
+ overwritten`, or local changes to a file the merge touches), no merge is
869
+ in progress, so `git merge --abort` has nothing to abort, and the fault is
870
+ in your checkout, not the task: move the named untracked file out of the
871
+ way (it is yours if setup or a script made it; otherwise ask), or commit or
872
+ stash a tracked change of yours, then merge again. That costs the task no
873
+ round.
874
+
804
875
  If the merge stops on a conflict, or the covering tests fail on the merged
805
876
  tree, run `git merge --abort` and send the task back to its implementer
806
877
  (`write agent://<id>`) with the plan branch's name and, for a failure, the
807
878
  output file's path: rebase onto the plan branch, fix what the merge
808
879
  exposed, re-run its covering tests, report again. Each such round counts
809
- toward the task's three rounds (rounds and breaker as in the fix loop);
810
- ledger it as `Task <N>: rebased (<conflict | failing test>)`. A `review
811
- per-task` task whose rebase changed code gets a scoped re-review over its
812
- rebased commits: `review-package PLAN_FILE <plan-branch>
813
- sdd/<plan>/task-<N>`. A failure that belongs to a task already merged, not
814
- to this one, goes to ONE fix dispatch on the plan checkout as a fix round of
815
- that earlier task; then merge this one.
880
+ toward the task's three rounds, with the fix loop's seats: round 3 is a
881
+ fresh `sdd-escalation-implementer` whose dispatch names the plan branch,
882
+ the worktree, and the conflict or the failing output file, framed as
883
+ "rebase this task's branch onto the plan branch and make its covering
884
+ tests pass on the result". A task whose three rounds were already spent in
885
+ its review loop still gets one merge round, on that seat. Ledger each round
886
+ as `Task <N>: rebased (<conflict | failing test>)`. A task that still
887
+ conflicts or fails after its last round is never parked and never merged:
888
+ ledger `Task <N>: merge stuck (<conflict | failing test>)`, merge the wave's
889
+ other tasks, start no new wave, and stop and ask. A `review per-task` task
890
+ whose rebase changed code gets its task review again, not a scoped
891
+ re-review (there are no open findings to check, and the rebase may have
892
+ changed anything): `review-package PLAN_FILE "$(git merge-base
893
+ <plan-branch> sdd/<plan>/task-<N>)" sdd/<plan>/task-<N>` — a SHA, since the
894
+ plan branch moves when a sibling merges — then `sdd-reviewer`, at `effort:
895
+ "hi"` when `task.enableEffort` is on. A failure that belongs to a task
896
+ already merged, not to this one: abort this merge, get a fix on the plan
897
+ checkout (below), then merge this one.
816
898
 
817
899
  Right after the merge commit, ledger `Task <N>: merged (<sha7>)`, then
818
900
  remove the task's worktree and branch: `git worktree remove <path>`, then
@@ -821,11 +903,24 @@ remove the task's worktree and branch: `git worktree remove <path>`, then
821
903
  missing from the merge; otherwise ledger it and leave it for Finish.
822
904
 
823
905
  After the last task of a wave of two or more merges, run the full suite once
824
- in the plan checkout, output to a workspace file. Implementers ran it in
825
- worktrees without their siblings, so this is the first run on the combined
826
- tree. A failure no single task owns goes to ONE fix dispatch on the plan
827
- checkout, ledgered `Wave <K>: fix (<failing tests>)`, before the next wave
828
- starts.
906
+ in the plan checkout, output to a workspace file, and ledger `Wave <K>:
907
+ suite pass` or `Wave <K>: suite fail (<failing tests>)`. Implementers ran
908
+ only their covering tests, in worktrees without their siblings, so this is
909
+ the first full run on the combined tree. Any failure here gets a fix on the
910
+ plan checkout before the next wave or the final review — the last wave's
911
+ suite runs too.
912
+
913
+ **A fix on the plan checkout:** write a brief,
914
+ `<workspace>/wave-<K>-fix-brief.md`: the failing tests, the output file, the
915
+ test command to make pass, and the wave's merge commits; when one merged
916
+ task owns the failure, that task's brief and report paths. Dispatch a fresh
917
+ `sdd-implementer` with the implementer template, task `Wave <K> fix`,
918
+ `Work from:` the plan checkout, that brief, and
919
+ `<workspace>/wave-<K>-fix-report.md` as its report file, and ledger `Wave
920
+ <K>: fix dispatched (implementer <id>)`. Merge nothing else while it works.
921
+ When it reports, run the full suite yourself and ledger `Wave <K>: fix
922
+ (<failing tests>; commits <a7>..<b7>)`, then `Wave <K>: suite pass`, or
923
+ `Wave <K>: suite fail (after fix: <failing tests>)` and stop and ask.
829
924
 
830
925
  Then append the completion line to the ledger in the same message as your
831
926
  other bookkeeping:
@@ -927,7 +1022,7 @@ Use superpowers:finishing-a-development-branch.
927
1022
  ```
928
1023
  You: I'm using Subagent-Driven Development to execute this plan.
929
1024
 
930
- [Setup: worktree verified; on omp, session moved into it with /move]
1025
+ [Setup: the approval named a new branch feat/hooks in this checkout — git switch -c feat/hooks, project setup and baseline tests in place, no worktree, no /move]
931
1026
  [Read plan file once: docs/plans/feature-plan.md]
932
1027
  [Resolve workspace: bash scripts/sdd-workspace docs/plans/feature-plan.md — no ledger inside, fresh start]
933
1028
  [On omp: scripts dir resolved with realpath skill://subagent-driven-development/scripts and added to the ledger as "SDD scripts: <dir>"; each script runs as bash <dir>/<name>]
@@ -936,7 +1031,7 @@ You: I'm using Subagent-Driven Development to execute this plan.
936
1031
 
937
1032
  Wave 1: Task 1 (hook installation script) and Task 3 (help text)
938
1033
 
939
- [Two worktrees: omp worktree add -b sdd/feature-plan/task-1 …, and task-3]
1034
+ [Two worktrees: omp worktree add -b sdd/feature-plan/task-1 …, and task-3; npm ci in each, and a check that the code resolves in the worktree]
940
1035
  [Run task-brief for Tasks 1 and 3; ONE task call with two implementer items, each naming its worktree]
941
1036
  [Ledger: Task 1: dispatched (BASE a1b2c3d, implementer Impl1, worktree /home/me/.omp/wt/app-feature-plan-task-1)]
942
1037
 
@@ -954,7 +1049,7 @@ Implementer: [Later]
954
1049
  [git merge --no-ff --no-commit sdd/feature-plan/task-1; covering test on the merged tree passes; git commit --no-edit]
955
1050
  [Ledger: Task 1: merged (9a8b7c6); worktree and branch removed]
956
1051
  [Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review at final — tests: npm test test/install.test.js, pass)]
957
- [Task 3 likewise; its merge was the wave's last, so the full suite runs once in the plan checkout: pass]
1052
+ [Task 3 likewise; its merge was the wave's last, so the full suite runs once in the plan checkout — Ledger: Wave 1: suite pass]
958
1053
 
959
1054
  Wave 2: Task 2 (recovery modes, review per-task) and Task 4
960
1055
 
@@ -48,19 +48,26 @@ Use this template when dispatching an implementer subagent.
48
48
  6. Report back
49
49
 
50
50
  Work from: [directory — for a wave task, its worktree's absolute path]
51
+ [WAVE_LINE — only for a task in a wave of two or more: "Other tasks
52
+ run in parallel with this one: before committing, run only the
53
+ covering tests your brief names, not the full suite; the controller
54
+ runs the full suite once the wave merges."]
51
55
 
52
56
  Work only under that directory. Your session may have started in a
53
57
  different checkout, so give every file tool (`read`, `write`, `edit`,
54
58
  `grep`, `glob`, `lsp`) absolute paths under it, set the `bash` tool's
55
59
  `cwd` to it for every command, and commit on the branch checked out
56
- there. The brief and the report file are the exception: use the paths
57
- given for them.
60
+ there, staging your own files by path, never with `git add -A`,
61
+ `git add .` or `git commit -a`: the checkout may hold changes that
62
+ aren't yours. The brief and the report file are the exception: use the
63
+ paths given for them.
58
64
 
59
65
  **While you work:** If you encounter something unexpected or unclear, **ask questions**.
60
66
  It's always OK to pause and clarify. Don't guess or make assumptions.
61
67
 
62
68
  While iterating, run the focused test for what you're changing; run the
63
- full suite once before committing, not after every edit.
69
+ full suite once before committing (unless a wave line above says
70
+ otherwise), not after every edit.
64
71
 
65
72
  ## You Do Not Dispatch Subagents
66
73
 
@@ -171,7 +178,8 @@ Use this template when dispatching an implementer subagent.
171
178
  If BLOCKED or NEEDS_CONTEXT, put the specifics in the final message
172
179
  itself — the controller acts on it directly.
173
180
 
174
- Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
181
+ Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness,
182
+ or had to change a file your brief's Files list does not name (say which).
175
183
  Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
176
184
  information that wasn't provided. Never silently produce work you're unsure about.
177
185
  } ] }
@@ -113,8 +113,10 @@ that the fix itself broke nothing.
113
113
  - `[FINDINGS]` — the Critical/Important findings and spec gaps from the
114
114
  previous review, copied verbatim, one per bullet
115
115
  - `[REPORT_FILE]` — the implementer's report file (fix reports appended)
116
- - `[FIX_BASE_SHA]` — the head the previous review saw
117
- - `[HEAD_SHA]` — current commit
116
+ - `[FIX_BASE_SHA]` — the head the previous review saw: the `[HEAD_SHA]` you
117
+ gave it, as a SHA, never a branch name (a branch moves with the fix)
118
+ - `[HEAD_SHA]` — current commit; for a wave task that has not merged yet,
119
+ its branch tip (`git rev-parse sdd/<plan>/task-<N>`)
118
120
  - `[DIFF_FILE]` — the path `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
119
121
  - `[CHECKOUT_LINE]` — same as the task reviewer's: the worktree line for a wave
120
122
  task that has not merged yet, omitted otherwise
@@ -203,7 +203,9 @@ more, nothing less) and is well-built (clean, tested, maintainable)
203
203
  - `[REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed
204
204
  report to
205
205
  - `[BASE_SHA]` — commit before this task
206
- - `[HEAD_SHA]` — current commit
206
+ - `[HEAD_SHA]` — current commit; for a wave task that has not merged yet,
207
+ its branch tip (`git rev-parse sdd/<plan>/task-<N>`). Record this SHA:
208
+ it is the next re-review's FIX_BASE
207
209
  - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
208
210
  package to (`bash scripts/review-package PLAN_FILE BASE HEAD` prints the unique
209
211
  path it wrote; the package never enters the controller's context)
@@ -52,7 +52,7 @@ The rule is prompt text, not a tool block. It applies to every subagent at task
52
52
  - a vibe `good` worker told "fix sum.js so sum(2, 3) returns 5, then commit" ran no test;
53
53
  - the same brief plus "This assignment explicitly instructs you to run the tests yourself (`npm test`), before and after the fix" ran both.
54
54
 
55
- So every dispatch that needs a check names the command and when to run it. SDD's implementer template already instructs its test runs: the focused test while iterating, the full suite once before committing.
55
+ So every dispatch that needs a check names the command and when to run it. SDD's implementer template already instructs its test runs: the focused test while iterating, then before committing the full suite, or, for a task in a parallel wave, only its covering tests (the controller runs the full suite once the wave merges).
56
56
 
57
57
  ## Task lists
58
58
 
@@ -202,7 +202,7 @@ After saving and self-reviewing the plan, choose the execution method
202
202
  yourself, unless your human partner already named one:
203
203
 
204
204
  - **Subagent-driven** (superpowers:subagent-driven-development) - A fresh subagent implements each task, independent tasks run in parallel in their own worktrees, the tasks marked `**Review:** per-task` get a fresh reviewer each, and one whole-branch review at the end covers every task. Fastest for several tasks whose interfaces the plan settles; costs a fresh context per task.
205
- - **Native** (superpowers:executing-plans) - I implement every task myself in this session, the way this harness runs work, then one fresh reviewer on the most capable model checks the whole branch. Cheapest, and fastest for a few tightly coupled tasks; no independent review until the end. Runs well with a mid-tier session model, since the plan carries the design.
205
+ - **Native** (superpowers:executing-plans) - I implement every task myself in this session, the way this harness runs work, then one fresh reviewer on the most capable model checks the whole branch. Cheapest, and fastest for a few small tasks; no independent review until the end. Runs well with a mid-tier session model, since the plan carries the design.
206
206
 
207
207
  A plan with any `**Review:** per-task` mark runs Subagent-driven unless your
208
208
  human partner says otherwise: Native has no task reviews. If you still
@@ -214,10 +214,13 @@ yet: the design document when this plan came straight from brainstorming,
214
214
  the plan, the method, and where the work runs. Do not ask them to pick the
215
215
  method; name the one you chose and why, and they can swap it in the same
216
216
  reply. Name the workspace too: a new branch in this checkout unless they
217
- already said otherwise, so the run needs no `/move` from them, and this
218
- approval is the consent superpowers:using-git-worktrees would otherwise
219
- ask for. They can answer `/wt <branch>` instead to move the session into
220
- its own worktree:
217
+ already said otherwise. Approving it answers superpowers:using-git-worktrees'
218
+ consent question with "no new worktree", so the run needs no `/move` from
219
+ them; the execution skill creates the branch at its Setup. If `git status
220
+ --porcelain` lists a change to a tracked file or anything staged, say so in
221
+ the same message: a run in place needs those committed or stashed first.
222
+ They can answer `/wt <branch>` instead to move the session into its own
223
+ worktree:
221
224
 
222
225
  **"Design: `docs/specs/<filename>.md`. Plan: `docs/plans/<filename>.md`, <N> tasks. I'll run it <method> on a new branch `<branch>` in this checkout, because <one sentence from the plan: how much the tasks depend on each other's interfaces, how many there are, what a shipped mistake would cost>. Calls I made for you: <the decisions marked as your call, one line each>. Approve both, or tell me what to change, the method included; reply `/wt <branch>` if you want it in its own worktree."**
223
226