superpowers-mcp 6.3.10 → 6.4.1

package/skills/executing-plans/scripts/task-start.ps1

@@ -0,0 +1,38 @@
+#!/usr/bin/env pwsh
+# Begin one task of an inline plan execution in a single call: extract the
+# task's brief (via subagent-driven-development's task-brief, so both skills
+# share one workspace) and record BASE, the commit the task's review range is
+# cut from. One tool call instead of two, because every call in an inline
+# session is a turn that re-reads the whole context.
+#
+# Usage: ./task-start.ps1 PLAN_FILE TASK_NUMBER
+# Prints:
+#   brief: <path to the task's brief file>
+#   base:  <full SHA of HEAD>
+
+$ErrorActionPreference = "Stop"
+
+if ($args.Count -ne 2) {
+    [Console]::Error.WriteLine("usage: task-start.ps1 PLAN_FILE TASK_NUMBER")
+    exit 2
+}
+
+$plan = $args[0]
+$n = $args[1]
+$sdd = Join-Path $PSScriptRoot "../../subagent-driven-development/scripts"
+
+$out = @(& (Join-Path $sdd "task-brief.ps1") $plan $n)
+if ($LASTEXITCODE -ne 0) {
+    exit $LASTEXITCODE
+}
+$brief = $null
+foreach ($line in $out) {
+    if ($line -match '^wrote (.*): [0-9][0-9]* lines$') { $brief = $Matches[1] }
+}
+if ([string]::IsNullOrEmpty($brief)) {
+    [Console]::Error.WriteLine("task-brief did not report a path: $($out -join [Environment]::NewLine)")
+    exit 1
+}
+
+Write-Output "brief: $brief"
+Write-Output "base: $((& git rev-parse HEAD).Trim())"

package/skills/requesting-code-review/code-reviewer.md

@@ -30,6 +30,23 @@ Subagent (general-purpose):
     git diff [BASE_SHA]..[HEAD_SHA]
     ```
 
+    ## The spec is a vision document
+
+    The spec says what the software must do. It does not enumerate every
+    input, environment, or condition the software will meet. For behavior
+    the spec is silent on, judge by what a reasonable person using this
+    software would expect: a reasonable person's expectation is a
+    requirement, and a spec's silence is not permission. Grade such
+    findings by their effect on that person, not by whether the spec
+    mentions the trigger.
+
+    ## Declined to judge
+
+    Before your verdict, list every behavior you considered and set aside
+    as outside the plan or spec, one line each, with the reason. The
+    executor rules on each line; nothing you set aside is dropped
+    silently. An empty list means you set nothing aside.
+
     ## Read-Only Review
 
     Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
@@ -140,7 +157,7 @@ Subagent (general-purpose):
 - `[BASE_SHA]` — starting commit
 - `[HEAD_SHA]` — ending commit
 
-**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+**Reviewer returns:** Strengths, Declined to judge, Issues (Critical / Important / Minor), Recommendations, Assessment
 
 ## Example Output
 

package/skills/subagent-driven-development/SKILL.md

@@ -36,25 +36,25 @@ stop and ask.
 digraph when_to_use {
     "Have implementation plan?" [shape=diamond];
     "Tasks mostly independent?" [shape=diamond];
-    "Stay in this session?" [shape=diamond];
+    "Partner chose inline, or no subagent tool?" [shape=diamond];
     "subagent-driven-development" [shape=box];
     "executing-plans" [shape=box];
     "Manual execution or brainstorm first" [shape=box];
 
     "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
     "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
-    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
+    "Tasks mostly independent?" -> "Partner chose inline, or no subagent tool?" [label="yes"];
     "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
-    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
-    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
+    "Partner chose inline, or no subagent tool?" -> "executing-plans" [label="yes"];
+    "Partner chose inline, or no subagent tool?" -> "subagent-driven-development" [label="no"];
 }
 ```
 
-**vs. Executing Plans (parallel session):**
-- Same session (no context switch)
-- Fresh subagent per task (no context pollution)
-- Review after each task (spec compliance + code quality), broad review at the end
-- Faster iteration (no human-in-loop between tasks)
+**vs. Executing Plans (inline):**
+- Fresh subagent per task (no context pollution) instead of one context doing every task
+- Review after each task (spec compliance + code quality) instead of only at the end
+- Costs a fresh context per task and per review; inline costs one context plus one final reviewer
+- Both run in this session, share the same plan workspace and ledger, and never pause between tasks
 
 ## The Process
 
@@ -136,8 +136,8 @@ sequences — the single most expensive failure observed. Track progress in
 a ledger file, not only in todos.
 
 - Each plan owns a workspace: at skill start, run this skill's
-  `scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
-  directory (`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to
+  `bash scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
+  directory (under `<repo-root>/.superpowers/sdd/`), home to
   every artifact for THIS plan: ledger, briefs, reports, review packages.
   Another plan's directory is never yours to read or write.
 - Check for this plan's ledger at `<workspace>/progress.md`. If its first
@@ -273,7 +273,7 @@ Record BASE (`git rev-parse HEAD`) before dispatching — the review package
 and fix-round diffs need it.
 
 - **Task brief:** before dispatching an implementer, run this skill's
-  `scripts/task-brief PLAN_FILE N` (or `scripts/task-brief.ps1 PLAN_FILE N` on
+  `bash scripts/task-brief PLAN_FILE N` (or `scripts/task-brief.ps1 PLAN_FILE N` on
   Windows PowerShell) — it extracts the task's full text to a
   uniquely named file and prints the path. Compose the dispatch so the
   brief stays the single source of
@@ -344,7 +344,7 @@ Template: [implementer-prompt.md](implementer-prompt.md)
 
 Implementer subagents report one of four statuses. Handle each appropriately:
 
-**DONE:** Generate the review package (`scripts/review-package PLAN_FILE BASE HEAD`, or `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell, 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), then dispatch the task reviewer with the printed path.
+**DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, or `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell, 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), then dispatch the task reviewer with the printed path.
 
 **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. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
 
@@ -371,7 +371,7 @@ required. Implementer self-review never replaces the task review; both are
 needed.
 
 - Hand the reviewer its diff as a file: run this skill's
-  `scripts/review-package PLAN_FILE BASE HEAD` (or
+  `bash scripts/review-package PLAN_FILE BASE HEAD` (or
   `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell) and
   pass the reviewer the file path
   it prints (or, without bash: `git log --oneline`, `git diff --stat`,
@@ -464,7 +464,7 @@ output; dispatch the re-review once all three are present. Name the
 covering test files in the fix message — a one-line fix does not need the
 whole suite.
 
-**The re-review is scoped.** Run `scripts/review-package PLAN_FILE FIX_BASE HEAD`
+**The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
 (or `scripts/review-package.ps1 PLAN_FILE FIX_BASE HEAD` on Windows PowerShell)
 where FIX_BASE is the head the previous review saw, and dispatch
 [re-review-prompt.md](re-review-prompt.md) with the findings list, the
@@ -552,7 +552,7 @@ parked-with-ruling at the cap.
 ## Final Review
 
 The final whole-branch review gets a package too: run
-`scripts/review-package PLAN_FILE MERGE_BASE HEAD` (or
+`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (or
 `scripts/review-package.ps1 PLAN_FILE MERGE_BASE HEAD` on Windows PowerShell;
 MERGE_BASE = the commit the branch started from, e.g. `git merge-base main HEAD`)
 and include the
@@ -562,14 +562,19 @@ on the most capable available model (see Model Selection), using
 superpowers:requesting-code-review's
 [code-reviewer.md](../requesting-code-review/code-reviewer.md). Point it at
 the ledger's deferred-minor and parked lines so it can triage which must be
-fixed before merge.
+fixed before merge. Rule on its "Declined to judge" list before the fix
+dispatch: every line there is a ruling you make and ledger —
+`Final: Ruling: <behavior the reviewer set aside> — <what a reasonable
+person using this software gets, and why that stands or why it is now a
+finding> — <cost if wrong>`. Nothing the reviewer set aside is dropped
+silently.
 
 If the final whole-branch review returns findings, dispatch ONE fix subagent
 with the complete findings list — not one fixer per finding.
 Per-finding fixers each rebuild context and re-run suites; a real
 session's final-review fix wave cost more than all its tasks combined.
 Then run exactly one scoped re-review of the fix wave
-(`scripts/review-package PLAN_FILE FIX_BASE HEAD`, or
+(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD`, or
 `scripts/review-package.ps1 PLAN_FILE FIX_BASE HEAD` on Windows PowerShell,
 over the fix range,
 [re-review-prompt.md](re-review-prompt.md)).
@@ -596,7 +601,7 @@ carry them, because git records what was done. So export them before
 anything is deleted: grep the progress ledger for its three finding tags
 
 ```bash
-grep -E 'Ruling:|^(Task [0-9]+: )?(minor \(deferred\)|parked)' <workspace>/progress.md
+grep -E 'Ruling:|^(Task [0-9]+: |Final: )?(minor \(deferred\)|parked)' <workspace>/progress.md
 ```
 
 and carry every matching line, verbatim, into a durable, human-reachable
@@ -650,12 +655,12 @@ You: I'm using Subagent-Driven Development to execute this plan.
 
 [Setup: worktree verified]
 [Read plan file once: docs/superpowers/plans/feature-plan.md]
-[Resolve workspace: scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
+[Resolve workspace: bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
 [Create todos for all tasks]
 
 Task 1: Hook installation script
 
-[Run task-brief for Task 1; dispatch implementer with brief + report paths + context]
+[bash scripts/task-brief PLAN_FILE 1; dispatch implementer with brief + report paths + context]
 
 Implementer: "Before I begin - should the hook be installed at user or system level?"
 
@@ -667,7 +672,7 @@ Implementer: [Later]
   - Self-review: Found I missed --force flag, added it
   - Committed
 
-[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path + review file]
+[bash scripts/review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path + review file]
 Task reviewer: Spec ✅. Quality: Approved. Minor: 0.
   Full report: task-1-review.md
 
@@ -676,14 +681,14 @@ Task reviewer: Spec ✅. Quality: Approved. Minor: 0.
 
 Task 2: Recovery modes
 
-[Run task-brief for Task 2; dispatch implementer with brief + report paths + context]
+[bash scripts/task-brief PLAN_FILE 2; dispatch implementer with brief + report paths + context]
 
 Implementer: [No questions]
   - Added verify/repair modes
   - 8/8 tests passing
   - Committed
 
-[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path + review file]
+[bash scripts/review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path + review file]
 Task reviewer: Spec ❌:
   - Missing: Progress reporting (spec says "report every 100 items")
   Important: Magic number (100). Minor: 0. Full report: task-2-review.md
@@ -692,7 +697,7 @@ Task reviewer: Spec ❌:
 Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
   Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
 
-[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review with the review file to append to]
+[bash scripts/review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review with the review file to append to]
 Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
   Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
   Verdict: all findings addressed.
@@ -704,7 +709,7 @@ Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
 ...
 
 [After all tasks]
-[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
+[bash scripts/review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
 Final reviewer: All requirements met. Deferred minors triaged: none block merge.
 
 [Use superpowers:finishing-a-development-branch — Option 2: push and create PR]

package/skills/subagent-driven-development/re-review-prompt.md

@@ -114,7 +114,7 @@ Subagent (general-purpose):
   review `…/task-N-review.md`); append this round's verdicts to it
 - `[FIX_BASE_SHA]` — the head the previous review saw
 - `[HEAD_SHA]` — current commit
-- `[DIFF_FILE]` — the path `scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
+- `[DIFF_FILE]` — the path `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
 
 **Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
 new breakage in the fix diff, out-of-scope observations, and a round verdict —

package/skills/subagent-driven-development/scripts/review-package

@@ -28,6 +28,8 @@ git rev-parse --git-dir >/dev/null 2>&1 || {
 git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
 git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
 
+# Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
+# not rooted at BASE; either would silently produce a bogus review package.
 git merge-base --is-ancestor "$base" "$head" || {
   echo "HEAD ($head) is not a descendant of BASE ($base)" >&2
   exit 3
@@ -41,6 +43,8 @@ fi
 if [ $# -eq 4 ]; then
   out=$4
 else
+  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
+  # strip Unix exec bits when unpacking marketplace packages (#2040).
   dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
 fi

package/skills/subagent-driven-development/scripts/review-package.ps1

@@ -38,6 +38,8 @@ if ($LASTEXITCODE -ne 0) {
     exit 2
 }
 
+# Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
+# not rooted at BASE; either would silently produce a bogus review package.
 & git merge-base --is-ancestor $base $head *> $null
 if ($LASTEXITCODE -ne 0) {
     [Console]::Error.WriteLine("HEAD ($head) is not a descendant of BASE ($base)")

package/skills/subagent-driven-development/scripts/sdd-workspace

@@ -3,16 +3,20 @@
 # short-lived artifacts: task briefs, implementer reports, review packages,
 # and the progress ledger. Print the plan directory's absolute path.
 #
-# One directory per plan (.superpowers/sdd/<plan-slug>/) so a follow-up
+# One directory per plan (.superpowers/sdd/<plan-basename>/) so a follow-up
 # plan in the same working tree can never read or overwrite another plan's
 # artifacts. A stale ledger misread as current progress makes controllers
 # skip whole task sequences — plan-scoping removes that failure structurally.
 #
-# Ownership markers (plan-path file in the workspace directory) disambiguate
-# same-basename plans (e.g. docs/alpha/plan.md vs docs/beta/plan.md) by appending
-# the parent-directory name, then a counter. A workspace with no marker
+# Basename slugs collide when two plans share a filename (docs/alpha/plan.md
+# vs docs/beta/plan.md), so each workspace records its owning plan's path in
+# a plan-path marker (repo-relative in-repo, absolute outside). A workspace
+# owned by a different plan is skipped and the slug disambiguated with the
+# plan's parent-directory name, then a counter. A workspace with no marker
 # predates the marker scheme and is adopted for the current plan so in-flight
-# workspaces keep resolving.
+# workspaces keep resolving — which means the first collision on such a
+# legacy workspace adopts instead of detecting; acceptable, marker-less
+# workspaces age out as plans finish.
 #
 # The workspace lives in the working tree (not under .git/) because Claude Code
 # treats .git/ as a protected path and denies agent writes there — which blocks

package/skills/subagent-driven-development/scripts/sdd-workspace.ps1

@@ -7,6 +7,16 @@
 # plan in the same working tree can never read or overwrite another plan's
 # artifacts.
 #
+# Basename slugs collide when two plans share a filename (docs/alpha/plan.md
+# vs docs/beta/plan.md), so each workspace records its owning plan's path in
+# a plan-path marker (repo-relative in-repo, absolute outside). A workspace
+# owned by a different plan is skipped and the slug disambiguated with the
+# plan's parent-directory name, then a counter. A workspace with no marker
+# predates the marker scheme and is adopted for the current plan so in-flight
+# workspaces keep resolving — which means the first collision on such a
+# legacy workspace adopts instead of detecting; acceptable, marker-less
+# workspaces age out as plans finish.
+#
 # A greenfield plan's first task is often "create the repo", so there is no
 # repo root to resolve yet: fall back to the current directory rather than
 # failing, since that task is exactly the one needing a brief.

package/skills/subagent-driven-development/scripts/task-brief

@@ -21,6 +21,8 @@ n=$2
 if [ $# -eq 3 ]; then
   out=$3
 else
+  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
+  # strip Unix exec bits when unpacking marketplace packages (#2040).
   dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/task-${n}-brief.md"
 fi

package/skills/subagent-driven-development/task-reviewer-prompt.md

@@ -203,7 +203,7 @@ Subagent (general-purpose):
 
 **Placeholders:**
 - `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection
-- `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N`, or `scripts/task-brief.ps1 PLAN N` on Windows PowerShell,
+- `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N`, or `scripts/task-brief.ps1 PLAN N` on Windows PowerShell,
   prints the path; same file the implementer worked from)
 - `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from
   the plan's Global Constraints section or the spec: exact values, formats,
@@ -214,7 +214,7 @@ Subagent (general-purpose):
 - `[BASE_SHA]` — commit before this task
 - `[HEAD_SHA]` — current commit
 - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
-  package to (`scripts/review-package PLAN_FILE BASE HEAD`, or `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell, prints the unique
+  package to (`bash scripts/review-package PLAN_FILE BASE HEAD`, or `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell, prints the unique
   path it wrote; the package never enters the controller's context)
 - `[REVIEW_FILE]` — REQUIRED: the file the reviewer writes its full report
   to; name it after the brief (brief `…/task-N-brief.md` → review

package/skills/systematic-debugging/root-cause-tracing.md

@@ -101,7 +101,7 @@ If something appears during tests but you don't know which test:
 Use the bisection script `find-polluter.sh` in this directory:
 
 ```bash
-./find-polluter.sh '.git' 'src/**/*.test.ts' npx vitest run
+bash ./find-polluter.sh '.git' 'src/**/*.test.ts' npx vitest run
 
 # Windows PowerShell:
 ./find-polluter.ps1 '.git' 'src/**/*.test.ts' npx vitest run

package/skills/using-superpowers/SKILL.md

@@ -62,10 +62,12 @@ These thoughts mean STOP—you're rationalizing:
 
 If your harness appears here, read its reference file for special instructions:
 
+- Claude Code: `references/claude-code-tools.md`
 - Codex: `references/codex-tools.md`
 - Pi: `references/pi-tools.md`
 - Antigravity: `references/antigravity-tools.md`
 - Hermes Agent: `references/hermes-tools.md`
+- Muse: `references/muse-tools.md`
 - Devin CLI: `references/devin-tools.md`
 - OpenCode: `references/opencode-tools.md`
 

package/skills/using-superpowers/references/claude-code-tools.md

@@ -0,0 +1,29 @@
+# Claude Code Tool Notes
+
+Claude Code is the reference harness: skills speak its vocabulary
+(`Agent` for a subagent dispatch, todos, `Skill`). These notes cover the
+one place Claude Code can run a plan cheaper than the skills' default
+shape. It is opt-in by your human partner and changes nothing the skills
+require.
+
+## Cheaper orchestration for subagent-driven development
+
+The controller session is the most expensive seat in a
+superpowers:subagent-driven-development run: it reads every dispatch
+result and every report, and it usually runs on the session's most
+capable model. Claude Code supports nested subagents (three layers below
+the main conversation by default; `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`
+adjusts it), so the whole loop can run one layer down.
+
+When your human partner asks for it — or has said the session model is
+too expensive to spend on coordination — dispatch ONE orchestrator
+subagent on a mid-tier model with the plan path and the instruction to
+use superpowers:subagent-driven-development end to end. The orchestrator
+dispatches its own implementers and reviewers per that skill's Model
+Selection; the workspace and ledger live on disk, so nothing is lost to
+the extra layer. Its final message must carry the "Rulings I made" list
+verbatim — that list is how the decisions reach your human partner, and
+you relay it, not summarize it.
+
+Do this only for a whole plan. Nesting a single task's dispatch buys
+nothing and adds a seat.

package/skills/using-superpowers/references/muse-tools.md

@@ -0,0 +1,35 @@
+# Muse Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Muse these resolve to the tools below.
+
+| Action skills request | Muse equivalent |
+|----------------------|----------------|
+| Read a file | `read_file` |
+| Read multiple files | `read_file` (call multiple times) or `search` |
+| Create a new file | `write_file` |
+| Edit a file | `edit_file` |
+| Run a shell command | `bash` |
+| Search file contents | `search` |
+| Find files by name | `search` with `glob` |
+| Fetch a URL | `web_fetch` |
+| Search the web | `web_search` |
+| Invoke a skill | `read_file` on `skills/<name>/SKILL.md` or native skill tool |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `subagent_spawn` with prompt filling |
+| Task tracking ("create a todo", "mark complete") | `write_todos` or `bash` task file |
+| Ask the user a question | `request_user_input` |
+
+## Instructions file
+
+When a skill mentions "your instructions file", on Muse this is **`CLAUDE.md`** or **`AGENTS.md`** in the project root. Muse loads these hierarchically where configured.
+
+## Skill invocation
+
+Muse has native skill support via `muse skills`. To invoke a Superpowers skill, read its `SKILL.md` and follow the instructions. The bootstrap (`using-superpowers`) is injected automatically at `SessionStart` via the plugin hook — you are already following it, do not re-load it.
+
+## Subagent dispatch
+
+Use `subagent_spawn` to delegate work to isolated subagents. Fill prompt templates (e.g., `implementer-prompt.md`, `task-reviewer-prompt.md`) before dispatching. If no subagent tool is available, do the work inline rather than inventing tool calls.
+
+## Task tracking
+
+Use `write_todos` for checklist tracking. Create one todo per skill checklist item, mark in_progress/completed as you go. If `write_todos` is unavailable, maintain a markdown task file via `write_file`/`edit_file`.

package/skills/writing-plans/SKILL.md

@@ -100,6 +100,18 @@ naming and copy rules, platform requirements — one line each, with exact
 values copied verbatim from the spec. Every task's requirements implicitly
 include this section.]
 
+## Review Focus
+
+[The five input classes or failure modes the spec implies but no task's
+tests exercise that are most likely to bite a person using this software
+— one line each, naming the input or condition and the behavior a
+reasonable person would expect, most likely first. The spec is a vision
+document: it says what the software must do, not everything it will
+meet, and its silence on an input is not permission for that input to
+break the program. Write the list here, once, with the spec in front of
+you. Then, for each line, add the test that pins it to the task that
+owns the code, in that task's own step style.]
+
 ---
 ```
 
@@ -175,6 +187,8 @@ After writing the complete plan, look at the spec with fresh eyes and check the
 
 **3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
 
+**4. Review Focus:** For each input class or failure mode the spec implies, is there a task whose tests exercise it? The five uncovered ones most likely to bite a person go in the Review Focus section, and each line there gets its test added to the owning task. An empty section means you checked and found none, not that you skipped the check.
+
 If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
 
 ## Execution Handoff
@@ -187,27 +201,24 @@ them to review the plan and choose an execution method before implementation.
 
 **When no execution method has already been supplied:**
 
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Two execution options:**
-
-**1. Subagent-Driven** - fresh subagent per task, review between tasks, fast iteration
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Two execution options: which execution approach would you prefer?**
 
-**2. Inline Execution** - tasks in a session via executing-plans, batched with checkpoints
+- **Subagent-driven** - A fresh subagent implements each task and a fresh reviewer checks it before the next one starts, then a whole-branch review at the end. Most thorough; costs a fresh context per task and per review.
+- **Native** - 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; no independent review until the end. Runs well with a mid-tier session model, since the plan carries the design.
 
-**Recommended for this plan: [pick one] — [one-line why].** Then: **Does the plan capture what you want, and which approach should we use?"**
+**For this plan I recommend <one of the two>, 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>. Does the plan capture what you want, and which approach should we use?"**
 
-Pick the recommendation from the plan in front of you:
-- **Subagent-driven** when tasks are largely independent, the plan is short-to-medium, and a cold executor could pick up each task from its own task block alone.
-- **Inline** when tasks share interfaces/state, build heavily on each other, the plan is long, or you (the parent) already hold the spec/architecture context that a cold subagent would spend a spawn re-deriving each time.
+**Recommended for this plan: [pick one]** — Subagent-driven or Native (Inline), picked from the plan in front of you:
+- **Subagent-driven** when your partner wants a review gate on every task, when the plan is long enough that its later tasks would run on a compacted context inline, or when tasks need a fresh pair of eyes per task.
+- **Native (Inline)** when the plan is short-to-medium, tasks are mostly independent — the same precondition as Subagent-driven — and cheapest-and-fastest single-context execution is preferred. It shines when you already hold the spec/architecture context that a cold subagent would spend a spawn re-deriving each time.
 Say which and why. Never default to one without looking.
 
 **When an execution method has already been supplied:**
 
 **"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Does it capture what you want?"**
 
-**If Subagent-Driven chosen:**
+**If Subagent-driven chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
-- Fresh subagent per task + two-stage review
 
-**If Inline Execution chosen:**
+**If Native chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
-- Batch execution with checkpoints for review

package/skills/writing-skills/SKILL.md

@@ -317,8 +317,8 @@ See `graphviz-conventions.dot` in this directory for graphviz style rules.
 
 **Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
 ```bash
-./render-graphs.js ../some-skill           # Each diagram separately
-./render-graphs.js ../some-skill --combine # All diagrams in one SVG
+node ./render-graphs.js ../some-skill           # Each diagram separately
+node ./render-graphs.js ../some-skill --combine # All diagrams in one SVG
 ```
 
 ## Code Examples
@@ -371,6 +371,8 @@ pptx/
 ```
 When: Reference material too large for inline
 
+Invoke bundled scripts through their interpreter in the prose (`bash scripts/tool.sh`, `node scripts/tool.js`), never by bare path: some harness plugin packagers strip executable bits, and a bare `scripts/tool.sh` fails there with `Permission denied`.
+
 ### Moving Content Into a Skill
 
 Relative paths mean nothing on their own - they resolve against the file holding them. Moving content to a different depth invalidates every relative reference inside it.