@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.
- package/CHANGELOG.md +26 -1
- package/README.md +9 -6
- package/agents/sdd-escalation-implementer.md +3 -2
- package/agents/sdd-implementer.md +1 -1
- package/package.json +1 -1
- package/skills/brainstorming/SKILL.md +96 -34
- package/skills/diagnosing-superpowers/SKILL.md +1 -1
- package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
- package/skills/diagnosing-superpowers/templates/issue.md +23 -4
- package/skills/executing-plans/SKILL.md +22 -57
- package/skills/finishing-a-development-branch/SKILL.md +5 -1
- package/skills/subagent-driven-development/SKILL.md +145 -50
- package/skills/subagent-driven-development/implementer-prompt.md +12 -4
- package/skills/subagent-driven-development/re-review-prompt.md +4 -2
- package/skills/subagent-driven-development/task-reviewer-prompt.md +3 -1
- package/skills/using-superpowers/references/pi-tools.md +1 -1
- package/skills/writing-plans/SKILL.md +8 -5
- package/skills/writing-skills/SKILL.md +21 -303
- package/skills/writing-skills/references/bulletproofing.md +80 -0
- package/skills/writing-skills/references/discovery.md +201 -0
- package/skills/writing-skills/references/flowcharts.md +37 -0
- package/skills/writing-skills/{testing-skills-with-subagents.md → references/testing-skills-with-subagents.md} +2 -2
- /package/skills/writing-skills/{examples → references}/CLAUDE_MD_TESTING.md +0 -0
- /package/skills/writing-skills/{anthropic-best-practices.md → references/anthropic-best-practices.md} +0 -0
- /package/skills/writing-skills/{graphviz-conventions.dot → references/graphviz-conventions.dot} +0 -0
- /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
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
**
|
|
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,
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
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
|
|
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
|
|
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/`.
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
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
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
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`
|
|
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>`).
|
|
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,
|
|
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
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
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
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
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:
|
|
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
|
|
57
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
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
|
|