Release v7.0.1: brainstorming retune, skills that better survive compaction, contribution templates (#2581)

feat(sdd): align templates and codex reference with resume-based fix rounds
feat(sdd): lifecycle restructure with resume-based fix loop, five-round breaker, and rationalization table
docs(using-superpowers): drop dangling subagent-support anchor (#2010)

The prune in e7ddc25e removed the ## Subagent support section from antigravity-tools.md but left the inline cross-reference to it in the dispatch table, so [Subagent support](#subagent-support) resolves to nothing. An agent following the pointer to learn the difference between the self and research subagent types lands nowhere.

Drop the dangling parenthetical. The guidance it pointed at survives in the same table cell – self for full-capability work, research for read-only – so no content is lost and the row still answers the question the removed section answered.

gemini-tools.md carries the same cross-reference but retains its ## Subagent support heading, so its link is valid and is left alone.

fix(systematic-debugging): match find -path ./ prefix in find-polluter.sh (#2011)

find . emits ./-prefixed paths, so -path “src/**/*.test.ts” matched nothing; wc -l on empty stdin then lied as “Found 1”. Fixes #2008.

Co-authored-by: arimu1 19286898+arimu1@users.noreply.github.com Co-authored-by: Cursor cursoragent@cursor.com

fix(systematic-debugging): find-polluter accepts ./-prefixed patterns and matches top-level tests

Follow-up to #2011 (which fixed the ./-prefix mismatch for the documented pattern form): strip a leading ./ from the caller’s pattern instead of double-prefixing it into a never-matching ././ form, and also match the pattern with ‘/‘ collapsed, since find -path cannot match ‘/‘ against zero directory levels and silently skipped files directly under the base directory (src/top.test.ts vs src/**/*.test.ts).

Adds a deterministic test suite for the script with a stubbed npm.

fix(finishing): check in with human partner when worktree removal hits untracked files

git worktree remove refuses when the tree holds modified or untracked files, and the skill gave no guidance for that refusal — the natural agent response was –force, permanently destroying files that exist nowhere else (uncommitted plans, notes, scratch work). Reported twice from real sessions (#2016’s plan loss, #1223’s dirty-tree ambiguity).

Step 6 now treats the refusal as a stop-and-ask moment: show the untracked files, offer commit / relocate / delete, and only remove the worktree after the human partner chooses. Adds a matching rationalization row so –force-as-cleanup is named as the failure it is.

feat(hermes): Hermes Agent harness support, rebased to a Hermes-only diff

Rebase of PR #1922 onto current dev: the ~14 files of v6.1.0-era codex/release drift are dropped, the porting-guide edits (stale against the post-prune rewrite, no Hermes content) are dropped, and the Hermes surface is kept intact: .hermes-plugin/ (on_session_start bootstrap injection), tests/hermes/ (20 tests, passing), docs/README.hermes.md, references/hermes-tools.md, the Platform Adaptation row, README section, and Python ignores.

Known open items from review, unchanged by this rebase: the injection mechanism uses ctx.inject_message from on_session_start, which the official plugin guide does not document (pre_llm_call returning {“context”: …} is the sanctioned path), skills are not registered via ctx.register_skill, and the acceptance transcript predates the fix.

Co-authored-by: kumarabd kumarabd@users.noreply.github.com

fix(hermes): working bootstrap injection via pre_llm_call + native skill registration

Empirical findings from the quorum eval bring-up (superpowers-evals docs/experiments/2026-07-23-hermes-target-bringup.md):

ctx.inject_message exists but returns False when called from on_session_start — nothing reaches the model. The documented path, a pre_llm_call hook returning {“context”: …} on is_first_turn, verifiably delivers (probe model echoed an injected codeword).
ctx.register_skill requires a pathlib.Path; passing a str raises AttributeError inside hermes, which silently disables the entire plugin (no log line anywhere). This also means any exception in register() is invisible — keep register() failure-proof.
Registered skills are namespaced by plugin name: models invoke skill_view(“superpowers:brainstorming”) and receive the stock SKILL.md — verified live on GLM 5.2, both install layouts.

The plugin now: resolves skills/ for both the git-clone layout (.hermes-plugin/ and skills/ as siblings) and a flattened install, raising loudly when neither matches; registers every stock skill with Hermes’ native loader (no per-harness skill copies); injects the using-superpowers bootstrap via pre_llm_call on the first turn; and sources the tool mapping from references/hermes-tools.md instead of duplicating it. Injected context is transient (API-call time only, never persisted in the session export) — verification of injection must be behavioral.

test(hermes): realign suite with the pre_llm_call mechanism; slim docs to the README section

The 20-test suite still exercised the dead on_session_start/inject_message mechanism (17 failures against the rewritten plugin). Rewritten for the real contract: pre_llm_call registration + first-turn-only context return, register_skill receiving pathlib.Path (the conftest mock now raises on str, mirroring hermes’ AttributeError that silently disables a plugin), both install layouts resolving skills, loud failure when skills are missing, tool mapping sourced verbatim from hermes-tools.md, and a bootstrap-size guard against hermes’ 10k-char context spill threshold. 19 tests, passing.

Install docs collapse into the README section per maintainer direction: docs/README.hermes.md and .hermes-plugin/INSTALL.md are gone; the README carries the two-line install plus the compaction caveat. plugin.yaml version aligned to 6.1.1.

Release v6.2.0: SDD plan-scoped workspace and resume-based fix loop, skills compression sweep, Windows SessionStart fix (#2026)

Release notes for everything on dev since v6.1.1, plus the version bump to 6.2.0 across all seven declared manifest files (bump-version.sh, audit clean). Tagging and marketplace publication happen after the dev -> main merge.

docs: remove the “We’re Hiring” section from the README

The community engineer role has a candidate on trial, so the posting no longer needs to be at the top of the README.

feat(brainstorming): three-path router — ceremony scales, approval never does

Spike / bounded / architectural classification said out loud, one-way upgrade ratchet, approval gate on every path. The measured pathology: the absolute hard-gate wording forced bounded tasks into the full two-document ritual 5/5 while a no-guidance control differentiated paths natively.

fix(sdd): implementers never dispatch subagents

Depth-2 worker-spawned reviewers were 9/9 same-task duplicate reviews across four corpora in the codex-efficiency eval campaign.

fix(brainstorming): bounded-path approval is a hard stop

Live ceremony battery: bounded reps produced zero doc ritual (the measured win) but 2/3 implemented before any approval turn; the bounded path now states the stop explicitly.

fix(codex): correct multi-agent guidance against Codex source

Five claims contradicted by the Codex CLI source (V2 has no close_agent; followup_task always reaches a child; role files attach via agent_type; full-history forks accept model/effort; V2 spawn allowlist). Citations: superpowers-autoresearch docs/2026-07-29-codex-multiagent-v2-capabilities.md.

fix(sdd): reviewers never dispatch subagents either

The first fix-cycle battery moved the depth-2 leak from implementers (9/9 baseline -> 0/6) to a final reviewer that spawned two sub-reviewers; the contract now reaches every dispatched role.

fix(brainstorming): bounded means existing code in this repo, not a familiar app genre

Triggering battery: Claude Code classified a brand-new project bounded 3/3 by reading ‘existing, understood flow’ as genre familiarity — once while explicitly noting the repo was empty. Gemini routed the same prompt architectural 3/3.

fix(codex): event-driven waiting instead of short polls

60-78% of wait_agent calls timed out across every measured corpus; waits are event subscriptions, so one long wait replaces dozens of polls at identical wake latency.

fix(sdd): controllers wait long or not at all

Docs-only wait guidance in the platform reference changed nothing (65.1% vs 67.1% baseline wait-timeout rate); the discipline now lives in the controller loop the session actually re-reads.

fix(sdd,codex): bounded wait stretches with reconciliation

Round 2 proved the long-wait mechanism (65.1%->0.0% timeouts) but 20-38 min silent waits starved graders and let 1/51 children vanish; bounded 5-10 min stretches with a status line and list_agents reconcile keep the efficiency and restore observability.

fix(codex): explicit model+effort on every spawn, config backstop

Depth-2 child-issued spawns omitted model 2/2 at CLI 0.146; model without reasoning_effort resets effort to the model default.

docs: codex-efficiency fix-cycle spec and plan (campaign record)
fix(sdd): rule and continue — non-catastrophic conflicts get ledgered rulings, not blocking questions

A donated session sat dormant 8h48m waiting for a plan-conflict answer that cost ~zero tokens to decide. Wrong-ruling rework is bounded; stalls are not. This encodes the never-stall doctrine: plan conflicts, ambiguities, and cap exceptions get a controller ruling recorded in the ledger and work proceeds; only irreversible/destructive actions, security-sensitive actions, out-of-worktree side effects (merge/push/ publish), and totally-broken plans remain hard stops. Rulings surface in the Finish report instead of as mid-run questions.

Evals: 3/3 no-stall vs control 3/3 stall-at-preflight on a seeded-conflict SDD plan; catastrophic guard 5/5 (every rep reaching a seeded DROP TABLE step refused it); re-validated 3/3 after rebase onto the current fix-PR text; composes cleanly with the evidence-bearing preflight treatment.

Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy

fix(sdd): batch small same-shape tasks into one dispatch

Plans sometimes enumerate many tiny, same-shape edits (one-line fixes, constant changes, a field added across files) as separate tasks. The current loop dispatches a fresh implementer plus review per task, so a 12-micro-task plan costs ~24 subagent seats for what one subagent could do in a single pass. In controlled evals on a micro-task plan, batching cut cost 73% and dispatches 87% with better completion than control; on a 5-non-trivial-task plan the rule correctly never batched (dispatch counts and completion identical to control).

Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy

fix(sdd): preflight emits its pairwise checks as a ledger table and rules on what it surfaces

The pre-Task-1 conflict scan currently permits ‘the scan is clean’ with no evidence the scan happened — mined sessions show controllers skipping straight to dispatch and plan conflicts surfacing mid-execution as blocking questions. Requiring the scan to emit one row per task pair sharing a file/interface and one row per task’s self-consistency turns the claim into an artifact; in controlled evals the table appeared 3/3 with conflicts surfaced pre-dispatch, and the mechanism held 3/3 when composed with the never-stall ruling change (#2077).

Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy

fix(planning): the spec travels with the plan — Spec: header pointer + SDD reads it at setup

In controlled evals, an identical seeded-incoherence plan yielded 0-1/5 correct conflict resolutions when executed specless (controllers ruled the conflicts ‘internally explained’) and 4-5/5 with the spec merely present and named — even with no other skill-text changes. Cross-task coherence turns out to be adjudicable only against ground truth above the plan; this change makes that ground truth travel with the plan.

Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy

fix(sdd): one Ruling: token everywhere, exhaustive finish roll-up

The breaker’s two ledger formats wrote lowercase ‘ruling’ (parked findings, load-bearing adjudications), so the Finish section’s collect-every-Ruling:-line step missed exactly the rulings made under the most pressure. Field evidence from an independent eval rep: a breaker-cap run adjudicated correctly, wrote everything to the plan-scoped ledger, deleted the workspace at finish, and left no durable trace of the adjudication.

Capitalize the two breaker formats to the canonical token, and make the finish roll-up explicitly exhaustive across preflight, parked, and breaker rulings.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

fix(sdd): batch reviews check the diff against the brief’s file list

Batching moves N edits under one review, which changes the review’s failure profile: an implementer that silently skips one file of twelve produces a diff full of correct, uniform edits — nothing conspicuous is missing, and no seat in the pipeline was assigned to notice. The single combined review is the only net for a dropped edit, but the reviewer template never told it to count.

The batch brief already lists every file with its change, so the reviewer reconciles the diff against that list file by file; a listed file with no hunk is a Missing finding regardless of how clean the rest of the batch looks. Conditional on a multi-file brief, so single-task reviews are unchanged.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

fix(sdd): task reviewers re-read illegible evidence instead of re-running to regenerate it

Interrogation of reviewers who bypassed test-evidence leases showed a convergent driver: when the report or receipt looked truncated or couldn’t be located, re-running the suite felt cheaper than re-reading — evidence got regenerated instead of read. This paragraph names that moment: re-read at the stated path, report a genuine gap to the controller, and never re-run to regenerate what wasn’t read.

Battery: 0/31 reviewer re-runs across 4 treatment reps vs 7/~59 reviewers in 5/8 control reps on the same scenario and classifier.

Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy

Moves Community up, and adds ToC.
chore(hermes): align plugin version with dev

Update the Hermes plugin manifest from 6.1.1 to 6.2.0 so PR #2025 matches the current release version at the tip of origin/dev.\n\nThis intentionally does not change the version bump tooling. The existing release script supports JSON manifests only; YAML support will be handled separately on its own branch.

fix(writing-skills): run graphviz without a shell in render-graphs.js

The dot availability check shelled out to which dot, which is not a command on Windows, so render-graphs.js reported graphviz as missing on Windows even when it was installed. Replace it with a direct dot -V probe via execFileSync.

Also switch the SVG render call from execSync to execFileSync(‘dot’, [‘-Tsvg’]). Behavior is identical on macOS/Linux — the diagram source was already passed via stdin, never interpolated into the command — but running the binary directly removes the shell entirely.

test(writing-skills): cover render-graphs execution
fix(finishing): name the actual files in the refusal prompt

git status --porcelain collapses a wholly-untracked directory to a single ?? docs/ line. In the shape of the incident this step exists for (#2016 — an uncommitted plan document under an untracked docs/ tree), the file list we show the human partner therefore names no file at all:

$ git -C "$WORKTREE_PATH" status --porcelain
?? docs/
$ git -C "$WORKTREE_PATH" status --porcelain -uall
?? docs/superpowers/plans/2026-08-04-csv-export-rollout.md

Both forms produce identical (empty) output on a clean worktree, so this adds no over-trigger surface.

Found while running this PR’s behavioral micro-tests. Every treatment agent dug past ?? docs/ unprompted and named the document, so the step did work — but on the agent’s own initiative rather than because the text asked for it. That initiative is not reliable one tier down: Claude Haiku 4.5 on the control arm failed for exactly this shape, asking a question that never named the file and then deciding for the human when they deferred. Nothing in the prior wording stopped a treatment agent from relaying ?? docs/ verbatim and satisfying the letter of the instruction.

Re-ran the treatment cells against this amended text — Opus pass (refusal fired, named the file), Haiku 4.5 pass (named the file) — no regression.

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com

docs: design Hermes version-bump wiring

Document the agreed follow-up to PR #2025 on a branch based on its merged dev commit. The design registers the Hermes YAML manifest, keeps jq for existing JSON files, and uses Mike Farah yq v4 for a narrow top-level YAML field rather than adding a Bash parser.\n\nDefine focused failure behavior and behavioral tests while explicitly excluding nested YAML, Hermes runtime changes, and unrelated release-script refactors. This captures Drew’s request to keep the implementation small and avoid process or abstraction overhead.

docs: reduce Hermes version-bump design

Incorporate the adversarial design review without turning the Hermes wiring follow-up into a general release-script refactor. Keep the existing jq path, add Mike Farah yq v4 only for .yaml, and retain one read-only preflight to prevent deterministic partial bumps.\n\nReduce the test contract to three behavioral cases and explicitly defer .yml support, nested YAML, rollback machinery, audit/status redesign, exhaustive failure matrices, and the separately discovered JSON-expression issue. This follows Drew’s direction to avoid ceremony and overengineering.

docs: plan Hermes version-bump wiring

Record Drew’s approved reduced design after the second staff review. Limit preflight to the mutating bump path, cover audit’s independent read path, and require byte-for-byte proof that deterministic YAML failures cannot partially update earlier JSON manifests.

Provide one TDD implementation task for the Hermes registry entry, jq/yq dispatch, focused preflight, and three behavioral checks. Explicitly defer rollback, audit-status changes, nested YAML, runtime changes, and broader release-tool refactoring.

fix(release): wire Hermes into version bumps

Register the Hermes YAML manifest alongside the existing JSON manifests. Route manifest reads and writes by extension through jq or Mike Farah yq v4, with field names and values passed as data.

Preflight every present manifest before the mutating bump loop so a deterministic YAML read failure cannot leave earlier JSON manifests partially updated. Cover check, audit, bump, registry wiring, and byte-for-byte no-partial-write behavior with one focused fixture test.

feat(opencode): add V2 (opencode2) plugin compatibility

Add dual V1/V2 support to the OpenCode plugin. The same source file now works on both OpenCode V1 (opencode) and V2 (opencode2) without version detection at runtime.

V2 changes:

Add default export { id, server, setup } for V2 PluginSupervisor
setup() registers skills via ctx.skill.transform() (V2 native API)
setup() injects bootstrap via ctx.session.hook(‘context’) (V2 equivalent of V1’s experimental.chat.messages.transform)
config hook guards against V2 array-format skills to avoid conflicts

Both APIs confirmed active at runtime via diagnostics in the V2 beta.

No external dependencies added — pure JavaScript throughout.

Docs updated with V2 install instructions, OPENCODE_CONFIG_DIR side-by-side setup, and accurate How It Works section for both versions.

docs: add Grok Build CLI to README.md
feat: add Devin CLI support

Devin CLI’s devin plugins install obra/superpowers fails today because the repo has no .devin-plugin/plugin.json manifest. Add the manifest (skills are auto-discovered from the co-located skills/ directory), a Devin tool mapping linked from using-superpowers’ Platform Adaptation section, a README install section, version tracking in .version-bump.json, a Codex-sync exclude for the new dotdir, and a CI-safe test mirroring the kimi/antigravity test style.

Bootstrap rides Devin’s native skill surfacing: every installed skill’s name + description is injected into the system prompt at session start with a standing instruction to invoke matching skills via the native skill tool. Acceptance test (“Let’s make a react todo list”) passes in a clean session: using-superpowers and brainstorming auto-trigger before any code is written.

Drop devin-tools.md — not needed for correct operation

Re-ran the clean-session acceptance test with the mapping file and the SKILL.md Platform Adaptation pointer removed: using-superpowers and brainstorming still auto-trigger first, and the full workflow chain (writing-plans, executing-plans, TDD, verification) resolves every action to Devin’s native tools. Devin CLI’s own system prompt already documents its tools (skill invocation, subagent profiles, todo tracking, question prompts), so the mapping was redundant. Test now validates the manifest only.

docs: streamline README getting started navigation

Remove the redundant Quickstart entry and section now that the README has a table of contents. Rename the Installation label in the table of contents to Getting Started while retaining the existing installation anchor and section heading.

docs: keep Hermes in installation navigation

Add Hermes Agent to the installation entries in the table of contents. The removed Quickstart section was the README’s only direct link to that existing installation section, so preserving the link avoids a navigation regression.

feat(tdd): the project’s suite defines green, not just your test file

At the Verify GREEN moment, redefine “other tests still pass”: run the project’s test command even when the task named only one test file — a scope statement bounds the deliverable, not the verification — and any failure seen goes in the report by name. In a pre-registered 24-rep battery on an adjacent-breakage probe, controls ran the wider suite in 1/12 sessions; with this text, 8/12 (sonnet 4/4, kimi 3/4, glm 1/4), and every session that saw the failure reported it.

Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy

docs: release notes for v6.3.0
chore: bump version to 6.3.0
Update to Prime Radiant Community Code of Conduct. (#2122)
docs: add Qwen Code install instructions to README

Rebased from PR #2108 onto the reworked README. Differences from the PR: the Hermes TOC entry and Quickstart-line changes are obsolete (the v6.3.0 README rework already added the former and removed the latter), and the Hermes post-compaction caveat stays: .hermes-plugin injects the bootstrap only on is_first_turn, so the caveat is still accurate.

Install/update commands and the acceptance transcript are from PR #2108 (@arittr, tested interactively on Qwen Code).

Co-authored-by: Drew Ritter arittr@users.noreply.github.com

fix(requesting-code-review): anchor the multi-commit BASE_SHA alternative to the merge base

The ‘# or origin/main’ alternative fed a moving ref into the reviewer’s two-dot diff: once origin/main advances past the branch point, main’s new files appear as phantom deletions the reviewer can’t distinguish from real ones. Reproduced during triage (2026-08-12): a scratch repo with main advanced one commit shows ‘main-new.txt | 1 -‘ in the branch’s diff. git merge-base origin/main HEAD anchors the range to the branch point, matching how sdd’s review-package already computes BASE.

Reported in #2118 (wan-huiyan). Fixes #2118.

fix(sdd): invoke sdd-workspace via bash so helpers survive stripped exec bits

Codex marketplace users hit ‘Permission denied’ running SDD helpers: some extractors (Python zipfile) discard Unix mode attributes when unpacking the package, so task-brief’s and review-package’s direct exec of their sibling sdd-workspace fails. Our packaging preserves 0755 (git archive | tar -xpf, asserted by the existing packaging test) — the bits are lost on the consumer side, which no packaging change can reach. Invoking the sibling via “${BASH:-bash}” makes the exec bit irrelevant.

TDD: new regression case copies the helpers, chmod -x, runs task-brief via bash — RED with the reported rc=126 Permission denied, GREEN after.

Reported in #2040 (michaelholcomb-creator). Fixes #2040.

fix(sdd): reject empty or non-descendant BASE..HEAD ranges in review-package

When an SDD implementer commits to the wrong branch (#2050), the BASE..HEAD range handed to review-package is either empty or not rooted at BASE. Both cases previously produced a review package silently — an empty one lets the reviewer approve “clean” work that isn’t there.

Add two mechanical guards after BASE/HEAD validation, exiting 3 (vs 2 for usage errors) so callers can distinguish range problems:

git merge-base –is-ancestor BASE HEAD, else “HEAD is not a descendant of BASE”
git rev-list –count BASE..HEAD > 0, else “empty commit range”

Guard shape credits the analysis in closed PR #2082 by @stantheman0128.

Fixes #2050

fix(opencode): adapt to V2 skill draft API removal (#2106)

OpenCode V2 removed SkillDraft.source() in 1113adfd5e (#41622): the skill service now stores values only, and filesystem scanning moved to the config side. The plugin’s draft.source({type:’directory’}) call threw ‘draft.source is not a function’, which killed the entire V2 plugin activation generation. Because V2 gates model.list on PluginSupervisor.flush (23b0688a7f, #41783), that failure left flush pending forever and the TUI showed no providers or models (‘Model catalog initialization timed out’, /api/model 503).

Register each skills//SKILL.md as a native Skill.Info object via draft.add({id, name, description, location, content}) instead, matching the {list, add, update, remove} draft API and the pattern used by V2’s built-in skill plugin. Wrap skill registration, hook registration, and the context hook callback in try/catch so a future V2 API change degrades to a logged error instead of taking down the whole generation again. session.hook(‘context’) payload shape is unchanged and keeps working.

Verified end-to-end on opencode2 v0.0.0-beta-17595: 24 skills listed via /api/skill (all superpowers skills present), /api/model returns 83 models across 3 providers, no ‘failed to reload plugins’ in server logs. V1 path untouched.

fix(opencode): skip V2 setup when V1 invokes it with a V1-shaped ctx

opencode 1.18.18 also calls default.setup, but with a ctx that lacks the skill/session domains, so the defensive try/catch logged a TypeError into every V1 session transcript even though V1 is fully served by the SuperpowersPlugin named export. Detect the V1 shape and return quietly.

feat(skills): import proving-it-works-with-a-movie from its standalone repo

Brings the proving-it-works-with-a-movie skill (demo/screencast/proof-video recording, plus the check-movie timeline gate that catches frozen pictures, narration drift, and dropped words) into superpowers core, along with its supporting docs, scripts, and shell regression tests.

Source: prime-radiant-inc/proving-it-works (MIT, same copyright holder), skills/proving-it-works-with-a-movie/ at time of import. The five scripts (narrate, make-subtitles, assemble, burn-subtitles, check-movie) are self-contained uv –script files with inline PEP 723 dependency declarations, so they port with no new project-level dependency wiring.

Test paths were adjusted one directory level to match superpowers’ tests// layout (the standalone repo kept tests/ as a top-level sibling of skills/).

Adds a Verification entry to README’s Skills Library list.

Goal: fold this into 6.4 and retire the standalone repo.

fix(opencode): skip controller bootstrap in task subagent sessions (#2160)

Detect child sessions structurally via session parentID instead of relying on the model honoring :

V1: sessionID from firstUser.info.sessionID (hook input is empty at runtime), parentID via client.session.get({path:{id}})
V2: sessionID from the context-hook event, parentID via ctx.session.get({sessionID})

Decision cached per session; lookup failures fail open (previous behavior) and are not cached. Skills registration is unaffected, so workers keep explicit access to execution skills.

fix(opencode): skip controller bootstrap in task subagent sessions (#2160)

The messages.transform hook injects the using-superpowers bootstrap into the first user message of every session, including task subagent children. Workers then restart brainstorming/design cycles for work the parent already authorised — the note inside the bootstrap only works when the model chooses to honor it.

Detect child sessions structurally instead: OpenCode task sessions are created with a parentID, so when the session carrying the message has a parentID, skip bootstrap injection. The hook receives no input at runtime (verified in the 1.18.x bundle: trigger(…, {}, {messages})), so the sessionID is taken from firstUser.info.sessionID and the session record is fetched via client.session.get({path:{id}}).

The decision is cached per session; lookup failures fail open (previous inject-always behavior) and are not cached so transient errors recover. Skills registration is untouched — workers keep explicit access to execution skills.

fix(opencode): add root index.js entrypoint for v2 directory-form registration
docs(opencode): remove and merge identical v1/v2 install and update guidance
Fix platform-support issue template to apply a label that exists

The template auto-applies platform-support, but the repo has no such label (harness requests use new-harness). GitHub silently drops labels that don’t exist, so every platform-support request arrives unlabeled — the Amazon Q request (#2194) is the latest example.

Claude-Session: https://claude.ai/code/session_01UiEfXTZAC5cuH4hgx24mbB

fix: establish shared intent before implementation

Discover the intended outcome, audience and success criteria before proposing features when the request leaves them unclear. Reflect the understanding for correction and carry it into the selected path’s design artifact.

Bind approval to the actual stage presented: new architectural work requires written-spec review and the planning handoff before implementation. Preserve the existing lighter spike and bounded paths and clarify the short-design example accordingly.

Jesse requested this repair after a React todo session advanced from feature scope approval without establishing purpose. The controlled CLI comparison observed purpose discovery in 5/5 candidate openings versus 0/5 controls, with full-chain and holdout outcomes and their limits recorded in the PR. This commit preserves the independently reviewed skill bytes; research artifacts and the original development history are archived outside the PR.

fix: review the saved plan before execution

Present the saved, self-reviewed plan for human review before implementation. Request an execution method when none was supplied; preserve an existing choice and ask only for plan review when the human already chose a method.

This completes the shared-intent repair without interpreting approval of an earlier idea or scope as approval of an unseen implementation plan. Four saved-plan smoke cases covered old/new wording with/without a prior choice; all passed the narrower handoff checks, including old controls, so this is not evidence of measured improvement.

Jesse requested consolidation into two commits and removal of the supporting spec/plan research content from the PR. The skill bytes remain identical to the reviewed branch; the complete research and original history are retained in local archives.

docs: specify proof movie OS compatibility
docs: resolve adversarial review of movie compatibility spec
docs: plan proof movie OS compatibility with Windows validation host
test(movie): validate native Windows recording mechanism
fix(movie): release probe resources after evidence failures
docs(movie): avoid repeating the interactive probe take
test(movie): port regression fixtures to Python
test(movie): verify first subtitle cue offset
fix(opencode): differentiate tool mapping by host flavor and harden child detection

Current opencode2 builds renamed the model-facing tools (bash→shell, task→subagent with agent instead of subagent_type, apply_patch→ patch/patchText) and removed todowrite entirely, so the single v1 mapping injected on v2 hosts taught the model stale tool names.

export V1_MAPPING/V2_MAPPING and inject the flavor-correct one on each path (v1 messages.transform → V1; v2 ctx.session.hook(“context”) → V2, incl. no-todo-tool guidance and sessionID continuation)
child-session detection now keys on parentID presence (primary signal on both flavors) with dual-shape unwrapping preserved; v1
2160 behavior unchanged
mirror surfaces updated: INSTALL.md dual mapping tables, README.opencode.md host-flavor notes, test-bootstrap-caching.mjs asserts both mappings + drives the v2 context hook end-to-end
skills: add OpenCode to executing-plans’ subagent-capable list, accurate OpenCode worktree status (git fallback; TUI dialogs are user-side only), generalized live-subagent resume guidance

fix(movie): make frame and concat inputs portable
docs: scope remaining movie work to Windows completion
docs: resolve adversarial review of Windows completion scope
docs: plan three milestones to finish Windows movie support
fix(opencode): drop skill-content edits from this PR

AGENTS.md requires evaluated adversarial testing for any skill-content change; these three one-line harness-accuracy notes don’t clear that bar, so they are deferred to a separate evaluated change. The PR now ships plugin, docs, and test changes only — no skill content modified.

fix(movie): finish native Windows media tools
feat(movie): support native Windows terminal recording
fix(movie): verify terminal health before finalizing takes
docs(movie): document and verify Windows workflows
docs(movie): correct reserved regression suite names
chore(movie): drop the abandoned OS-rollout probe and superseded plans

The first, broader OS-compatibility rollout was stopped and replaced by the narrower Windows completion. Its feasibility probe, probe cleanup test, design, review, 12-task plan, results report, and the completion plan and review record were internal execution artifacts with machine-specific paths. The one probe-derived test list is inlined into the terminal suite.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

test(movie): keep one portable test suite

The Python suite ported the three shell tests’ assertions so they run on Windows; both copies were kept and the README mapped one to the other. Keep the portable suite. Drop the one-shot Windows acceptance driver and its browser fixture, which produced evidence rather than regressions, and the never-implemented reserved suite names.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

docs(movie): trim Windows guidance to what the tools need

Remove generic shell exit-status recipes and a stills wrapper that the card scene already covers. Keep the gdigrab commands and the verify-on notes short. Reduce the spec to the design: drop execution logistics, host names, and references to deleted files.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

test(movie): keep tool output out of the test log

The in-process narration and subtitle tests let the tools’ stdout and stderr through to the runner. Capture both and assert the expected diagnostics.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

feat(movie): simplify the Windows terminal recorder to serve/run/key/watch/close

Windows has no tmux, so the recorder had grown into a 738-line daemon with a file-based request protocol, request IDs, wait-only result retrieval, and a Win32 Job Object module. Replace it with the Unix route’s shape: serve keeps ttyd and a headless browser alive and logs the terminal’s output; run, key, watch, and close are one-shot CDP calls against that browser. The installed prompt reports each command’s status through the window title, so run can print it without any visible marker.

Process cleanup uses taskkill /T (a pgrep walk on Unix) instead of Job Objects, which also simplifies the card renderer. The session tests run on macOS too, since nothing in the script is Windows-specific.

Verified: 9 session tests per shell on Windows 11 for PowerShell 5.1, PowerShell 7, and Git Bash; the browser suite with Chrome and Edge; 44 portable tests on macOS against a real ttyd session.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

feat: add diagnosing-superpowers skill

Evidence-based diagnosis of superpowers sessions: intake with the human partner, safe transcript reading for Claude Code and Codex (discovery procedure for other harnesses), seven analyst subagents, a report with path:line evidence and a bounded superpowers-involvement line, scrubbed export bundles, approval-gated GitHub issue search/draft, and similar-session search. Includes spec, plan, structure test, and README and docs index lines.

Developed RED-GREEN-REFACTOR per writing-skills: 46 scored scenario runs across five SKILL.md versions, all twelve scenarios clean against the final version, micro-tests control 5/5 to skill 0/5 on both baseline-failing prohibitions, and one end-to-end run. Eval records are kept by the maintainer outside the repo.

Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7

docs: add ‘When Something Goes Wrong’ README section for diagnosing-superpowers
diagnosing-superpowers: build the scrubbed bundle only on request

Never build or push a bundle unprompted. When intake names a bug report as the goal, say once that a bundle is available on request, then wait. On handover, state what the bundle contains, point at the scrub log, and say scrubbing can miss things so every file needs review before sharing. Raise the SKILL.md word budget to 1000 to fit the added rule.

diagnosing-superpowers: share the analyst preamble and context-safety rules

The seven analyst prompts opened with an identical 39-line block (role, inputs, context safety, return format). It now lives once in prompts/analyst-common.md and each dimension prompt points at it. The wc -lc / long-line / never-cat rule was restated in nine places; it now lives in references/context-safety.md and everything else points there. Addresses arittr’s review on #2236.

diagnosing-superpowers: drop gh; file issues through a prefilled template link

A default gh login carries the repo scope, which is write access to every repository the user can reach. The skill now searches issues through the unauthenticated public API and, instead of posting, hands the partner a prefilled new-issue link. The link uses a new diagnosis_report.md issue template so the bug and automated-issue-report labels apply regardless of the reporter’s permissions. Addresses arittr’s review on #2236.

diagnosing-superpowers: say ‘plan step’, not ‘commitment’

In a transcript full of git commits, ‘commitment’ and ‘committed to’ read as version control. The plan-adherence and quality-evidence prompts now say ‘agreed plan’ and ‘plan step’.

spec: ‘agreed to’, not ‘committed to’, in the plan-adherence summary
diagnosing-superpowers: writing review fixes

Move GitHub search and prefilled-link mechanics to references/github-issues.md. State the redaction levels neutrally instead of nudging toward more data. Say that all seven analysts always run and what the quick-reference table is for. Add a title slot and a bundle slot to the issue template. Drop the duplicated human-prompts rule from request-conflicts. Prose fixes: active voice, dangling modifier, vague referents, two lists turned into tables.

diagnosing-superpowers: use gh for issue search and creation

gh handles auth, rate limits, and JSON, and the approval gate on the exact issue text already covers posting. Keep the public-API and prefilled-link paths as fallbacks for machines without gh. Note that GitHub drops labels from reporters without push access, so the template footer is the durable marker of a skill-filed issue.

Use shared session discovery in diagnosing-superpowers

At Drew’s request, apply the evaluated shared-discovery variant to Jesse’s existing PR #2236. Resolve native session sources and record semantics from available tools, documentation and bounded inspection. Record verified absolute paths, linkage, extraction queries, human-message distinctions, usage-counter semantics and uncertainty once in the case for all analysts to consume. Replace the three per-harness references and update structural checks.

This is exactly the evaluated source tree at 3f0a63e860d4719397e584e90cc7af07a247cb6d, applied as one commit on 801badbf719f4044c97175e5b01fb6f7cbc32c2d. Fourteen files change; 126 lines added, 285 removed. No private eval fixtures or transcripts ship.

Validation:

Structural test: 45 passed, 0 failed before and after application.
Staged tree exactly matches the evaluated candidate; diff check passes.
Independent read-only review: no actionable blockers.
Retained before/after full doctor runs: one pair each on native Claude, Codex and Pi. All six delivered reports and completed seven dimensions. Shared discovered all three native session families without the removed references. Both versions had report-quality defects; shared Codex deleted its cited case through a fixture symlink. Preserve this negative result.
Eight fresh Codex follow-ups: original/shared x symlink/ordinary-home x two repeats, one retained historical session family. All eight retained cases and supported the four core findings. Seven native final deliveries; one shared run stopped on provider capacity after writing its report. No deletion recurred. One original reused three analysts for seven tasks. Recorded follow-up cost $34.8617883, all eight attempts accounted for.

These observations support this scoped simplification, not general equivalence or a causal claim that reference removal caused or could not cause a failure. Child assignment/model choices were native behavior; the complete variants also differ in analyst prompts. Common provenance, citation-verification and measurement problems remain separate follow-ups. No new paid runs were made for this publication; evidence and independent audits are retained privately by Drew. Behavioral evaluation provenance: campaigns 358c7333-c5f0-48bd-a733-61196da992ed and 102d630d-30ef-49a0-97e1-8dd410ed0548.

Prepared with GPT-6 using Codex through Paseo; local codex-cli 0.153.4. Skills used: superpowers writing-skills, using-git-worktrees, requesting-code-review, verification-before-completion; primeradiant-ops linear-ticket-lifecycle. Drew approved publishing this evaluated variant. Enabled plugins in the publishing checkout’s Codex configuration:

github@openai-curated
documents@openai-primary-runtime
spreadsheets@openai-primary-runtime
presentations@openai-primary-runtime
primeradiant-ops@primeradiant
slack@openai-curated
linear@openai-curated
codex-security@openai-curated
pdf@openai-primary-runtime
template-creator@openai-primary-runtime
sites@openai-bundled
visualize@openai-bundled
computer-use@openai-bundled
cloud-build@superpowers-cloud-build
browser@openai-bundled
superpowers@superpowers-dev
stream-deck-agents-codex@drew-local
computer-history@openai-bundled
codex-app-tools@openai-bundled
unified-computer-use@openai-bundled
chrome@openai-bundled
bits-and-bolts@mcp-extensions-early-access
visual-probe@visual-probe-local

Tracking: PRI-3127

Preserve diagnostic evidence through doctor export

Align scrubber and independent audit prompts around one shared redaction policy while preserving safe command, result, source, session-line, quotation, and linkage structure. Add finished-handoff evidence and reconciliation instructions, provenance labels across case/report/bundle/issue templates, and the structural existence check for the shared reference.\n\nThis patch responds to the retained negative post-report handoff baseline: cited result bodies were removed wholesale, source findings and the positive related-session match were not verifiable, provenance and export statements were stale, and scrub counts disagreed. The behavioral handoff validation remains pending for the follow-up task; this commit records only the focused product guidance and structural RED/GREEN evidence.

Clarify scrub audit return contract

Remove the obsolete CLEAN branch beneath the audit prompt’s Otherwise return instruction. CLEAN remains governed by the preceding no-misses condition, and MISSED is now the only alternative. Verified with the focused structural test and git diff –check.

fix(movie): preserve rejected narration and prior takes

Prevent failed narration scenes from entering the cache manifest, while leaving their generated WAV files available as failure evidence. Add filesystem-backed regressions covering repeated rejected chat synthesis, accepted-scene reuse, and strict ASR rejection of cached audio.

Refuse nonempty recording directories both before CLI session side effects and at the direct film boundary. The regression preserves existing numbered frames and a sentinel byte-for-byte across run, key, watch, and direct film refusal.

Make subtitle capability tests independent of the host FFmpeg installation, skip the real pixel test before probing unavailable tools, retain strict skipped-capability rejection, and remove only the unused websockets runner dependency.

docs(movie): make native Windows recorder recipes executable

Replace the Git Bash PowerShell shorthand with complete native commands, explicit path conversion, a kept-alive serve task, bounded readiness, and run/key/watch/close examples. Use native input and sleep commands so the recipe works without a sample app. Explain empty take directories and PowerShell 5.1 embedded-quote escaping observed in native trials.

The original PowerShell missing-cwd finding does not reproduce when the session is nested under the working directory; retain the successful baseline and describe explicit directory creation as setup clarity.

Fresh readers exercised the final recipes on native PowerShell 5.1, PowerShell 7, and Git Bash. Preserve the failed first candidate and driver setup failures, distinguish instruction trials from full skill evaluation, and keep movie acceptance with Drew. Record Drew’s approval of the normal workflow dependencies and the bounded repair plan.

Fix narration cache identity and partial subtitle offsets

Address the fresh review on PR #2214 after the #2275 integration. Drew approved fixing the two reproduced bugs and keeping the specified auto/on/off verification semantics.

Cache accepted narration by normalized text plus effective engine, voice, and synthesis model. Resolve voice defaults before rendering, invalidate entries without settings, and retain requested ASR checks on cache hits. Exclude rejected clips as before.

Treat manual subtitle offsets as start-time overrides. Only assembly offsets JSON selects scenes in the cut, including when manual timing overrides are also supplied. Empty narrated cuts write an empty SRT without crashing.

Make the gated Unix example pass –verify on and document the actual local ASR modes. Auto remains permissive if ASR is unavailable; on remains strict.

Validation: observed the new cache and subtitle regressions fail before the fixes; all 23 focused narration and subtitle-text tests now pass. Synthesis, duration probing, and ASR are mocked. No media inspection or live ASR was performed; Drew retains final video acceptance.

Fix inserted narration and movie audio subtitle checks

Address the final three review findings on PR #2214, as approved by Drew. Count both sides of every non-equal transcript span so a short insertion or expanded replacement cannot evade the drift gate on a longer script. Preserve the existing length and run thresholds.

Honor –no-expect-audio for encoded silent tracks. Base subtitle requirements on detected audible speech so opting out of expected audio does not suppress captions for speech that is present.

Extract the first embedded subtitle stream as SRT when no sidecar is present and apply the same cue-end check to either source. Empty cues fail even for short narration, and extraction or malformed timing errors are reported as failures. Preserve the silent end-card allowance.

Validation: the new tests first reproduced ten failing cases across narration insertion, silent-track opt-out, and embedded subtitle handling. All 35 focused narration, checker-policy, and subtitle-text tests now pass. External media commands, audio and picture sampling, contact-sheet creation, synthesis, and ASR were mocked; no actual media inspection or live ASR was performed. Drew retains final video acceptance.

docs: plan consolidated movie committee repairs

Drew requested a whole-PR committee review after repeated narrow fixes missed failures. Record the repair boundaries, acceptance handoff, timing and lifecycle contracts, and focused regression cases before implementation. Preserve existing artifact formats and Drew-owned video acceptance; all automated checks in this pass use mocked media boundaries.

fix(movie): make narration acceptance govern assembly

Repair Task 1 from the 2026-09-11 movie committee plan. Narration now atomically withdraws acceptance before it mutates accepted bytes, stages failed takes as retained evidence, and publishes a manifest entry only after transcript gates and duration measurement. It preflights ffprobe, preserves bounded retries and cache identity, and distinguishes unsupported token comparison from cache identity.

Assembly now validates accepted manifest narration before it starts encoding, ignores generated narration for movie scenes, selects manifest WAV paths, maps source or synthetic movie audio explicitly, fits wide movies within the requested inner rectangle, and escapes only literal directory percent signs in sequence paths. The focused regression suite mocks every media boundary; real-media fixture declarations are updated but not executed. Prompt constraints prohibit real media generation, probing, inspection, synthesis, ASR, browser, checker, or full media suites.

fix(movie): retain narration evidence through verification

Address Task 1 review round 1. Treat successful empty ASR output as speech failure rather than an unavailable verifier, reject empty chat claims within the existing bounded retry loop, and extend unsupported segmentation detection to supplementary CJK ideographs.

Withdraw cached acceptance before every revalidation so strict failures and interrupts cannot leave stale publication. Preserve nested manifest WAV paths on cache reacceptance, and measure a unique candidate before promotion so duration failures retain their evidence across reruns. Add structured movie geometry coverage plus both silent and source-audio mapping tests. All tests use uv –no-project with mocked synthesis, ASR, probes, and encoding; no media operation was run.

test(movie): cover unsupported ASR and ordinary retries

Close Task 1 review round 2 without production changes. Feed actual unsupported ASR text through auto and strict verification while proving off does not call ASR. Run the second rejected narration invocation without –force, then assert it synthesizes new takes and retains distinct rejected bytes instead of reusing cache evidence.

fix(movie): keep subtitle timing and track selection faithful

Implement Task 2 of the movie committee repairs. Allocate proportional cue boundaries across each complete rounded scene interval, reserve positive millisecond spans, and coalesce chunks when the available interval cannot represent them separately. Readability limits guide word splitting without dropping text or clipping narration tails; invalid intervals fail before subtitle output is written.

Explicitly select the supplied soft subtitle track with optional source audio, including the hard-burn fallback. Parse only numbered SRT cue timing lines so arrow-bearing captions cannot crash the checker or inflate coverage. Preserve the existing maximum cue end policy, assembly-offset intersection, and partial manual retiming.

Add 17 safe subtitle contracts and register the contracts runner suite. Real-file mocked narrate/assemble/subtitle reruns retain removed narration WAV evidence while omitting stale assembly audio and offsets. Verification: 41 contract tests and 18 authorized existing regressions pass; only text and mocked media boundaries were exercised. Native Windows and human video acceptance remain outside this verification.

fix(movie): refine subtitle chunks using allocated durations

Address Task 2 review round 1: initial character budgets count spaces that disappear between chunks, so proportional timing can exceed –max-secs even when a further word-boundary split is feasible. Reallocate after splitting an over-target multiword cue, checking actual integer millisecond intervals each time.

Coalescing runs once before refinement, and refinement stops at the available millisecond count or unsplittable words. This keeps tiny impossible readability targets bounded while preserving every word and the full measured scene interval.

Added a failing six-second unequal-chunk regression and a tiny-target termination/positive-interval guard. The RED emitted 3273 ms for a cue with a 3000 ms target. GREEN: 43 safe contract tests and six covering existing offset/BOM tests pass. All verification remained text/data or mocked media boundaries.

fix(movie): own recorder cleanup and bound observation

Implement Task 3 of the consolidated PR 2214 movie repairs. Startup failures could leak an already launched ttyd or browser because acquisitions preceded the cleanup block; close killed historical numeric PIDs and reported success without confirmed cleanup. Register each acquired resource inside serve’s try/finally, invalidate readiness on shutdown, retain logs, and atomically retire PID metadata only after confirmed owned-process and profile cleanup. Close now requests stop and waits under one overall 30-second deadline without killing PIDs.

Poll CDP and owner readiness while observing commands without recording, preserving a completed native exit status across simultaneous disconnects and reserving exit 2 for live unfinished commands. Fill only bounded 5 fps slots when a final capture crosses the hard or hold endpoint, correctly strip ST-terminated OSC titles, and emit ASCII-escaped stdout JSON while preserving UTF-8 session files. A serve-only CDP call-boundary check prevents a stop from waiting through multiple consecutive calls.

Add 21 contract tests using fake processes, fake websocket responses, fake clocks, byte-token capture callbacks, and intercepted frame writes. Register real-session test cleanup immediately after Popen and retain live PID snapshots, but do not execute that fixture. RED evidence and implementation report are in .superpowers/sdd/2026-09-11-movie-committee-repairs/task-3-report.md. Validation: 26/26 authorized prompt, serve-argument, and recorder contract tests pass; git diff –check passes. No media generation, inspection, browser/ttyd launch, real session or frame-grid suite was performed. Native movie acceptance remains Drew’s review; an abruptly hard-killed owner with a live browser and stale readiness remains the agreed limitation.

fix(movie): retain incomplete cleanup and command evidence

Address both independent Task 3 review findings at 42486dbb. When an owned leader exits before tree cleanup, the existing parentage helper cannot confirm orphan descendant cleanup. Treat that state as incomplete, preserve PID metadata, return failure, and never invoke the helper on the exited leader’s numeric PID. Continue releasing the other owned resources without adding descendant tracking.

Keep a recording capture failure truthful while preserving available completed command evidence: outcome remains failed, exit status remains 1, and the capture error is retained alongside ok, native exit_code, and cwd. A completed successful command does not make a failed recording successful, and no successful take manifest is published.

TDD regressions reproduced an exited leader incorrectly returning 0 and capture failures dropping completed native status for exits 0 and 7. All 14 covering lifecycle and observation tests pass using fake process handles, fake clocks, mocked capture/log boundaries, and intercepted media writes; git diff –check passes. No real media generation or inspection, process/browser launches, SessionTests, FilmGridTests, or full media suites were executed. Detailed RED/GREEN evidence is appended to .superpowers/sdd/2026-09-11-movie-committee-repairs/task-3-report.md.

docs: make proof-movie recipes preserve failures

Repair the shipped Unix, logging, subtitle, cursor, narration, and recorder guidance against the literal fake-boundary failures recorded for Task 4. The primary pipeline and subtitle recipe now fail fast, measured offsets reach subtitle generation, producer logging preserves the real status under the pipefail owner, and cursor mouseup restores the released state.

Document the accepted narration/cache contract, cooperative recorder cleanup limits, and the safe contracts-suite entrypoint without changing Windows recipes or the existing evidence and human-viewing gates. Include the controller-owned plan bookkeeping and record the executable RED/GREEN results while leaving independent fresh-reader trials pending.

Prompt: implement Task 4 focused executable movie-guide corrections after Tasks 1-3, using writing-skills and only fake producers, text fixtures, and fake DOM execution.

Verification: python3 .superpowers/review/pr2214/committee/recipe-probes.py; uv run –script tests/proving-it-works-with-a-movie/run-tests.py –suite contracts; git diff –check.

docs: record consolidated movie repair verification

Complete the four-task repair plan after independent reviews and two fresh-reader reference trials. Record 66 current contract tests and 45 existing safe regressions, executable recipe failures and repairs, and the limits of those checks.

Drew requested a committee and full local review after repeated PR feedback. Preserve the negative evidence, distinguish historical native runs from current mocked/text checks, and retain Drew’s video viewing as final acceptance. The whole accumulated PR review and authorized existing-branch update remain the next steps; no merge is performed.

Reject invalid chat transcripts and propagate browser cleanup failures

Address the two final whole-PR findings from the consolidated movie repair brief. A fresh openai-chat response must provide a speech-bearing string transcript even when local ASR is off; null must not reuse the no-transcript sentinel belonging to deterministic engines or cached accepted audio. Preserve the bounded candidate loop and rejected-byte evidence.

Report failed Windows tree termination as OSError so the recorder owner’s existing per-child handler continues all cleanup and retains failure metadata. Card rendering checks its acquired browser handle before acting on the PID, propagates wait failure, and reports locked-profile removal instead of allowing a pending successful return to hide incomplete cleanup.

Add fake HTTP/process/filesystem boundary regressions for both findings, including real adapter invocation, accepted chat cache reuse, ASR modes, normal completed cards, and serve cleanup after a failed leader later exits. Correct the rejected-chat fixture to use the chat engine. No media or native browser execution was performed; Drew retains personal video acceptance.

Validation: expected RED failures retained; 40 focused tests and the single 75-test contracts entrypoint pass. Full evidence and self-review are in .superpowers/sdd/2026-09-11-movie-committee-repairs/final-fix-report.md.

fix(opencode): align V2 tool mapping with the 2.0.3 catalog; harden plugin internals

V2 bootstrap mapping now teaches write/edit/websearch (verified against a live v2.0.3 /api/plugin tool catalog) instead of routing all file mutation through patch
frontmatter parser tolerates CRLF and YAML block scalars/continuation lines
child-session cache is bounded (512 entries, oldest-quarter eviction)
INSTALL.md and docs/README.opencode.md tool tables synced to the 2.0.3 catalog; unit-test needle list extended to cover the new tools

Invoke bundled scripts through their interpreter in skill prose

Plugin packagers for other harnesses can strip executable bits from the files they ship. The Codex marketplace cache delivered the SDD helpers as 0644 (#2040), and the MiniMax Code marketplace ships its repackaged copy of our skills tree with every file at mode 600. On those installs every bare invocation in our skill prose – scripts/start-server.sh ..., scripts/review-package ..., ./find-polluter.sh ..., ./render-graphs.js ... – fails with “Permission denied”, so the brainstorming visual companion, subagent-driven development, the polluter bisection helper, and render-graphs are all broken there even though the repo records the files as 100755.

Spell every script invocation in skills/**/*.md through its interpreter instead: bash for the shell scripts (start-server.sh, stop-server.sh, sdd-workspace, task-brief, review-package, find-polluter.sh) and node for render-graphs.js, per each script’s shebang. That form works whether or not the exec bit survived packaging. The MiniMax Code marketplace package independently applied exactly this edit to its copy of v6.2.0; this brings the same pattern upstream so every packager gets it.

Nothing else in the prose changes. #2134 covers the complementary case of a script exec’ing a sibling script (task-brief and review-package calling sdd-workspace) and is still needed alongside this.

Record the rationale in docs/porting-to-a-new-harness.md (Part 6 distribution notes plus an Appendix B gotcha) and add a one-line note to writing-skills’ File Organization section so future skill authors don’t strip the prefixes.

Refs #2040, #2134.

fix(opencode): register skills with Skill.Info 2.0.4 path field; contain per-skill add failures

Reported on PR #2106 (80avin): on OpenCode v2.0.4 the plugin is disabled at startup with “Plugin disabled after skill.transform failed”, losing both skill registration and bootstrap injection.

Root cause: upstream commit 199aabe9e2 (first released in v2.0.4) renamed Skill.Info’s required file field location -> path and removed slash. draft.add() decodes payloads with Schema.decodeUnknownSync against that schema, so our location payloads now fail decode with “Missing key path”.

Why the failure was silent: the decode error is thrown during the host’s state rebuild, where the State layer catches it and hard-disables the whole plugin group asynchronously - the throw never reaches the try/catch around ctx.skill.transform(), and the session “context” hook is torn down as collateral.

Fix:

skill payloads now use path (2.0.4 contract); no v2.0.3 compatibility retained per review decision
draft.add() failures are contained per skill inside the transform callback, so one rejected payload skips that skill (visible in server logs) instead of the host disabling the entire plugin
new test-skill-registration unit test pins the 2.0.4 payload contract (absolute path field, no stale location/slash, hostile-add containment) and is registered in run-tests.sh; full suite 3/3 green

fix(sdd): ownership markers stop same-basename plans sharing a workspace

sdd-workspace slugged workspaces by basename alone, so docs/alpha/plan.md and docs/beta/plan.md resolved to one directory and task-brief silently overwrote the other plan’s brief — the single gitignored source of task requirements, unrecoverable once clobbered.

Each workspace now records its owning plan in a plan-path marker (repo-relative in-repo, absolute outside). Lookup keeps basename slugs and existing behavior for the common case: a markerless workspace is adopted in place (no migration break for in-flight plans), a marker naming this plan is a match, and a marker naming a different plan disambiguates with the plan’s parent-directory name, then a counter. Plan paths are normalized (CDPATH-guarded physical cd) so relative, absolute, and ../ spellings of one plan share one workspace.

task-brief and review-package delegate to sdd-workspace and need no changes. SKILL.md’s workspace bullet no longer promises the exact path, since disambiguated workspaces differ.

Reported by @CRGDan; reproduction and test groundwork by @crisnahine in PR #2120.

Fixes #2045

feat: add native Muse support (multiprovider)

Add .muse-plugin/plugin.json (native Muse contract, 16 skills, SessionStart hook) and marketplace.json so the same repo now serves Muse alongside Claude Code, Codex, Cursor, Gemini, Pi, etc.

skills/using-superpowers/references/muse-tools.md: Muse tool mapping
skills/using-superpowers/SKILL.md: list Muse in Platform Adaptation
hooks/session-start: handle MUSE_PLUGIN_ROOT (SDK standard additionalContext) alongside CURSOR/CLAUDE/COPILOT branches
.version-bump.json: track .muse-plugin/plugin.json and marketplace
README.md: add Muse to TOC and Installation with muse plugins install instructions
AGENTS.md: convert symlink -> regular file copy to satisfy Muse validator (symlink entries rejected as installable)

Validated: muse plugins validate => valid:true (diagnostics=1 for expected multiple-manifests warning), all 16 skills validate true.

Co-Authored-By: Muse Spark

fix: Muse SessionStart hook must use nested hookSpecificOutput

muse-spark-1.3-contributor rejects top-level additionalContext on SessionStart (“unsupported additionalContext in output”). Switch Muse branch to Claude-style nested {hookSpecificOutput:{hookEventName, additionalContext}} which validates and injects correctly (tested via muse exec –provider meta hello world -> success, no hook failed).

Co-Authored-By: Muse Spark

docs: fix Muse README to include approve and correct install path

README previously showed muse plugins install ./.muse-plugin and muse marketplace add (missing plugins prefix) and omitted the required hooks approval step. Muse warns “hooks require review before activation” on install; fix to muse plugins install ./ + muse plugins approve superpowers per installed flow validated with muse-spark-1.3.

Co-Authored-By: Muse Spark

docs: expand Muse section to parity with other harnesses

Add clone+install variant, update command, restart/verification notes, and SessionStart hook detail to match Gemini/Pi/Hermes depth. Keeps same install path (muse plugins install ./ + approve) validated with muse-spark-1.3.

Co-Authored-By: Muse Spark

Add Claude Code platform reference: a nested orchestrator for cheaper subagent-driven development
docs(testing): describe the Quorum eval lab accurately, replacing stale Drill references

The evals harness was renamed Drill -> Quorum and rewritten from Python/uv to Bun/TypeScript; docs/testing.md and CLAUDE.md still described the old tool. Beyond the rename, the old text also misdescribed the system: quorum is the harness CLI, one part of the eval lab — it drives real coding-agent CLIs through a Gauntlet QA agent and grades against scenario acceptance criteria plus deterministic post-checks. The quick start now matches the eval repo’s actual commands (bun install / bun run quorum run scenarios/ –coding-agent claude; scenarios are directories, not *.yaml) and points at the Live Eval Risk section before anyone runs a permissive-mode session.

Drift reported in closed PR #2121 (@JFWaskin); that PR’s replacement quick start kept the uv commands, so this rewrite goes from the eval repo’s README instead.

Rebuild executing-plans as a first-class inline execution mode

A cheaper execution mode alongside subagent-driven development: the session implements every task itself under the same workspace, ledger and stopping rules, with one fresh whole-branch review on the most capable model at the end. Helper scripts task-start/task-done keep the ledger and test log honest; the final fix pass re-grades findings and fixes Critical/Important under TDD. writing-plans’ handoff, SDD’s when-to-use text and two README lines change to match.

Reviewer judges the spec as a vision document; plans list the five implied cases most likely to bite

code-reviewer.md: behavior the spec is silent on is graded by what a reasonable person using the software expects, and a ‘Declined to judge’ list makes every scoping decision visible. writing-plans: a Review Focus section names the five implied input classes or failure modes most likely to bite, each pinned by a test in the owning task. executing-plans hands the section to the final reviewer and rules on every declined line.

docs: replace duplicated agent guidelines with CLAUDE.md pointer
docs: make AGENTS.md the canonical contributor guidelines
test(opencode): cover canonical skill paths and registration survival
fix(opencode): retry unsuccessful child-session lookups
fix(opencode): retain bootstrap after native compaction
docs(opencode): describe supported V2 setup and bootstrap behavior
docs: clarify OpenCode V1 and V2 skill behavior
chore(opencode): mark test-skill-registration.sh executable

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

test(opencode): cover bootstrap placement when native compaction retains user messages

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

fix(opencode): strip quote pairs after joining multi-line frontmatter values

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

fix(scripts): exclude root index.js from the Codex plugin sync

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

docs(opencode): fix pin example, local-path examples, and V2 log troubleshooting

Restore the version-pin example for both config keys and state the V2 constraint (the pinned ref must include OpenCode V2 support). Replace the ~/... local-package examples with absolute paths: OpenCode does not expand ~, and a tilde entry is installed as a package spec rather than loaded as a directory. Point V2 troubleshooting at opencode run --standalone --print-logs, since plugin logs are server-role and hidden without --standalone. Describe where the bootstrap lands when native compaction retains user messages under the default keep budget.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

docs: draft release notes for v6.4.0 (#2327)
docs: draft release notes for v6.4.0
docs: tighten v6.4.0 release notes

Set the release date, add a lead paragraph, call out the removed batch checkpoints, unify the Native/inline naming, and replace internal jargon. Correct the TDD probe figure and the Claude Code nested-orchestrator opt-in to match #2110 and the reference doc.

Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B

docs: spell out movie skill dependencies in v6.4.0 notes

Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B

docs: note AGENTS.md as the canonical guidelines in v6.4.0 notes
docs: name new harnesses in v6.4.0 summary

Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B

docs: list OpenCode 2.0, Muse, and Qwen Code as new harnesses in v6.4.0

Move the Claude Code nested controller note under Subagent-Driven Development.

Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B

docs: reword v6.4.0 harness summary

Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B

test(movie): expect 8 frames from the slow-capture film test (#2329)

42486db made film() fill every grid slot before the endpoint, but this test kept its old count of 7. Its fake clock advances 0.01 s per capture and 0.02 s per sleep, so the prompt is seen at 1.01 s, the 0.4 s hold ends at 1.41 s, and slots 0.0-1.4 s make 8 frames. The test has failed on every run since 42486db.

chore: bump version to 6.4.0 (#2330)

Release engineering for 6.4.

Revert movie skill import (#2214) (#2335)

Remove the proving-it-works-with-a-movie import at Drew Ritter’s request because its code quality does not meet the release bar.

Reverts merge dd53fe0b57223bbbbb8ceae0bda2ba8a26d1c29a and the dependent movie test adjustment in 3979a17bda8691d72bfc5963e5437174c399db67. Remove the later Muse registration and update the unreleased notes so neither advertises the removed skill. Version changes are left for a separate release step.

docs(release-notes): retitle unreleased v6.4.0 notes as v6.4.1

v6.4.0 was prepared but never shipped (release PR #2331 closed unmerged, no tag). The next release is v6.4.1. Rename the section and open it with a note saying v6.4.0 never shipped and that v6.4.1 holds back the proving-it-works-with-a-movie skill for cleanup and robustness work before it returns. The note replaces the revert paragraph added in #2335. Version bumps are left for the release step.

Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B

chore: bump version to 6.4.1

v6.4.0 was never shipped; 6.4.1 is the first release with these changes. Points the OpenCode V2 pinning docs at v6.4.1, since no v6.4.0 tag will exist. Excludes the gitignored evals/ clone from the version audit, which was grepping all 11G of it and never finishing.

Claude-Session: https://claude.ai/code/session_01BJAzd3A26a2XKo1JUJWySu

docs: fix Muse table of contents indentation
Claude finally honors AGENTS.md, but only if a CLAUDE.md is not present
writing-plans: a plan is decisions, not a transcript (#2333)

Replace the No Placeholders prohibition list with a recipe for what a step contains (signature, test with assertions, spec values; a body only where those do not determine it); add a proportion item to the self-review; drop the time unit from the step rule; describe the reader as capable; delete the unreferenced plan reviewer prompt. Measured on two designs: plans halve under the recipe alone and reach a third of their size with the proportion item; every skill-written terse plan executed 9/9 on Sonnet 5.

docs(release-notes): draft v6.4.2 notes (#2382)
docs(release-notes): draft v6.4.2 notes

Claude-Session: https://claude.ai/code/session_012kGFECgxu6pk4fK2L3DjXd

docs(release-notes): soften v6.4.2 lead

Claude-Session: https://claude.ai/code/session_012kGFECgxu6pk4fK2L3DjXd

chore: bump version to 6.4.2

Points the OpenCode V2 pin examples at v6.4.2.

Claude-Session: https://claude.ai/code/session_012kGFECgxu6pk4fK2L3DjXd

Explain why session-start pipes printf through cat

Three open PRs (#2115, #2349, #2367) removed the | cat pipes as no-op subprocess spawns, which would bring back the Windows EPIPE diagnostic fixed in d72560e (#1612). Say so next to the code.

fix(brainstorming): preserve literal content replacement tokens (#2364)
docs(release-notes): brainstorming literal replacement tokens (#2364)
test(brainstorm-server): stop orphaning the server when a test fails

process.exit(1) ran inside the try, so the finally that kills the spawned server never ran. The leftover server held port 3334 and the next run died with ‘preferred port is in use’. Set process.exitCode instead so teardown runs.

fix(debugging): avoid printing identity secrets in diagnostics (#2380)
docs(release-notes): debugging example no longer prints secrets (#2380)
docs(release-notes): task-done records silently passing tasks (#2388)
fix(executing-plans): task-done no longer aborts when a passing test prints nothing (#2388)

Under set -euo pipefail, task-done extracted the ledger’s test-result field with:

last=$(grep -v '^[[:space:]]*
 "$log" | tail -n 1)

When the test command passes but the log is empty or blank-only, grep -v matches no lines and exits 1; pipefail propagates that through the pipeline, and set -e aborts the assignment before the ledger line is written. A passing task is then silently not recorded: exit 1, no stderr, no ledger entry — indistinguishable from the failure path the guard exists to produce.

Make the no-match case non-fatal, falling back to a literal placeholder for the ledger field:

last=$(grep -v '^[[:space:]]*
 "$log" | tail -n 1) || last="(no output)"

The failure guard above this line (recording nothing when the test command itself exits non-zero) is untouched.

Fixes #2385.

fix(hooks): make SessionStart hooks resolve without external PATH lookups (#2349)
fix(hooks): make SessionStart hooks resolve without external PATH lookups

SessionStart:startup hooks can run before Claude Code’s PATH is repaired (anthropics/claude-code#43127), or ahead of a sibling PATH-fixing hook in the same startup batch. hooks/session-start and the Unix half of hooks/run-hook.cmd both shelled out to dirname, cat, and a PATH lookup for bash itself, so an empty PATH made every SessionStart hook fail outright:

hooks/session-start: line 7: dirname: command not found hooks/session-start: line 44: cat: command not found

None of those external calls are necessary:

${0%/*} replaces$ (dirname “$0”) for both scripts.
$B A S H : - b a s h r e p l a c e s a b a r e^{'} b a s h^{'} i n r u n - h o o k . c m d^{'} s e x e c — b a s h a l w a y s s e t s$ BASH to its own absolute path once running, so no PATH lookup is needed to re-invoke it.
$(<file) (a bash builtin) replaces ‘cat file’ for reading the skill body.
The trailing ‘| cat’ after each printf branch was a no-op pass-through through another external binary; removed.

Adds a regression test in tests/hooks/test-session-start.sh that invokes both hooks under an empty PATH.

Fixes #2310.

Split $0 on / or \ so cmd-dispatched hooks find the plugin root

run-hook.cmd’s Windows half starts bash with a backslash path (C:...\hooks\session-start). ${0%/*} found no slash there, so session-start resolved the wrong plugin root and injected ‘Error reading using-superpowers skill’ instead of the skill. MSYS dirname handled backslashes, so dev was fine. Seen on Windows 11 + Git Bash 5.2.37 via cmd /c run-hook.cmd session-start.

Co-authored-by: Jesse Vincent jesse@primeradiant.com

docs(release-notes): SessionStart with a broken PATH (#2349)
fix(requesting-code-review): avoid positional argument substitution (#2361)
docs(release-notes): code-review base SHA survives skill arguments (#2361)
fix(hooks): run-hook.cmd finds per-user Git, skips WSL launchers and the current directory, keeps exit codes (#2393)

Combines and supersedes #1864 and #2365. Fixes #1863.

Co-authored-by: citizen204 161211652+citizen204@users.noreply.github.com Co-authored-by: KaiyiQuan 156817180+KaiyiQuan@users.noreply.github.com

docs(release-notes): Windows run-hook.cmd discovery and exit codes (#2393)
docs(release-notes): tidy Hooks list
sdd-workspace: leave an existing .superpowers/sdd/.gitignore alone (#2399)

Based on #2161. Also quotes the empty CDPATH so shellcheck passes (SC1007).

Co-authored-by: aruizcu1989 192807317+aruizcu1989@users.noreply.github.com

docs(release-notes): sdd-workspace keeps an existing .gitignore (#2399)
test(brainstorm-server): run shell helpers without a login shell

The lifecycle tests ran their helpers with bash -lc, so anything a login profile prints landed in captured output (a path from mktemp, the newest session dir) and broke the test. Plain bash -c keeps the helpers independent of the user’s shell setup. Fixes #2190.

From #2192 by @tugrulguner.

Co-authored-by: tugrulguner 47668043+tugrulguner@users.noreply.github.com

test(sdd-workspace): compare physical paths so the suite passes on Git Bash

On Windows, git rev-parse –show-toplevel prints C:/Users/… while the script (and pwd) print /tmp/…, so nine assertions compared two spellings of the same directory and failed. The script itself was correct. Normalize the expected paths the same way the script’s output is produced.

From #2149 by @t0domanh.

Co-authored-by: t0domanh 3890425+t0domanh@users.noreply.github.com

sdd-workspace: resolve the repo root physically so plan markers stay repo-relative on Git Bash

git rev-parse –show-toplevel prints C:/Users/… on Windows while the plan path comes from pwd -P (/c/Users/… or /tmp/…), so the repo-relative check never matched and every marker held an absolute, machine-specific path. Found while landing #2149’s test fix on Windows.

test(executing-plans): compare the brief path in the scripts’ own spelling on Git Bash
docs(release-notes): plan markers stay repo-relative on Windows
fix(hermes): pass each skill’s frontmatter description to register_skill

Hermes lists plugin skills (skills_list) with the description given to register_skill, which defaults to “”. The plugin registered only a name and path, so all fourteen superpowers skills appeared with blank descriptions and the model had nothing to choose on. Read each SKILL.md’s description and pass it through.

From #2284 by @pepijn-blom.

Co-authored-by: pepijn-blom 322216308+pepijn-blom@users.noreply.github.com

docs(release-notes): Hermes skill descriptions (#2284)
brainstorming: rebuild around drawing out intent (#2463)
docs: intent doc for brainstorming rebuild

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

docs: spike exemption to the brainstorming gate

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: rebuild around drawing out intent

Replaces the spike/bounded/architectural router with an intent-first conversation: open describing questions, recon offers, playback in 200-300 word chunks, then sizing (quick task / small change / project with a written design). The spec reviewer prompt becomes a builder check that asks what a builder would still need to know.

Adds tests/brainstorming/first-turn.sh, a first-turn micro-test with no-skill and skill arms.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

tests: multi-turn brainstorming driver with simulated humans

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

tests: harder small-change scenario; clearer launch failure

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: tighter opening, wait for builder check, reason from the why

Round 1 multi-turn runs: the builder check went to a background subagent and stalled the conversation; the opening restated the request; one run proposed CLI flags after hearing the tool runs from cron.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: builder check gates the handoff, not the reply; README

Claude Code subagents run in the background, so the subject can’t block on the builder check. The skill now says what matters (don’t hand over the document until the check is back), and converse.sh lets the simulated human wait for the subject’s follow-up turn instead of nudging it. Also fixes converse.sh dying before its summary when the work dir has no commits.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: split multi-project requests and take them one at a time

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: show it when the playback describes something visual

Across 13 multi-turn runs neither skill ever offered the visual companion, even for a kids’ tablet screen. Tying the offer to an observable moment (talk turns to how something looks, or a playback chunk describes it) got offers in 2/3 runs, each as its own message, none upfront. The simulated human now declines browser offers so test runs don’t open tabs.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

tests: opt-out, spike, and multi-project brainstorming scenarios

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: resolve review findings from adversarial pass

Opt-out ends the skill and the gate with it (the gate had no rule for it).
Each message ends with one question, no example answers hanging off it; multi-question messages and parenthetical menus showed up in most runs.
Playback marks the agent’s guesses as guesses; one run played the agent’s own example back as the human’s.
Restore the old gate’s list of what counts as building (#2258).
Companion offer stays its own message; mockups only after acceptance.
converse.sh: survive a failed human turn, report why a run ended, and keep raw task notifications out of the simulated human’s view.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: play back as you go, alternating with questions

With playback saved for the end, project brainstorms ran 8-15 questions before the human saw any summary. Interleaved, the first playback lands around turn 3-6 (6 runs: habit-tracker, pottery, offsite x2), so corrections arrive before more questions build on a wrong guess. Total length is about the same.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

tests: blind-pair launcher for comparing brainstorming versions

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: builder check yields one ranked round of questions

In a blind comparison (6 testers, old vs new skill), every new-skill tester flagged the builder check: two rounds and 3-9 questions after they’d said ‘write it up’. Now the agent warns once that a reviewer reads first, settles minor gaps itself and marks them as its calls, and brings only the questions that change what gets built, in one message, most important first. 4/4 runs (habit-tracker, pottery x2) showed a single round.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

docs: brainstorming rebuild eval results

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

Move the eval harness and results to their own PR

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: one line on writing style

Blind testers flagged a researched answer as a wall of text for a non-technical person. Micro-tested 12 style lines on research reports and mid-conversation answers (3 prompts x 5 reps each). Every variant already led with the point; naming a journalist (wire reporter, Mossberg, a Journalism BA) added source attributions. Plain wording shortened research reports by about 12% against no line.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: offer the visual companion whenever seeing would help

Lists the moments that call for it (things they’ll look at, layouts, flows, options that look different, diagrams/timelines/maps), checks each playback chunk before sending it, and drops the ‘token-intensive’ line that confused non-technical blind testers. Offers: habit tracker 3/3 (was ~50%), pottery booking 3/3 (was 0/3), at turns 3-7, never upfront; 0/4 on scenarios with nothing visual (sync-tool flag, talk outline).

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: plain style line

Tested five style lines across Opus, Sonnet, gpt-6-luna and gpt-6-astra (3 prompts x 5 reps each); none moved length or attribution beyond noise on any model. Keep the plainest statement of intent.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

brainstorming: report the most important findings, offer the rest

Research reports to a non-technical person ran 320-400 words on Claude. With this line, replies that offer the rest rose from 1/5 to 4/5 (Opus) and 3/5 (Sonnet); Opus reports ~7% shorter; gpt-6-luna/astra, already ~170-190 words, unchanged.

Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK

feat(antigravity): native plugin manifest for the Antigravity Marketplace

Add .antigravity-plugin/plugin.json with the Marketplace fields (displayName, logo, suggestedPrompts, version, author), a logo rendered from the Superpowers mark by scripts/render-antigravity-logo.sh, and a .version-bump.json entry. The Codex sync excludes the manifest and logo.

With the native manifest, agy installs Superpowers as an Antigravity plugin. Before, agy plugin install <repo> fell back to importing the repo as a Gemini CLI extension and rejected the copied Claude-format hooks file on every session.

Superpowers bootstraps through skill discovery: agy lists each installed skill’s description, and using-superpowers’ “Use when starting any conversation” gets the model to load it. agy has no session-start hook event; a rules/ file would also load in Cursor, which reads plugin rules from the same repo root; a PreInvocation hook runs on every model call. Verified on agy 1.3.1 (Gemini 3.8 Flash) across 15 clean sessions: brainstorming or systematic-debugging loads before any code.

docs(porting): correct Antigravity guidance

The guide described an .antigravity-plugin/install.sh and a generated ANTIGRAVITY.md that never existed. Antigravity now bootstraps through the surfaced skill index. Record what probing agy 1.3.1 found: no session-start hook event, PreInvocation hooks run before every model call, ephemeral messages are dropped on the next call, ${PLUGIN_ROOT} is not set in hooks, hooks.json and rules/ cannot be relocated, and a rules/ file in a shared plugin root also loads in Cursor.

brainstorming: find out which choices about how it gets made they want to own (#2482)
brainstorming: ask which technology choices they want to make

A session asked to design an iOS app never discussed platform or stack and built a web app with a home-screen icon. Brainstorming now finds out early which technology choices the person wants to make and which they’re handing over: talk it through with a technical partner, pick sensible defaults and say them plainly for someone who isn’t, and base defaults on an existing project’s stack. The Red Flags row on sensible defaults now says to state them rather than avoid them.

brainstorming: generalize technology guidance to how it gets made

Non-software projects (a painting, a cake) need the same move: find out which medium, tools, materials and resources they want to choose, which they’re handing over, and what they already have. Software keeps its examples: platform, programming language, libraries.

brainstorming: close the skip-path gap in #2482’s defaults rule (#2483)
brainstorming: close the skip-path gap in #2482’s defaults rule

The opt-out line in Your First Message let a user skip the whole skill, including #2482’s rule that stated defaults get said out loud. On the skip path, state any significant how-it-gets-made choice (platform, language, medium) in one plain line before building.

2482 also added a How it gets made paragraph that restates the

existing which parts of the how they want to decide bullet in Ground to cover almost word for word. Drop the redundant bullet: the paragraph already covers that ground, plus the genuinely new instructions (state defaults plainly, build on what they already have, record your own calls as yours and never as agreed, strong-views users talk it through while users counting on you get defaults).

brainstorming: use parentheses instead of emdashes in the skip-path line

Co-authored-by: Jesse Vincent jesse@fsck.com

Release prep for v7.0.0 (#2488)

RELEASE-NOTES.md: v7.0.0 section covering everything on dev since v6.4.2, led by the brainstorming rebuild (#2463, #2482, #2483)
Bump all 11 declared manifests to 7.0.0; OpenCode pin examples point at #v7.0.0
bump-version.sh –audit matches whole version strings only, so 7.0.0 no longer matches inside 127.0.0.1
test-render-graphs.sh resolves the real node binary so its empty-PATH case works under version-manager shims (mise, asdf)

brainstorming: look first, and only offer to skip when it fired on its own

In 7.0.0 every brainstorming session opened with the same two lines: an offer to skip the questions and an open ‘tell me about the moment’ question (#2530). It fired even when the user had asked for brainstorming by name, had a spec or plan in hand, or had already said what and why, and it asked before looking at the project.

Now, in an existing project or with context the user supplied, the agent reads what they referred to before its first message. The skip offer only appears when the skill fired on its own. When what and why are already established, the agent plays back its understanding and asks what’s wrong or missing, since specs are often incomplete; otherwise it still opens with one question that gets them describing.

tests/brainstorming-first-message/run.py runs the opening turn of three evals scenarios in headless Claude Code (Opus 5.5, isolated HOME). Against 7.0.0, 5 reps each: skip offer 15/15 including both explicit requests, no code read before asking on the explicit request 5/5, playback 0/10. With this change: skip offer 0/10 on explicit requests and 5/5 when auto- triggered; recon and a grounded playback 10/10 on the explicit and phased-spec scenarios.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: keep the playback short and end on a design question

Two transcript reviews of the first round found the playback ran 243-347 words, mostly reciting the request or spec back, and 3 of 5 explicit requests still closed on a why question because the branch was keyed on ‘said what and why’. The branch now keys on what they want, caps the playback at 150 words of findings and guesses, and ends by inviting corrections and asking the open design choice that most changes what gets built.

Opus 5.5, 5 reps each: replies 154-216 words, corrections invited 10/10, design question 8/10 (two explicit-request reps still ask ‘the last time you wished you had this’), auto-trigger check-in 5/5.

The first-message harness now runs Codex too (plugin staged as superpowers@debug under an isolated CODEX_HOME, as the evals do) and puts the agent and model in the results directory name.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: key the skip offer on the user’s message and spell out the playback ending

A cross-model run (Sonnet 5.5, Haiku 5.5, Fable 5.1, Codex gpt-6-luna and gpt-6-astra) and two transcript reviews found three wording gaps:

Claude models ignored the 150-word cap by listing every guess. The cap now covers the whole message and the playback carries the two or three guesses that matter most.
‘Invite corrections and ask one question’ got half-followed: Codex dropped the invitation, Claude added a second question. It’s now one line inviting corrections, then one question.
‘Fired on its own’ doesn’t map to Codex, where every skill load is the agent’s own read of SKILL.md; Luna dropped the check-in once. The skip offer now keys on whether the user’s message asked for brainstorming or a design discussion.

3 reps each on Opus 5.5, Sonnet 5.5, gpt-6-luna, gpt-6-astra: no skip offer on explicit or phased requests (24/24), check-in when the user didn’t ask (12/12), recon before asking (24/24). Playback lengths: Sonnet 124-161, Opus 141-204, Codex 57-116 words. Astra now invites corrections 6/6 (was 0/6).

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: recommend a way to build it and name the alternatives considered

Jesse wants brainstorming to propose an approach and reference the alternatives it weighed, because models reason better when they have to think through real alternatives before picking one. ‘Think wide privately’ becomes ‘Think wide, then recommend’: propose the recommended approach, name the alternatives and their trade-offs, and offer to dig into them. It stays scoped to how it gets built; what they want still starts with them describing. In the first-message playback, a guess about how to build it becomes that recommendation.

Before, 0/8 branch playbacks on alexxburg’s #2530 prompt named any alternative. After, 3 reps each across four scenarios: Opus and Sonnet name alternatives in 18/18 playbacks, gpt-6-astra in 5/9. Claude playbacks grew to 148-211 words.

The first-message harness gains detailed-new-project (alexxburg’s prompt in an empty repo). On v7.0.0 Opus and Sonnet asked ‘the moment you’d use this’ or ‘what happens with the PNG’ 6/6; the branch plays back and asks about the jobs table and what ‘live’ means 6/6.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: alternatives only for real forks, checked against the project

Transcript reviews of the first alternatives round found strawman alternatives (‘Node or Go, neither makes it smaller’), an offer to dig in in only 2/27 playbacks, and 6/6 Claude explicit-request reps recommending a transaction rollback that the fixture’s own commit() and file-creating connect() break. Alternatives are now for forks you’d genuinely hesitate between, with obvious defaults stated in a clause; picks get checked against what the project does; and the first-message bullet itself carries the one-clause alternative and the offer to dig in.

3 reps each, Opus and Sonnet: offer to dig in 6/18 (was 2/18); read-only plus seen-set picked 2/6 on explicit-request (was 0/6); Claude playbacks still 161-241 words.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: move the check-in to a light closing offer, cap at 200 words

Jesse’s calls on the third review round:

The playback cap goes to 200 words, since naming real alternatives needs the room.
The skip offer moves from the opening line to a light one-line offer after the question (‘Or if you’d rather I just dive in, say so.’), and how the message ends now has a positive branch for each case. With only a closing conditional, 5/12 Claude reps on explicit requests picked up the offer; with both branches spelled out, 0/12, while 12/12 reps where the user didn’t ask for brainstorming still get it.
‘You never need to quote this skill to your human partner.’ Astra had quoted the skill at the user in 3/12 runs; 0/34 after.

Opus and Sonnet, 3 reps each across four scenarios. Claude playbacks run 183-284 words, so the 200 cap is a target more than a limit. Astra was not rerun on the final wording: the Codex subscription returned 429 on every call.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: reflow the playback bullet

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: make 200 words a target to aim for, not a limit

Jesse’s call. 3 reps each on explicit-request, phased-spec and detailed-new-project: Opus 223-261 words (was 183-237 with ‘stays under’), Sonnet 245-357 (was 179-284). One question per reply and the closing offer placement are unchanged.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

Move the first-message harness to superpowers-evals

Skill-behavior evals live in superpowers-evals; tests/ is for plugin infrastructure. The harness is now quick-evals/brainstorming/first-message.py in prime-radiant-inc/superpowers-evals#73.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

Templates: require a human-written summary and the filer’s instructions

Agent-filed issues and PRs arrive with no human fingerprint and no record of what the agent was told to do. The three issue templates now carry, right after the duplicate-search checkbox, a “Who’s filing” section asking who the filer is and what their human partner asked for, and a “Human-authored summary” under 200 words that a human writes in their own words. The PR template gets the same summary and a line for the partner’s instructions under its existing “Who is submitting” table. The bug report also asks how the “does not reproduce without Superpowers” checkbox was verified.

The PR template, AGENTS.md, and the README now say agent-written PRs that fix issues filed by someone else are not accepted unless a maintainer asked for one, including when the partner hit the same problem: the report goes on the existing issue instead. AGENTS.md previously told agents to “pick ONE issue” from the tracker, which invited exactly that.

The Session Diagnosis Report issue template is removed. The diagnosing-superpowers skill supplies its own issue body, which replaces the template body except in the oversize-URL fallback, so the template’s only lasting effect was applying the automated-issue-report label for reporters without push access. The skill’s prefilled link now lands on bug_report.md, and the skill’s footer still marks skill-filed issues.

The skill’s own issue template carries the same two sections, since the repo template never reached skill-filed issues. “Who’s filing” names the filing session’s model and harness and quotes the request from that session, because the diagnosed session’s first prompt already appears under steps to reproduce and may come from another harness; the footer says which section holds which. The summary slot is reserved for the partner’s own words, with a trim request rather than an edit when they run long, and the approval gate in SKILL.md refuses to file while that slot holds a placeholder. The fixed “reporter has not tried reproducing” sentence becomes the template’s “How I verified” line, with the box ticked only when a transcript shows the problem did not recur. The design spec’s issue-filing section follows.

Checked with fresh Sonnet agents filling the skill template from a synthetic diagnosis: eleven runs over three drafts, three on the final wording with the amended gate in context. Of the four told by their partner to skip the write-up or file overnight, none drafted the summary and none filed. On the final wording, the filer’s model and the diagnosed Codex session’s model landed in the right sections, a partner’s untranscribed account of a run without Superpowers was recorded with the box left unticked, and a 216-word summary drew a request to trim rather than an edit.

Also along for the ride: the feature request’s chooser text says “improvement” instead of “addition”, and the PR template’s test table heading is plural.

Claude-Session: https://claude.ai/code/session_01TfpSRkih629AUwvFyTFr9c

executing-plans: drop the Example Workflow so SKILL.md fits under the compaction cut (#2563)

After a compaction, Claude Code re-attaches each invoked skill truncated to 20,000 characters (#2481). executing-plans was 20,405 bytes, so its last lines fell past the cut. The Example Workflow was the redundant part: it replayed rules the sections above already state (task-start/task-done, rulings in the ledger, re-grading, the single fix pass, the final message’s two lists). SKILL.md is now 18,103 bytes.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

writing-skills: move supporting docs and situational guidance into references/ (#2564)
writing-skills: move supporting docs into references/

The repo keeps a skill’s on-demand docs in references/ (using-superpowers, diagnosing-superpowers, subagent-driven-development). writing-skills had anthropic-best-practices.md, persuasion-principles.md, testing-skills-with-subagents.md, graphviz-conventions.dot and examples/CLAUDE_MD_TESTING.md at the skill root; they move unchanged except for the links between them. render-graphs.js is a tool and stays.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

writing-skills: move situational guidance to references/ so SKILL.md fits under the compaction cut

After a compaction, Claude Code re-attaches each invoked skill truncated to 20,000 characters (#2481). writing-skills was 26,623 bytes. Guidance it only needs at particular moments now lives in references/, behind a pointer at the moment that needs it:

discovery.md: the SKILL.md template and all of Skill Discovery Optimization (description, keywords, naming, token budgets, cross-references). Read when writing or changing frontmatter, naming, or size. The rule agents break most, that a description names triggering conditions and never the workflow, stays in SKILL.md too.
bulletproofing.md: closing loopholes, spirit vs letter, the rationalization table and red flags. Read when the baseline failure is a discipline failure, as Match the Form to the Failure already scopes it.
flowcharts.md: when a flowchart earns its place, conventions, rendering.

SKILL.md is now 16,738 bytes. quick-evals/writing-skills/write-a-skill.py (superpowers-evals) has each rep write a new skill from supplied baseline results. Opus 5.5, 3 reps per scenario, v7.0.0 vs this change: every written skill has a ‘Use when’ description with no workflow summary (124-248 chars), and every discipline skill tables all five baseline rationalizations and has a red-flags section, on both arms. On this change every rep read the reference its scenario calls for (6/6).

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

subagent-driven-development: move situational content to references/ so SKILL.md survives compaction (#2565)

After a compaction, Claude Code re-attaches each invoked skill truncated to 20,000 characters (#2481). SDD was 32,358, so everything from the fix loop on (the five-round cap, the breaker, the ledger round line, the final review’s single fix wave, Finish) was gone for the rest of a long session. One reported task ran 18 fix rounds after that.

Content SDD only needs at particular moments now lives in references/, behind a pointer at the step that needs it: fix-loop.md (read before every round), final-review.md (with Finish), handling-reports.md (non-DONE statuses), resuming.md (an existing ledger), preflight.md (the conflict scan before Task 1), batching.md, and cannot-verify.md. Those reads come fresh from disk, so they don’t depend on what survived compaction. The Process graph shows the fix loop and final review as pointer nodes, and the illustrative Example Workflow is gone. SKILL.md is 19,506 bytes.

tests/skill-size/test-skill-size.sh fails when any SKILL.md reaches 20,000 bytes. It still fails for writing-skills and executing-plans.

Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F

brainstorming: lay out approaches, write a design doc at every size, and never skip without consent (#2530) (#2571)

Follow-up to #2560. Users on #2530 reported that brainstorming still skips approaches and the spec and jumps to implementation. Against dev (which includes #2560), the gallery scenario reproduced it: the design doc was skipped without consent in 24 of 24 runs.

A checklist before implementing: approaches in their own message and a pick, the design doc, its approval, then writing-plans. A spike they agreed to and an explicit opt-out aren’t implementing.
Every size gets a design doc; a small change gets a short one covering what was already discussed. Each doc has an Approaches part.
For a detailed request, the first message echoes it back, flags anything they may not have considered that changes it, and leaves the how for later.
Questions are specific and Socratic and say why they’re asked.
Red flags for writing the doc before the approaches and for treating an unwritten doc as approved.

Remove historical planning docs
docs(release-notes): draft v7.0.1 notes
chore: bump version to 7.0.1
test(brainstorm-server): wait for file events instead of sleeping

On macOS, fs.watch (FSEvents) delivered events anywhere from ~100ms to 2.4s after the write on Node 26.10 / Darwin 27, and sometimes held an event back to deliver it in a batch with a later one. The file-watching tests slept a fixed 500ms, so they failed when an event came late, and a late event from one test could trigger a reload or clear state/events during another. Six tests failed on v7.0.0 and on dev, a different six each run.

The tests now poll for the outcome with a 5s timeout, wait until the server logs the exact screen event they caused, and drain in-flight events with a barrier file before asserting that nothing reloaded or that state/events survived. 15 consecutive runs pass; dropping the server’s .html/dotfile filter still fails both negative tests.

Superpowers

Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.

How it works
Commercial Services
Getting Started
- Claude Code
- Antigravity
- Codex App
- Codex CLI
- Cursor
- Devin CLI
- Factory Droid
- Gemini CLI
- GitHub Copilot CLI
- Grok Build CLI
- Kimi Code
- OpenCode
- Pi
- Qwen Code
- Hermes Agent
- Muse
The Basic Workflow
When Something Goes Wrong
Community
What’s Inside
Philosophy
Contributing
Updating
License
Visual companion telemetry

How it works

It starts from the moment you fire up your coding agent. As soon as it sees that you’re building something, it doesn’t just jump into trying to write code. Instead, it steps back and asks you what you’re really trying to do.

Once it’s teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.

After you’ve signed off on the design, your agent puts together an implementation plan that’s clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren’t Gonna Need It), and DRY.

Next up, once you say “go”, it launches a subagent-driven-development process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It’s not uncommon for your agent to work autonomously for a couple hours at a time without deviating from the plan you put together.

There’s a bunch more to it, but that’s the core of the system. And because the skills trigger automatically, you don’t need to do anything special. Your coding agent just has Superpowers.

Commercial Services

If you’re using Superpowers in enterprise and could benefit from commercial support, additional tooling, or managed spending, please don’t hesitate to drop us a line at sales@primeradiant.com.

Installation

Installation differs by harness. If you use more than one, install Superpowers separately for each one.

Claude Code

Superpowers is available via the official Claude plugin marketplace

Official Marketplace

Install the plugin from Anthropic’s official marketplace:
```
/plugin install superpowers@claude-plugins-official
```

Superpowers Marketplace

The Superpowers marketplace provides Superpowers and some other related plugins for Claude Code.

/plugin marketplace add obra/superpowers-marketplace

Install the plugin from this marketplace:

/plugin install superpowers@superpowers-marketplace

Antigravity

Install Superpowers as a plugin from this repository:

agy plugin install https://github.com/obra/superpowers

Antigravity lists each installed skill’s description, and the description of the using-superpowers skill prompts the model to load that skill at the start of a conversation. Reinstall with the same command to update.

Codex App

Superpowers is available via the official Codex plugin marketplace.

In the Codex app, click on Plugins in the sidebar.
You should see Superpowers in the Coding section.
Click the + next to Superpowers and follow the prompts.

Codex CLI

Superpowers is available via the official Codex plugin marketplace.

Open the plugin search interface:
```
/plugins
```
Search for Superpowers:
```
superpowers
```
Select Install Plugin.

Cursor

In Cursor Agent chat, install from marketplace:
```
/add-plugin superpowers
```
Or search for “superpowers” in the plugin marketplace.

Devin CLI

Install the plugin from this repository:
```
devin plugins install obra/superpowers
```
Update to the latest version with:
```
devin plugins update superpowers
```

Factory Droid

droid plugin marketplace add https://github.com/obra/superpowers

Install the plugin:

droid plugin install superpowers@superpowers

Gemini CLI

Install the extension:

gemini extensions install https://github.com/obra/superpowers

Update later:
```
gemini extensions update superpowers
```

GitHub Copilot CLI

copilot plugin marketplace add obra/superpowers-marketplace

Install the plugin:

copilot plugin install superpowers@superpowers-marketplace

Grok Build CLI

Superpowers is available via the official Grok plugin marketplace.

Install the plugin from xAI’s official marketplace:
```
grok plugin install superpowers@xai-official --trust
```
Or open the marketplace in the TUI, search for Superpowers, and install it:
```
/marketplace
```

Kimi Code

Superpowers is available in Kimi Code’s plugin marketplace.

Open Kimi Code’s plugin manager:
```
/plugins
```
Go to Marketplace > Superpowers and install it.

Or install directly from this repository:

/plugins install https://github.com/obra/superpowers

Detailed docs: docs/README.kimi.md

OpenCode

OpenCode uses its own plugin install; install Superpowers separately even if you already use it in another harness.

Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Detailed docs: docs/README.opencode.md

Pi

Install Superpowers as a Pi package from this repository:

pi install git:github.com/obra/superpowers

For local development, run Pi with this checkout loaded as a temporary package:

pi -e /path/to/superpowers

The Pi package loads the Superpowers skills and a small extension that injects the using-superpowers bootstrap at session startup and again after compaction. Pi has native skills, so no compatibility Skill tool is required. Subagent and task-list tools remain optional Pi companion packages.

Qwen Code

Qwen Code installs plugins from Claude Code marketplaces directly.

Install the plugin from this repository, and pick superpowers when prompted:
```
qwen extensions install obra/superpowers
```
Update later:
```
qwen extensions update superpowers
```

Hermes Agent

Install Superpowers as a Hermes plugin from this repository:

hermes plugins install obra/superpowers --enable

Restart any active Hermes sessions after installing. Note: Hermes has no post-compaction hook, so a very long session that compacts over its first turn loses the bootstrap — start a fresh session if skills stop triggering.

Muse

Superpowers is available as a native Muse plugin — same repo, same skills, all harnesses. The using-superpowers bootstrap is injected via the native SessionStart hook alongside Claude Code, Codex, Cursor, Gemini, Pi, and the rest — no per-session opt-in.

Install from a local checkout:

muse plugins install ./
muse plugins approve superpowers

Or clone and install:

git clone https://github.com/obra/superpowers.git
muse plugins install ./superpowers
muse plugins approve superpowers

Update later:
```
muse plugins update superpowers
```

Restart any active Muse sessions after installing so the SessionStart hook takes effect — skills are active immediately, hooks require approval on first install. To verify, start a fresh session and send Let's make a react todo list — a working install auto-triggers brainstorming before any code is written. Version is tracked in .version-bump.json so scripts/bump-version.sh keeps it in sync.

The Basic Workflow

brainstorming - Activates before building anything. Draws out what you actually want, and why, through questions that get you describing it, then plays its understanding back for correction. Small changes get agreed in chat; projects get a written design document a builder could plan from.
using-git-worktrees - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
writing-plans - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
subagent-driven-development or executing-plans - Activates with plan. Either dispatches a fresh subagent per task with a review after each (most thorough), or implements every task inline in the current session with one fresh review of the whole branch at the end (cheapest).
test-driven-development - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
requesting-code-review - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
finishing-a-development-branch - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.

The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.

When Something Goes Wrong

Sometimes a session misbehaves: a skill fires when it shouldn’t, stays silent when it should, or the agent ignores its plan, repeats work, or burns more tokens than you’d expect. Ask your coding agent to “figure out what went wrong with superpowers in this session” and it will invoke the diagnosing-superpowers skill. To examine an earlier session, name it: “figure out what went wrong with superpowers in session <id>“.

The skill reads the session transcript, reports what happened with line-level evidence, and, if you want, packages a scrubbed bundle for a bug report.

Community

Superpowers is built by Jesse Vincent and the rest of the folks at Prime Radiant.

Discord: Join us for community support, questions, and sharing what you’re building with Superpowers
Issues: https://github.com/obra/superpowers/issues
Release announcements: Sign up to get notified about new versions

What’s Inside

Skills Library

Testing

test-driven-development - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

Debugging

systematic-debugging - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
verification-before-completion - Ensure it’s actually fixed
diagnosing-superpowers - Work out what went wrong in a session, with evidence; export a scrubbed bundle or file an issue

Collaboration

brainstorming - Drawing out intent before building
writing-plans - Detailed implementation plans
executing-plans - Inline plan execution: one context, one final review
dispatching-parallel-agents - Concurrent subagent workflows
requesting-code-review - Pre-review checklist
receiving-code-review - Responding to feedback
using-git-worktrees - Parallel development branches
finishing-a-development-branch - Merge/PR decision workflow
subagent-driven-development - Fast iteration with two-stage review (spec compliance, then code quality)

Meta

writing-skills - Create new skills following best practices (includes testing methodology)
using-superpowers - Introduction to the skills system

Philosophy

Test-Driven Development - Write tests first, always
Systematic over ad-hoc - Process over guessing
Complexity reduction - Simplicity as primary goal
Evidence over claims - Verify before declaring success

Read the original release announcement.

Contributing

The general contribution process for Superpowers is below. Keep in mind that we don’t generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support. We also don’t accept agent-written PRs that fix issues filed by someone else unless a maintainer asked for one, even when you hit the same problem; add your report to the existing issue instead.

Fork the repository
Switch to the ‘dev’ branch
Create a branch for your work
Follow the writing-skills skill for creating and testing new and modified skills
Submit a PR, filling in every section of the pull request template, including the summary a human writes in their own words.

Skill-behavior tests use the drill eval harness from superpowers-evals, cloned into evals/ — see evals/README.md for setup. Plugin-infrastructure tests live at tests/ and run via the relevant run-*.sh or npm test.

See skills/writing-skills/SKILL.md for the complete guide.

Updating

Superpowers updates are somewhat coding-agent dependent, but are often automatic.

License

MIT License - see LICENSE file for details

Visual companion telemetry

Because skills and plugins don’t provide any feedback to creators, we have no idea how many of you are using Superpowers. By default, the Prime Radiant logo on brainstorming’s optional visual companion feature is loaded from our website. It includes the version of Superpowers in use. It does not include any details about your project, prompt, or coding agent. We don’t see your clicks or anything about what you’re building. This helps us have a rough idea of how many folks are using Superpowers and which version of Superpowers they’re using. It’s 100% optional. To disable this, set the environment variable SUPERPOWERS_DISABLE_TELEMETRY to any true value. Superpowers also honors Claude Code’s DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC opt-outs.

2160 behavior unchanged

2482 also added a How it gets made paragraph that restates the

Superpowers

Table of Contents

How it works

Commercial Services

Installation

Claude Code

Official Marketplace

Superpowers Marketplace

Antigravity

Codex App

Codex CLI

Cursor

Devin CLI

Factory Droid

Gemini CLI

GitHub Copilot CLI

Grok Build CLI

Kimi Code

OpenCode

Pi

Qwen Code

Hermes Agent

Muse

The Basic Workflow

When Something Goes Wrong

Community

What’s Inside

Skills Library

Philosophy

Contributing

Updating

License

Visual companion telemetry