@loneexile/omp-superpowers 7.0.0-omp.3 → 7.0.1-omp.1

package/CHANGELOG.md

@@ -6,6 +6,29 @@ A version is `<upstream version>-omp.<n>`: the upstream release this fork is syn
 
 ## [Unreleased]
 
+## [7.0.1-omp.1] - 2026-10-24
+
+Synced to upstream [v7.0.1](https://github.com/obra/superpowers/blob/v7.0.1/RELEASE-NOTES.md).
+
+### Changed
+
+- **Brainstorming takes most of v7.0.1's retune.** It reads the project and whatever you pointed at before its first message, plays a detailed request back with what it found and asks about the one thing still open, offers to skip the questions only when you didn't ask for brainstorming, and builds each question on your last answer. The ways to build it come with the last playback chunk, with a recommendation, and that message's one question is the pick; upstream sends them in a message of their own, one more wait for your reply. Upstream's short design doc and plan for every small change are not taken: the small-change path stays. Checked live once per scenario on omp 18.12.6, in a scratch Python todo app, with no run of the old text to compare against. A calendar-sync request that didn't name brainstorming got a first message built on what `todo.py` stores, one question, and the skip offer last; two answers later, one message carried the rest of the design, two ways to build it with a third ruled out, a recommendation, the size and one pick question. A request starting "Let's brainstorm" got no skip offer, and its small change ended on "Should I build it this way?" with no design doc.
+- **Synced with upstream v7.0.1** (from v7.0.0). What reaches omp unchanged: `writing-skills` moves its supporting docs into `references/` (SKILL.md 26,623 → 16,738 bytes); `executing-plans` drops its Example Workflow, whose fork copy still sent the final review to `code-reviewer.md` (25,983 → 23,591 bytes); `diagnosing-superpowers` drafts issues with "Who's filing" and "Human-authored summary" sections, says how "without Superpowers" was checked, files nothing while the summary is a placeholder, and its link for filing without `gh` opens the Bug Report template instead of the deleted Session Diagnosis Report one. The repo gets upstream's new issue and PR templates, its `AGENTS.md` contributor rules, and `tests/skill-size/test-skill-size.sh`, which CI does not run yet: SDD's SKILL.md (69,657 bytes) and executing-plans' (23,591) are over its 20,000-byte limit. Upstream's old `docs/superpowers/plans/` files are gone. `tests/brainstorm-server/server.test.js` stays at v7.0.0's version: v7.0.1's rewrite, which waits on file events instead of fixed sleeps, failed one or both of its "does NOT send reload" checks (`0 !== 1`) in 4 runs out of 4 on a Linux host, because it counts reloads before its own marker file's reload has reached the client; v7.0.0's passed 3 out of 3.
+- Upstream's `skills/subagent-driven-development/references/` is deleted. It holds upstream's own fix loop (5 rounds, a fresh implementer on a more capable model for rounds 4–5), final review and resume text, and nothing in this fork's SKILL.md points to it. The fork's SDD stays one SKILL.md for now.
+
+## [7.0.0-omp.4] - 2026-10-16
+
+### Fixed
+
+Found by an independent review of 7.0.0-omp.3; a second review checked these fixes. Checked live on omp 18.11.1 with a three-task Python plan (an editable install in `.venv`). On the default workspace the controller ran `git status`, created the approved branch in place with no `/move`, ran tasks 1 and 2 in parallel worktrees, removed and recreated each cloned `.venv` and checked the import from `/` before dispatching, then merged both. Resumed from a ledger left mid-wave (task 1 merged but not ledgered, task 2 with no commits), it ledgered task 1 merged after the commit-count and ancestor checks, and re-dispatched task 2. The released 7.0.0-omp.3 text happened not to lose work in the same resume: its controller checked task 2's history before acting on the ancestor test.
+
+- **Resuming mid-wave no longer marks unstarted tasks as merged.** subagent-driven-development's resume rule ledgered a wave task `merged` when its branch tip was an ancestor of the plan branch, and a branch with no commits yet passes that test (`git merge-base --is-ancestor` exits 0). After a compaction or restart mid-wave, every unstarted sibling would have been ledgered merged and complete, its branch deleted, and its later work never merged. A wave task now counts as merged only when its branch also has commits past its BASE, and that check runs for every unfinished wave task, whatever its last ledger line. Resume then goes by each task's last line and covers `rebased` and `fix round` lines (read the agent first), review-list lines, `merge stuck`, a merge interrupted before its commit (`MERGE_HEAD`), and a wave whose suite has not passed. executing-plans finishes an open wave task under subagent-driven-development's rules instead of redoing it in place.
+- **The default workspace gets created.** writing-plans' approval names a new branch in this checkout, but both executors' Setup still sent the controller to make a worktree and wait for `/move`, or let it work on `main`, where the final review package comes out empty. Setup now creates the approved branch in place, runs project setup and baseline tests there, and ledgers the branch, so a resumed run only switches back to it. A change to a tracked file or anything staged goes back to the partner to commit or stash first, because a run in place commits from that index and tests that working tree; writing-plans' approval message says so up front, and implementers stage their own files by path. finishing-a-development-branch switches to the base branch before deleting a branch made in this checkout.
+- **Task worktrees test their own code.** A cloned in-project virtualenv keeps absolute paths into the plan checkout, through its scripts' interpreter and any editable install, so a wave task's tests ran the plan checkout's code (reproduced with a `uv` project: the cloned interpreter imported the package from the plan checkout, a recreated one from the worktree). Every task worktree, including one reused on resume, now runs the project's install step with a cloned virtualenv removed first (the venv's own pip, not the one on `PATH`); the controller checks from outside the worktree that the code resolves there, and records what the install wrote so it is not sent back to the implementer.
+- **Wave merges and their failures have a defined path.** A merge that git refuses to start (an untracked file in the way) is the controller's to clear and costs the task no round. In a wave of two or more, implementers run only their covering tests (the template and the `sdd-implementer` seat agree), and the controller runs the full suite once each wave merges, the last one included, and ledgers the result. Round 3 of a merge failure goes to the escalation seat, whose agent file now knows a merge round, with the plan branch and the worktree; a task whose rounds were spent in review still gets that one merge round; a task that still will not merge stops the run instead of being parked, and so does a wave suite still red after its one fix, both now in the skill's list of stops. A `review per-task` task whose rebase changed code gets its full task review again, over a merge-base SHA. A fix on the plan checkout gets its own brief and report file, its seat and its follow-up suite run. The reviewer templates take a wave task's branch-tip SHA as its head and next FIX_BASE, never the branch name. An implementer that had to change a file outside its brief reports DONE_WITH_CONCERNS ("or scope" is back, in the review-list trigger too), and the task merges after its wave's others.
+- **Small changes keep their guard.** A fully specified request on the never-small list is no longer built straight away as a "quick task". The small-change path asks before starting when something is already staged, runs the suite before changing anything so an existing failure is reported instead of mistaken for its own, commits only its own hunks of a file that already had edits, and stops before committing when the change grows into a project.
+- writing-plans no longer calls Native "fastest for a few tightly coupled tasks", a plan executing-plans and subagent-driven-development both turn away. The README's file list and upstream-sync notes now include this fork's executing-plans, requesting-code-review and finishing-a-development-branch edits.
+
 ## [7.0.0-omp.3] - 2026-10-16
 
 ### Changed
@@ -103,7 +126,9 @@ First release, synced to upstream [v6.4.2](https://github.com/obra/superpowers/b
 - The fork's rewritten subagent-driven-development text invokes its helper scripts through `bash` as well, so a package extractor that drops exec bits cannot break them.
 - `sdd-final-reviewer` carries upstream's new review rules from `code-reviewer.md`, the template it replaces in SDD's final review: the spec is a vision document (behavior it is silent on is graded by what a reasonable person expects), and a "Declined to judge" section that the controller rules on and ledgers like a plan conflict.
 
-[Unreleased]: https://github.com/LoneExile/omp-superpowers/compare/v7.0.0-omp.3...HEAD
+[Unreleased]: https://github.com/LoneExile/omp-superpowers/compare/v7.0.1-omp.1...HEAD
+[7.0.1-omp.1]: https://github.com/LoneExile/omp-superpowers/releases/tag/v7.0.1-omp.1
+[7.0.0-omp.4]: https://github.com/LoneExile/omp-superpowers/releases/tag/v7.0.0-omp.4
 [7.0.0-omp.3]: https://github.com/LoneExile/omp-superpowers/releases/tag/v7.0.0-omp.3
 [7.0.0-omp.2]: https://github.com/LoneExile/omp-superpowers/releases/tag/v7.0.0-omp.2
 [7.0.0-omp.1]: https://github.com/LoneExile/omp-superpowers/releases/tag/v7.0.0-omp.1

package/README.md

@@ -161,14 +161,17 @@ Rules that are easy to get wrong:
 - `.pi/extensions/superpowers.ts` — the injected mapping names `task`, `todo`, the `sdd-*` roster, and the no-`model:`-field rule; it also re-arms on `session_switch`, skips subagent sessions, and ignores an `agent_end` that will auto-continue; it tells a dispatching session to name the checks each subagent must run, since omp 18.4.12 tells subagents to leave builds, tests and smoke runs to the main agent unless their assignment explicitly instructs them; its last paragraph points a vibe-mode director (tools include `vibe_spawn` but not `task`) at the *Vibe mode* section of `pi-tools.md`
 - `.omp-plugin/plugin.json` — new. Marks the repo root as an omp-native plugin so a marketplace or `--plugin-dir` install keeps each agent's `model:` line
 - `skills/using-superpowers/references/pi-tools.md` — same, as the reference doc; it also gains a *Checks* subsection (the 18.4.12 subagent hand-off rule, and why every dispatch names its checks) and a *Vibe mode* section: what a director keeps and lacks, how skill actions map onto `vibe_*` and workers, and the worktree and request-budget limits
-- `skills/brainstorming/` — a defined small-change path: after the in-chat approval the session builds it itself, test first, runs the covering tests and the suite once, and commits once, with no design document, plan or subagents (a new behavior such as a `--quiet` flag can be small; security, auth, concurrency, money, migrations, changes one revert cannot undo, new config files or stored formats, changes to existing behavior, new interfaces other code builds on and new dependencies never are); a playback rides along with the next question instead of waiting for its own answer; for software, the plan is written right after the builder check so the design and the plan get one approval
+- `skills/brainstorming/` — a defined small-change path: after the in-chat approval the session builds it itself on a branch: the full suite before changing anything, test first, the covering tests and the suite again, then one commit of only its own files and hunks, with no design document, plan or subagents (a new behavior such as a `--quiet` flag can be small; security, auth, concurrency, money, migrations, changes one revert cannot undo, new config files or stored formats, changes to existing behavior, new interfaces other code builds on and new dependencies never are, and none of them takes the quick-task route however complete the request); a playback rides along with the next question instead of waiting for its own answer; for software, the plan is written right after the builder check so the design and the plan get one approval. Of upstream v7.0.1's retune it keeps reading the project first, the new first message and the sharper questions; the approaches ride with the last playback chunk, whose one question is the pick, instead of going out in a message of their own; upstream's short design doc and plan for every small change are not taken
 - `agents/sdd-*.md` — new. Each seat's `model:` is a pin plus a role fallback (`@task` or `@slow`), and all set `readSummarize: false`. `sdd-final-reviewer` reviews the whole branch for both ways of running a plan; after subagent-driven-development it does the task review's work on every task left to it (`review at final`) before the seams. It reads `requesting-code-review/code-reviewer.md` at run time and applies its What to Check, Calibration, severity definitions and Critical Rules, while carrying upstream's vision-document and Declined-to-judge rules in its own body; a crash or lost data on user input is always a finding, never a Declined-to-judge line. Descriptions name roles, never models
-- `skills/subagent-driven-development/` — *Model Selection* → *Agent Selection*; fix-loop cap 5 → 3 with a round-3 escalation seat; a proven-trivial-fix route that replaces a re-review with a one-command proof; the pre-flight scan builds a review list (plan-marked or ruled high-risk tasks get a task review, the rest get the controller's own covering-test run and the final review) and waves (tasks with no shared file or interface run in parallel, up to three, each in its own `omp worktree add` worktree, merged back with `--no-ff`); the scripts directory resolves via `realpath skill://subagent-driven-development/scripts`; fix rounds resume the implementer with `write agent://<id>` (id ledgered) and full results are read at `agent://<id>`; task review scales with risk through `effort: "hi"`; the controller checks reviewer results; templates show omp's real `{ context, tasks: [{ agent, task, solutionSpace }] }` wire shape and the reviewers' structured fields; one omp paragraph for vibe mode, where a director (no `task` or `bash`) hands the whole run to one `good` worker that dispatches the seats itself
-- `skills/executing-plans/` — one additive omp paragraph in *Final Review*: the `task` tool has no `model:` field, so the final review goes to `sdd-final-reviewer` (its model is what the host maps that agent to), told that no task was reviewed; it also resolves the scripts directory with `realpath` and reads full results at `agent://<id>`; one more omp paragraph for vibe mode, where a director hands the whole run to one `good` worker
+- `skills/subagent-driven-development/` — *Model Selection* → *Agent Selection*; fix-loop cap 5 → 3 with a round-3 escalation seat; a proven-trivial-fix route that replaces a re-review with a one-command proof; the pre-flight scan builds a review list (plan-marked or ruled high-risk tasks get a task review, the rest get the controller's own covering-test run and the final review) and waves (tasks with no shared file or interface run in parallel, up to three, each in its own `omp worktree add` worktree with the project's install step re-run there, merged back with `--no-ff` after their covering tests pass on the merged tree; a task that still will not merge after round 3 stops the run); Setup creates the approved branch in this checkout instead of a worktree; resume reads each task's last ledger line, and treats a wave task as merged only when its branch has commits past BASE; the scripts directory resolves via `realpath skill://subagent-driven-development/scripts`; fix rounds resume the implementer with `write agent://<id>` (id ledgered) and full results are read at `agent://<id>`; task review scales with risk through `effort: "hi"`; the controller checks reviewer results; templates show omp's real `{ context, tasks: [{ agent, task, solutionSpace }] }` wire shape and the reviewers' structured fields; one omp paragraph for vibe mode, where a director (no `task` or `bash`) hands the whole run to one `good` worker that dispatches the seats itself. Upstream v7.0.1's `references/` is deleted: it holds upstream's own fix loop (5 rounds), final review and resume text, and nothing in this SKILL.md points to it
+- `skills/executing-plans/` — the description, *Why inline*, *When to Use* and the "Prefer subagent-driven-development" paragraph say the partner approved inline execution at the handoff and that SDD reviews per task only where a plan marks it; Setup creates the approved branch in this checkout; a ledger with `Wave` lines resumes under SDD. Additive omp paragraphs: in *Final Review*, the `task` tool has no `model:` field, so the final review goes to `sdd-final-reviewer` (its model is what the host maps that agent to), told that no task was reviewed; it also resolves the scripts directory with `realpath` and reads full results at `agent://<id>`; one more for vibe mode, where a director hands the whole run to one `good` worker
+- `skills/requesting-code-review/` — *Mandatory* says a review follows each task on subagent-driven-development's review list, and once on the whole branch at the end, instead of after every task
 - `skills/using-git-worktrees/` — additive omp section: `/wt` is the user's one-line answer to the consent question (moves the session, carries WIP); when the agent creates the worktree itself it uses `omp worktree add` under `~/.omp/wt/` (the only place `omp worktree list`/`clear` manage), knows that command leaves uncommitted changes behind, and asks for `/move <path>` because `cd` never moves the tools' cwd. Also: clone-first falls back to a plain checkout without `node_modules` (no copy-on-write, or in-repo targets); setup and tests use the bash tool's `cwd` parameter until `/move`; `omp worktree clear --all` is warned against, since it force-removes every worktree, uncommitted work included; omp's bash rewrites a literal `git worktree add` into `omp worktree add` only without shell expansion; vibe mode refuses `/move` and `/wt`, so the worktree and `/move` come before `/vibe`, or every worker brief carries the absolute path
-- `skills/writing-plans/` — *Execution Handoff* picks the method itself and asks for one approval of the design, the plan and the method; *Review Marks* (and a self-review check) mark security, auth, concurrency, migration, money and destructive tasks `**Review:** per-task`; tasks that share no file or interface can run in parallel; in vibe mode both execution approaches run in one `good` worker the director briefs, not in its own session
+- `skills/writing-plans/` — *Execution Handoff* picks the method itself and asks for one approval of the design, the plan, the method and the workspace (a new branch in this checkout by default, which answers using-git-worktrees' consent question); *Review Marks* (and a self-review check) mark security, auth, concurrency, migration, money and destructive tasks `**Review:** per-task`; tasks that share no file or interface can run in parallel; in vibe mode both execution approaches run in one `good` worker the director briefs, not in its own session
+- `skills/finishing-a-development-branch/` — one line in the discard path: in a normal repo (a branch made in this checkout), switch to the base branch before `git branch -D`, which git refuses on the checked-out branch
 - `README.md` — this file: rewritten for omp (install, seats, overrides, maintenance); upstream's multi-harness README is gone
 - `tests/pi/test-pi-extension.mjs` — covers the extension's lifecycle (bootstrap on start, `session_switch`, compaction; none for subagents or an auto-continuing `agent_end`), the action table in `pi-tools.md`, the seat table against the names in `agents/*.md`, and the `.omp-plugin/plugin.json` manifest; the package-name assertion is gone (`scripts/check-npm-package.sh` checks the published name)
+- `tests/brainstorm-server/server.test.js` — kept at upstream v7.0.0's version. v7.0.1's rewrite counts the reloads a client received right after the server logs its marker file, before that file's own reload has reached the client, so its two "does NOT send reload" checks failed on Linux in 4 runs out of 4
 - `package.json` — the npm identity: `@loneexile/omp-superpowers`, `<upstream version>-omp.<n>` versions, a `files` allowlist (the extension, `skills/`, `agents/`), `publishConfig`, `omp`/`oh-my-pi` keywords; `main` is dropped, since it pointed at the OpenCode plugin this package does not ship
 - Spec and plan paths — `docs/specs/` and `docs/plans/` instead of upstream's `docs/superpowers/specs/` and `docs/superpowers/plans/`: brainstorming's *Where it goes*, writing-plans' save path and handoff lines, and the example plan paths in executing-plans, subagent-driven-development and requesting-code-review. `.superpowers/` (the SDD workspace, brainstorm companion files) is unchanged. `scripts/check-npm-package.sh` fails if a shipped file names `docs/superpowers/`
 - `CHANGELOG.md`, `.github/workflows/` (CI, npm release), `scripts/check-npm-package.sh` — new
@@ -185,9 +188,9 @@ git rebase upstream/main
 git push --force-with-lease origin main
 ```
 
-Expect conflicts in `skills/subagent-driven-development/`, `skills/brainstorming/`, `skills/writing-plans/`, `pi-tools.md`, `README.md`, and `package.json` whenever upstream touches them — this fork rewrites those files rather than appending to them (README.md is never a partial conflict). In `package.json` keep the fork's identity and set `version` to `<new upstream version>-omp.1`: CI's package check fails until the version's base matches the upstream version in `.claude-plugin/plugin.json`. `agents/`, the extension's mapping paragraph, and the omp blocks in `using-git-worktrees` are additive.
+Expect conflicts in `skills/subagent-driven-development/`, `skills/brainstorming/`, `skills/writing-plans/`, `skills/executing-plans/`, `skills/requesting-code-review/SKILL.md`, `skills/finishing-a-development-branch/SKILL.md`, `pi-tools.md`, `README.md`, and `package.json` whenever upstream touches them — this fork rewrites those files rather than appending to them (README.md is never a partial conflict). A sync that takes upstream's side of executing-plans or requesting-code-review brings back "review after every task" text that contradicts subagent-driven-development's review list: keep the fork's lines. In `package.json` keep the fork's identity and set `version` to `<new upstream version>-omp.1`: CI's package check fails until the version's base matches the upstream version in `.claude-plugin/plugin.json`. `agents/`, the extension's mapping paragraph, and the omp blocks in `using-git-worktrees` are additive.
 
-A clean rebase is not the whole sync. Upstream's edits to text this fork replaced never reach the replacement, so read upstream's diff for those files and port what still applies. The v6.4.x sync needed two: `bash scripts/...` invocations in the SDD text, and `code-reviewer.md`'s new review rules. Upstream edits to `code-reviewer.md`'s What to Check, Calibration, severity definitions and Critical Rules now reach `sdd-final-reviewer` without porting, because it reads the file at run time. Edits to the vision-document or Declined-to-judge sections still need porting into the agent body, which carries them itself.
+A clean rebase is not the whole sync. Upstream's edits to text this fork replaced never reach the replacement, so read upstream's diff for those files and port what still applies. The v6.4.x sync needed two: `bash scripts/...` invocations in the SDD text, and `code-reviewer.md`'s new review rules. The v7.0.1 sync took the fork's side of brainstorming and ported the retune by hand, all but its small-change gate, and deleted upstream's `skills/subagent-driven-development/references/`; when upstream edits a file there, the rebase stops on a modify/delete conflict: keep it deleted (`git rm`), then read upstream's diff of that file for rule changes to port into the fork's SDD text. Upstream edits to `code-reviewer.md`'s What to Check, Calibration, severity definitions and Critical Rules now reach `sdd-final-reviewer` without porting, because it reads the file at run time. Edits to the vision-document or Declined-to-judge sections still need porting into the agent body, which carries them itself.
 
 The fork changes upstream's `docs/superpowers/specs` and `docs/superpowers/plans` lines in brainstorming, writing-plans, executing-plans, subagent-driven-development and requesting-code-review. When upstream edits around one of them, `-X theirs` keeps the fork's whole conflicting hunk, so read upstream's diff of those lines and port the rest of the hunk. New upstream text naming `docs/superpowers/` fails `check-npm-package.sh` until it says `docs/specs/` or `docs/plans/`.
 

package/agents/sdd-escalation-implementer.md

@@ -13,12 +13,13 @@ thinkingLevel: max
 readSummarize: false
 ---
 
-You own one task from a Superpowers plan. Your dispatch names the brief (requirements, exact values verbatim), the report file, and which of two cases this is:
+You own one task from a Superpowers plan. Your dispatch names the brief (requirements, exact values verbatim), the report file, and which of three cases this is:
 
 - **Takeover:** a prior implementer attempted the task and either could not clear the review findings across two fix rounds, or reported `BLOCKED`. The dispatch lists the open findings, or the blocker that implementer reported. Read the report file first — it records what was tried and, for findings, what the reviewer rejected.
 - **First implementation:** the controller ruled the task needs the strongest seat from the start. No report file exists, no review has happened, and there are no findings: start from the brief and implement it test-first, as `sdd-implementer` would.
+- **Merge round:** the task's branch would not merge into the plan branch, or its covering tests failed on the merged tree, and its earlier rounds did not clear that. The dispatch names the plan branch, the task's worktree, and the conflict or the failing output file. Work in that worktree: rebase the task's branch onto the plan branch, make its covering tests pass on the result, and append what you did to the report file.
 
-If the dispatch does not say which case it is, the report file settles it: it exists for a takeover and not for a first implementation.
+If the dispatch does not say which case it is, the report file settles takeover against first implementation: it exists for a takeover and not for a first implementation. A dispatch that names a plan branch to rebase onto is a merge round.
 
 <contract>
 - Takeover: understand why the previous attempt did not converge before touching code. A loop that survives two resumes usually means the implementer could not see its own problem — look for the framing error, not just the diff; for a blocker, find what actually stopped it. Then fix the open findings, or clear the blocker and finish the task (test-first, as for a first implementation); re-run the covering tests (name them) and append your fix report to the same report file.

package/agents/sdd-implementer.md

@@ -24,5 +24,5 @@ You implement exactly one task from a Superpowers plan. Your dispatch names a br
 </contract>
 
 <budget>
-Read the changed files' context once; do not re-read files you already hold. While iterating, run the focused test for what you are changing; run the full suite once before you commit, not after every edit. A fix round re-runs only the tests that cover the amended code. Every extra turn is wall-clock the controller waits on.
+Read the changed files' context once; do not re-read files you already hold. While iterating, run the focused test for what you are changing; run the full suite once before you commit, not after every edit — unless your dispatch says the task runs in a wave with other tasks, in which case run only the covering tests your brief names. A fix round re-runs only the tests that cover the amended code. Every extra turn is wall-clock the controller waits on.
 </budget>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loneexile/omp-superpowers",
-  "version": "7.0.0-omp.3",
+  "version": "7.0.1-omp.1",
   "description": "obra/superpowers adapted for Oh My Pi (omp): a truthful task/todo tool mapping and five subagent-driven-development agents, each with its own model, thinking level, and tools.",
   "type": "module",
   "keywords": [

package/skills/brainstorming/SKILL.md

@@ -20,22 +20,57 @@ Before you reply, ask yourself: what do I know about what they want, and
 why?
 
 - **Everything that matters is in the request** ("make the icon cornflower
-  blue"). This is a quick, clear task. Do it, and say what you did.
+  blue"). This is a quick, clear task. Do it, and say what you did. Nothing
+  on the never-small list (Size the Work) is a quick task, however complete
+  the request.
 - **Something non-trivial is missing.** Start the conversation.
 
-## Your First Message
+## Look Before You Ask
+
+In an existing project, or when they've given you context (a spec, a plan,
+a handoff, files they pointed at, earlier conversation), dig in before your
+first message. Read what they referred to and the code or material it
+connects to, and keep reading until you can explain how the relevant
+parts work today and what this change would touch. Never ask what the
+project or their context already answers.
 
-Your first message is two things, in this order:
+## Your First Message
 
-1. One line letting them know that if they'd rather skip the questions and
-   have you just start, they can say so. If they take you up on it, this
-   skill is done: state any significant how-it-gets-made choice
-   (platform, language, medium) in one plain line, then do what they
-   asked the way its size calls for (Size the Work, below). Their opt-out
-   is the approval a small change needs.
-2. One open question that gets them describing. Ask about a real moment
-   or a concrete picture: "What's the moment you find yourself wishing
-   this existed?" or "Tell me about the people who'll be in the room."
+Move the work forward, with one of these:
+
+- **They've already said what they want** (a spec, a plan, a detailed
+  request): aim for about 200 words for the whole message. Echo their
+  request back in your own words, so they can see whether you've got its
+  shape: what they want, who it's for, and why, as far as they've said.
+  Add what you found that bears on it: how the relevant parts work today
+  and what the change would touch. If you found something they may not
+  have considered that would change what they're asking for or how it
+  has to be built, like a constraint, a conflict, or a cheaper path, say
+  so plainly. How to build it comes later, once you understand what they
+  want (see Lay out the approaches). End with one line inviting
+  corrections, then one question about what they want: the thing their
+  request leaves open whose answer would most change what gets built.
+  Specs are often incomplete, so confirm before you build on one.
+- **They haven't:** one open question, in their own terms, about the
+  biggest thing their request leaves unsettled. Say why you're asking:
+  what the answer would change about what you build. For "a website for
+  my bakery": "If it's mostly for people deciding whether to stop by,
+  I'd lead with hours and what's in the case today; taking orders is a
+  different site. What do you want someone to do when they land on it?"
+
+How the message ends depends on whether their message asked for
+brainstorming:
+
+- **They asked for it** (by name, by invoking it, or by asking for a
+  design discussion): end with your question. They want this
+  conversation.
+- **They didn't:** they may not want a conversation at all. After your
+  question, add a light, one-line offer to just get going instead, like
+  "Or if you'd rather I just dive in, say so." If they take you up on
+  it, this skill is done: state any significant how-it-gets-made choice
+  (platform, language, medium) in one plain line, then do what they
+  asked the way its size calls for (Size the Work, below). Their opt-out
+  is the approval a small change needs.
 
 That's the whole message.
 
@@ -44,7 +79,8 @@ That's the whole message.
 Each message ends with one question: a single sentence with no list of
 example answers hanging off it. Use plain language, pitched just a little
 above where your human partner is. Match their vocabulary; never use
-process jargon.
+process jargon. You never need to quote this skill to your human
+partner.
 
 Be clear and concise. Lead with what matters. Avoid jargon. When you
 report what you found, give them the most important findings and offer
@@ -76,19 +112,32 @@ out as questions:
 - current state: what exists now, what they've tried
 - the details they care about
 
-**Questions that work** anchor in specifics: "Walk me through the last
-time...", "If it could only do one of these well, which?", "What would
-make you wince if I got it wrong?" A guess they can correct ("I'm
-guessing this is because X keeps biting you?") often beats a question.
-
-**Offer recon.** Once you have a bit of grounding and looking would help,
-offer to go look: their codebase or project, their own files and data,
-or the web. Say what you'd look for. They decide whether you go.
-
-**Think wide privately.** Before you propose anything, come up with
-several ideas and drop the weak ones, including any that fight what
-they've told you about why. Show the comparison only when it helps them
-decide.
+**Make every question specific** to their project and what they've told
+you. Ask Socratically, the way a sharp colleague would: build each
+question on their last answer or on something you found, so it helps
+them think through a consequence or a case they may have missed
+("Voting closes before the meeting, and two members joined this month.
+Does someone who joins mid-round get a vote?"). When the reason isn't
+already plain, say what you're hoping to learn or what the answer would
+change. A proposal they can correct, plus your reason for it, often
+beats a question.
+
+**Offer recon.** Once you have a bit of grounding and looking further
+would help, offer to go look: deeper into their codebase or project,
+their own files and data, or the web. Say what you'd look for. They
+decide whether you go.
+
+**Lay out the approaches.** Once you understand what they want, and
+before you write anything up, lay out the ways of building it in the
+message that carries your last playback chunk (Play It Back). Come up
+with several real alternatives and drop the weak ones, including any
+that work against why they want it and any the existing work rules out.
+Present the two or three that remain, grounding each in what the project
+actually does and saying what it trades off. Recommend one and say why;
+that message's one question is which way they want to go. When there's
+genuinely one sensible way, say so and explain why the others don't
+fit. This is for how it gets built; for what they want, get them
+describing first.
 
 **Show, don't tell.** Offer the visual companion (below) whenever seeing
 would help more than reading:
@@ -118,11 +167,12 @@ behaves), describe that part back in about 200-300 words. A playback
 doesn't wait for its own answer: send it in the same message as your
 next question, with one line saying they can correct anything in it in
 their reply. The last chunk covers whatever is left and goes out with
-the size you pick; for a small change, it ends by asking whether to
-build it.
+the approaches (Lay out the approaches) and the size you pick. Its
+question is which way to build it; for a small change, it asks whether
+to build it that way.
 
-Mark anything you're guessing as your guess; only what they said goes in
-as theirs.
+Only what they said goes in as theirs. Anything you filled in goes in
+as your proposal, with your reason.
 
 Before you send a chunk, check it: does it describe something they'll
 look at, like a page, a screen, a schedule, or a printout? If so, and
@@ -155,9 +205,13 @@ public API), or a new dependency.
 yourself, in this session: no design document, no plan, no subagents.
 For software:
 
-1. Run `git status --short` first and note anything that isn't yours. On
-   the default branch or a detached HEAD, start a branch for the change
+1. Run `git status --short` first and note anything that isn't yours. If
+   anything is staged (`git diff --cached --quiet` exits non-zero), ask
+   before you start: a commit takes the whole index. On the default
+   branch or a detached HEAD, start a branch for the change
    (`git switch -c <topic>`), unless they told you to work where you are.
+   Run the full suite once before you change anything: a failure there
+   isn't yours. Report it with the rest; don't fix it unasked.
 2. Test first (superpowers:test-driven-development): a failing test,
    then the code that makes it pass. A change no test can cover
    (configuration, docs) gets the cheapest check that can fail instead:
@@ -165,6 +219,9 @@ For software:
    that exception.
 3. Run the tests that cover the change, then the full suite once.
 4. Commit once, staging your own files by path, never with `-a` or `-A`.
+   A file step 1 showed as changed also holds someone else's edits:
+   stage only your hunks (`git apply --cached` with a patch of just them;
+   `git add -p` needs a terminal), or ask.
 5. Before you call it done, follow
    superpowers:verification-before-completion: name the commit, the
    command you ran, what it printed, and any changes in the tree that
@@ -173,7 +230,9 @@ For software:
 Your human partner reviews that commit; it is the only review a small
 change gets. Outside software, make the change and show it to them.
 
-If it grows mid-task, stop, say so, and step up a size.
+If it grows mid-task, stop before committing, say so, and step up a size:
+say what the uncommitted work holds, and ask whether the design should
+keep it or start clean. A plan never starts on top of it uncommitted.
 
 If this is really several independent projects, say so, agree on an
 order, and brainstorm them one at a time.
@@ -186,6 +245,8 @@ could plan from without going back to your human partner. Cover:
 - intent and the why
 - goals, non-goals, anti-goals
 - constraints
+- approaches: the two or three you laid out, what each trades off, which
+  one they picked, and why
 - the parts of the how they decided, as they decided them
 - what's left to the builder
 
@@ -239,8 +300,9 @@ skill. Outside software, the plan follows the document's approval.
 
 | Thought | Reality |
 |---------|---------|
-| "I'll offer options to save them effort" | Options steer. Ask them to describe it first. |
+| "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. |
 | "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. |
+| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, with your last playback chunk. |
 | "I should explain the process first" | Ask your question. The process shows itself. |
 | "They said 'sounds good' to the idea" | Approval covers what you showed them. A description you haven't written isn't approved. |
 | "I'll get the design approved, then write the plan" | For software, write the plan first, so they approve both in one reading. A change to the design updates the plan before you ask again. |

package/skills/diagnosing-superpowers/SKILL.md

@@ -100,7 +100,7 @@ yourself in step 3 and which findings to lead with in the verdict.
   partner either.
 - **Approval gates.** No archive before your partner has seen the scrub
   log and file list. No issue or comment before they approve the exact
-  text.
+  text, and none with a placeholder summary.
 - **Intake before analysis.** Nothing in steps 2–7 starts until your
   partner has answered. If they are away, write the questions and stop.
   A statement you reconstructed for them is not an answer. An

package/skills/diagnosing-superpowers/references/github-issues.md

@@ -36,11 +36,11 @@ labels land only for collaborators; the template footer still marks the
 issue as skill-filed. `gh` cannot attach files: give your partner the
 bundle path to attach through the browser after the issue exists.
 
-Without `gh`, hand over a prefilled link on the `diagnosis_report.md`
-template, which applies both labels for any reporter:
+Without `gh`, hand over a prefilled link on the `bug_report.md` template,
+which applies the `bug` label for any reporter:
 
 ```
-https://github.com/obra/superpowers/issues/new?template=diagnosis_report.md&title=<url-encoded title>&body=<url-encoded body>
+https://github.com/obra/superpowers/issues/new?template=bug_report.md&title=<url-encoded title>&body=<url-encoded body>
 ```
 
 GitHub rejects URLs over about 8,000 characters; past that, send the link

package/skills/diagnosing-superpowers/templates/issue.md

@@ -2,6 +2,20 @@ Title: <skill or symptom>: <one-line observable> (<harness>)
 
 - [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
 
+## Who's filing this report? (required)
+
+<model and harness of this session>, filing on behalf of <how your
+partner wants to be named, or "my human partner">, who asked: "<their
+request from this session that led to the diagnosis or the issue,
+scrubbed>"
+
+## Human-authored summary (required, under 200 words)
+
+<Your partner's own words on what went wrong and what should have
+happened, pasted as written. Ask for them; a placeholder here means the
+issue is not ready to file. If they run long, ask them to trim rather
+than editing their words.>
+
 ## Environment (required)
 
 | Field | Value | Provenance / supporting evidence |
@@ -17,8 +31,12 @@ Title: <skill or symptom>: <one-line observable> (<harness>)
 
 - [ ] I confirmed this issue does not occur without Superpowers installed
 
-The reporter has not tried reproducing without superpowers. Evidence for
-involvement is below; it does not establish cause.
+How I verified that this issue does not reproduce without Superpowers:
+<"Not tried", or what your partner ran without superpowers and what
+happened, with the transcript path if there is one. Tick the box above
+only when a transcript shows the problem did not recur.>
+
+Evidence for involvement is below; it does not establish cause.
 
 ## What happened?
 
@@ -47,5 +65,6 @@ Superpowers involvement per the diagnosis report: <possible | likely>, with
 evidence at <transcript lines>. This report does not propose a fix.
 
 ---
-Filed with the `diagnosing-superpowers` skill. Model, harness, harness
-version, and installed plugins are listed above.
+Filed with the `diagnosing-superpowers` skill. The filing model and
+harness are under "Who's filing"; the diagnosed session's model, harness,
+versions, and plugins are in the Environment table.

package/skills/executing-plans/SKILL.md

@@ -124,10 +124,23 @@ digraph process {
 
 ## Setup
 
-Ensure the work happens in an isolated workspace: use
-superpowers:using-git-worktrees to create one or verify the existing one.
-Never start implementation on a main/master branch without your human
-partner's explicit consent.
+Ensure the work happens in an isolated workspace. If the plan's approval
+named a new branch in this checkout (writing-plans' default), that approval
+was your human partner's answer to superpowers:using-git-worktrees' consent
+question: work in place, with no worktree. With a ledger for this plan
+(below), `git switch` to the branch its `Setup:` line names and resume.
+On a first run, run `git status --porcelain`: a change to a tracked file,
+or anything staged, goes back to your human partner to commit or stash
+first, since your commits and tests would include it; untracked files may
+stay, and stay out of every commit. If a branch with the approved name
+already exists, ask, or name another. Then `git switch -c <branch>`, run
+using-git-worktrees' Step 2 (project setup) and Step 3 (baseline tests)
+here, and, once the ledger exists, ledger `Setup: branch <branch> in this
+checkout; untracked before start: <paths | none>`. Commit your own files
+by path, never with `-a` or `-A`. Otherwise use
+superpowers:using-git-worktrees to create a worktree or verify the
+existing one. Never start implementation on a main/master branch without
+your human partner's explicit consent.
 
 Conversation memory does not survive compaction. An inline executor that
 loses its place re-implements tasks whose commits already exist — the same
@@ -151,7 +164,11 @@ and the new one resumes from the same ledger.
   commits exist in git even when your context no longer remembers making
   them: after compaction, trust the ledger and `git log` over your own
   recollection. A ledger whose first line names a different plan file is
-  another plan's progress: leave it and start your own, fresh.
+  another plan's progress: leave it and start your own, fresh. A wave task
+  (its `dispatched` line names a worktree) with no `merged` or `complete`
+  line after it is still open in its worktree: finish it under
+  subagent-driven-development's resume rules and Complete the task before
+  continuing here. Finished waves need nothing.
 - Create the ledger with its identity as the first line:
   `# SDD ledger — plan: <plan file path>`.
 - `git clean -fdx` will destroy the workspace (it's git-ignored scratch);
@@ -382,55 +399,3 @@ Use superpowers:finishing-a-development-branch.
 | "The reviewer said Minor, so it's Minor" | The label graded the spec's silence. Grade what the person gets. Re-grade, then gate. |
 | "The fix is obvious, no need for a failing test first" | The failing test is the only proof the finding was real and is now gone. Without it you have a diff and a hope. |
 | "I'll fix the minors too while I'm in there" | Every minor you fix is a test, a fix, and a suite run your partner did not ask for. Ledger them; your partner decides. |
-
-## Example Workflow
-
-```
-You: I'm using the executing-plans skill to implement this plan inline.
-
-[Setup: worktree verified]
-[Read plan once: docs/plans/feature-plan.md; spec read]
-[Resolve workspace: sdd-workspace docs/plans/feature-plan.md — no ledger inside, fresh start]
-[Pre-flight scan: 2 shared-interface rows, 4 self-consistency rows, clean; written to ledger]
-[Create todos for all tasks]
-
-Task 1: Hook installation script
-
-[task-start plan 1 → brief read; BASE a1b2c3d]
-[Step 1: write failing test — written]
-[Step 2: run it — FAIL: install_hook not defined. Matches Expected.]
-[Step 3: implement — written]
-[Step 4: run it — PASS 1/1. Matches Expected.]
-[Step 5: commit — d4e5f6a]
-[Contract: tests ran, output read, no deviations]
-[task-done plan 1 a1b2c3d -- npm test -- hooks → ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, tests: npm test -- hooks → 1/1 pass)]
-
-Task 2: Recovery modes
-
-[task-start plan 2 → brief read; BASE d4e5f6a]
-[Step 2: run failing test — FAIL, but on an import error: Task 1 exported
- installHook, brief consumes install_hook]
-[Ruling: brief's consumer name is a typo against Task 1's Produces block;
- use installHook — Ledger: Task 2: Ruling: install_hook → installHook — matches Task 1 Produces — cost if wrong: one rename]
-[Steps 2-5 as planned; commit b7c8d9e]
-[task-done plan 2 d4e5f6a -- npm test -- recovery → ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, tests: npm test -- recovery → 8/8 pass)]
-
-...
-
-[After all tasks: review-package plan MERGE_BASE HEAD; dispatch code-reviewer, most capable model]
-Reviewer: One Important finding — progress reporting interval hardcoded. Two Minor.
-[Re-grade: Important stands; minors → ledger as deferred]
-[Fix pass: test_progress_interval_configurable RED → extract PROGRESS_INTERVAL → GREEN; suite 12/12; commit]
-[Ledger: Final: fixed hardcoded interval — test_progress_interval_configurable RED→GREEN, suite 12/12]
-
-Rulings I made:
-- Task 2: install_hook → installHook (brief typo; cost if wrong: one rename)
-
-Deferred minors:
-- README lacks a usage example
-- recovery.js could split verify/repair into two files
-
-[Delete this plan's workspace — the record now lives in git]
-
-Using superpowers:finishing-a-development-branch.
-```

package/skills/finishing-a-development-branch/SKILL.md

@@ -150,9 +150,13 @@ MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-tople
 cd "$MAIN_ROOT"
 ```
 
-Then clean up the worktree (Step 6) and force-delete the branch:
+Then clean up the worktree (Step 6) and force-delete the branch. In a
+normal repo (`GIT_DIR == GIT_COMMON`, for example a branch made in this
+checkout) the branch is still checked out here, and git refuses to delete
+it, so switch away first:
 
 ```bash
+git switch <base-branch>   # normal repo only
 git branch -D <feature-branch>
 ```