summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJesse Vincent <jesse@primeradiant.com>2026-10-09 17:28:04 -0700
committerGitHub <noreply@github.com>2026-10-09 17:28:04 -0700
commitbb92a77741419a4ab5f06e711a283343f1ada0c3 (patch)
tree4ac675daa3415bc836f707c7e60237ac7b66c7d5
parent8ca22dba9a94f28898bbce59f2537ff4d87c747d (diff)
Release v7.0.0: rebuilt brainstorming, Antigravity Marketplace manifest, Windows hook fixes (#2489)v7.0.0
* refactor(skills): fold TDD Why Order Matters rebuttals into rationalization table The eval verdict on this cut: deleting Why Order Matters and trusting the compressed one-line table rows measurably degrades test-first behavior under the exact pressure the section rebutted ("just write it, tests after") — control 8/10 → treatment 5/10 at n=10, corroborated on both Claude and Codex. Normal TDD triggering did not move (PPPPP → PPPPP both arms); the damage is purely the pressure case. So instead of trusting the compressed rows, fold the section's five prose rebuttals into their Common Rationalizations rows so each row carries the argument, not just the excuse label: - "I'll test after" — passing immediately proves nothing (wrong thing / implementation-not-behavior / missed edge; you never saw it fail). - "Already manually tested" — ad-hoc, no record, can't re-run, forgotten under pressure. - "Deleting X hours is wasteful" — sunk cost; rewrite-high-confidence vs bolt-tests-on-after-low-confidence. - "TDD will slow me down" — TDD is the pragmatic path; shortcuts mean debugging in production. - "Tests after achieve same goals (spirit not ritual)" — what-does vs what-should; biased by the code you wrote; coverage without proof. Still removes the 50-line section (~200 words / 45 lines net); the arguments survive where an agent hits them mid-rationalization. Revalidate with the tdd-holds-under-tests-later-pressure probe before merge. * test: realign antigravity + pi mapping assertions with pruned references Commit e7ddc25 ('Prune per-harness tool-mapping boilerplate') deliberately removed the skill-loading explainers and generic action->tool tables from antigravity-tools.md and pi-tools.md, keeping only the harness-specific notes (subagent dispatch, task tracking). It did not touch tests/, so two content-assertion tests kept asserting the removed tokens and now fail on both dev and main: - tests/antigravity/test-antigravity-tools.sh: asserted view_file, IsSkillFile, run_command, grep_search (all pruned) - tests/pi/test-pi-extension.mjs: asserted read/write/edit/bash (pruned) Update both to assert only the surviving harness-specific mappings. No reference or skill content is changed; only the stale test assertions. * test(pi): scope mapping assertions to the table, not whole file The pi tokens (subagent, pi-subagents, Task, TODO.md) also appear in the surrounding prose, so matching the whole file passed even with the mapping table deleted — the exact regression this test exists to catch. Filter to table rows (lines starting with '|') so the assertion fails when the table is gone and passes on dev. Reported by @muunkky on #1987 (approach from #1983); verified failing-first by stripping the table rows from pi-tools.md. * docs: fix dead references to pruned claude-code-tools.md/copilot-tools.md e7ddc25 deleted claude-code-tools.md and copilot-tools.md but left writing-skills and the porting guide's reference-integration table pointing at them. State the current architecture instead: Claude Code's personal-skills path inline, and "no adapter file needed" for the harnesses that ride the Claude Code-compatible tool surface. Reported by @rasibintang (#1969, with a fix proposed in #1970). Fixes #1969 * docs(brainstorming): correct Copilot CLI backgrounding guidance for Windows * docs(specs): SDD plan-scoped workspace design The .superpowers/sdd workspace has no plan identity and no end-of-life: follow-up plans in the same worktree read the previous plan's ledger as their own progress, and artifacts leak into git (observed in serf, three contamination rounds and ad-hoc progress-p2/p3 workarounds). Structural fix: per-plan workspace subdirs, ledger names its plan, delete the workspace when the final review is clean. * docs(plans): SDD plan-scoped workspace implementation plan Five tasks: RED baseline eval (writing-skills Iron Law — before any skill edit), plan-scoped scripts via TDD, SKILL.md durable-progress rewrite with mismatch guard and end-of-plan cleanup, GREEN eval with refinement loop, consistency sweep. Eval = 5 fresh sonnet subagents per scenario per arm, hand-scored. * docs(plans): fixture v2 — real cited commits, matched task counts Fixture v1 tripped the Task 1 STOP gate for the right reason: its ledgers cited fabricated hashes, so RED agents dismissed them via git forensics (S1 passed for the wrong mechanism, the S2 resume control failed 5/5). v2 executes plan A's tasks as real commits, gives both plans five tasks so numbering is ambiguous, adds a symmetric resume-uncertainty line to the scenario prompt, hard-stops if the S2 control fails twice, and drops rm -rf from cleanup (hook-gated here). * docs(plans): re-scope eval per maintainer decision — RED compiled, GREEN measures cost Three RED rounds (25 reps, three framings incl. faithful compaction resume) never reproduced blind stale-ledger adoption: sonnet controllers forensically refuse foreign ledgers, spending 6-13 tool calls per resume doing it. Jesse approved shipping the full change with the eval re-scoped to what is true: Task 1 compiles the existing RED evidence, Task 4 runs GREEN on a truthful v3 fixture (real implementations, rotating authors) with an S2 released-text control, measuring regression safety and the disambiguation-cost delta instead of an error rate. * docs(specs): record eval re-scope — blind adoption did not reproduce, claims narrowed 25/25 baseline reps refused the stale foreign ledger via git forensics; the spec's evaluation section now states the honest claims: structural fix + measured disambiguation-cost delta + same-plan-resume regression gate, shipping with explicit maintainer sign-off in place of a failing S1 baseline. * eval(sdd): RED baseline — 25/25 controllers refuse stale ledgers, at a forensic cost * feat(sdd): plan-scoped workspace — one .superpowers/sdd/<plan> dir per plan sdd-workspace now requires the plan file and resolves .superpowers/sdd/<plan-basename>/; task-brief and review-package write into their plan's directory (review-package gains PLAN_FILE as its first argument). Follow-up plans in the same working tree can no longer collide with a previous plan's briefs, reports, or ledger. * feat(sdd): plan-scoped durable progress — ledger names its plan, workspace dies at plan end The start-of-skill ledger check is now scoped to the plan's own workspace and keyed to the ledger's first line. Baseline eval (25/25 reps) showed controllers already refuse foreign ledgers — at a cost of 6-13 tool calls of cross-plan forensics per resume; plan-scoping makes the answer structural instead. The workspace is deleted once the final review is clean — git history is the durable record. * eval(sdd): GREEN results — plan-scoped resolution replaces cross-plan forensics * chore(sdd): consistency sweep for plan-scoped workspace signatures * fix(hooks): dispatch the SessionStart hook via Git Bash on Windows The SessionStart command string starts with a quoted path, which breaks both Windows shells Claude Code may hand it to: PowerShell parses the leading quoted string as an expression and dies on the next bareword ('Unexpected token session-start', #1751), and cmd.exe's /c quote rule drops the outer quotes when the path contains a metacharacter, so a profile dir like C:\Users\Name(External) truncates the command at the '(' (#1918). Either way the bootstrap silently never loads. Declare shell: "bash" on the hook. Claude Code >= 2.1.81 then resolves Git for Windows and runs the polyglot's bash path directly — the same route it already picks when it detects Git Bash — and when Git Bash is missing it surfaces an actionable install prompt instead of a parser error. Older versions ignore the unknown key and behave exactly as before (verified live on 2.0.77 and 2.1.80). Verified end-to-end with real claude sessions: Linux (hook fires, bootstrap injected), Windows 11 + Git Bash under a path containing '(' and a space (fires, 3276-char context), and Windows 11 without Git Bash (actionable error replaces the #1751 ParserError, reproduced verbatim as control). Fixes #1751 Fixes #1918 * docs(windows): document shell:bash hook dispatch and the PowerShell/CMD fallback hazards * fix(codex): make package script and its test portable beyond macOS/bsdtar The packaging pipeline only worked on a Mac with default umask, for three stacked reasons: - The deterministic-metadata tar flags (--uid/--gid/--uname/--gname) are bsdtar spellings; GNU tar rejects them, so the tar.gz archive step died on Linux. Detect the tar flavor and use --owner=:0 --group=:0 --numeric-owner on GNU tar, which writes byte-identical ustar headers (uid/gid 0, empty uname/gname). - Staged file modes depended on two umasks canceling out: git archive masks entry modes with tar.umask (git default 0002 -> 775), and the unflagged tar extraction re-masked with the process umask (022 on macOS -> 755, but 002 elsewhere -> 775). Pin tar.umask=0022 on the archive call and extract with -p so staged modes are canonical 755/644 on every machine. - The test's timestamp assertion parsed bsdtar's -tv column layout and expected epoch 0 rendered in a US timezone ("Dec 31 1969"); GNU tar uses different columns and UTC hosts render "1970-01-01". Assert mtime == 0 via python3 tarfile instead, matching how the test already checks zip timestamps. tests/codex/test-package-codex-plugin.sh now passes on Linux/GNU tar; the bsdtar branch preserves the exact flags that passed on macOS. * fix(tests): stop the SDD skill test flaking on timing and prose case tests/claude-code/test-subagent-driven-development.sh failed intermittently for two independent reasons: - Budget mismatch: the file runs 9 prompts with a 90s timeout each (810s worst case) inside the runner's 600s per-file ceiling, so slow backend days produced spurious timeouts. Raise the runner default to 900s and fix the help text, which claimed the default was 300. - Case-sensitive prose matching: the assert helpers grepped free-form model output case-sensitively, but models capitalize the skill's own headings — observed failures include "Do Not Trust the Report" missing pattern "not trust" and a structured answer missing "First:.*spec.*compliance". Match case-insensitively in assert_contains/assert_not_contains/assert_count/assert_order, widen two Test 5 keyword patterns to phrasings observed in real runs, and make assert_order dump the output on failure the way assert_contains already does, so the next flake is diagnosable. Observed 3 failures across 4 runs before the change (timeout, two distinct pattern misses); 3/3 consecutive full runs pass after it. * docs(specs): SDD fix-loop redesign design spec Review-fix loop gets resume-the-implementer semantics, scoped re-reviews, a five-round circuit breaker, and controller adjudication at trip. SKILL.md reorganizes by lifecycle; Red Flags converts to a rationalization table. Brainstormed with Jesse 2026-07-15. * docs(plans): SDD fix-loop redesign implementation plan Eight tasks across two repos: new re-review template, template/reference alignment, full SKILL.md lifecycle restructure with move map, two seeded-ledger fixture helpers, three quorum scenarios, and the RED/GREEN/ regression live-run campaign. * feat(sdd): add scoped re-review prompt template * 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/<name>/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/<skill-name>/ 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 <SUBAGENT-STOP>: - 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 <SUBAGENT-STOP> 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 <plan-basename> 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/<name> --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. - ${BASH:-bash} replaces a bare 'bash' in run-hook.cmd's exec — bash always sets $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) --------- Co-authored-by: Gaurav Dubey <gauravdubey0107@gmail.com> Co-authored-by: arimu1 <19286898+arimu1@users.noreply.github.com> Co-authored-by: Mark Rada <markrada26@gmail.com> Co-authored-by: dev_Hakaze <af.nawfal@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: kumarabd <kumarabd@users.noreply.github.com> Co-authored-by: Drew Ritter <drew@ritter.dev> Co-authored-by: Drew Ritter <drew@primeradiant.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Kattni <kattni@kattni.com> Co-authored-by: GoldJohnKing <GoldJohnKing@live.cn> Co-authored-by: Georgii Perepechko <georgiiperepechko@gmail.com> Co-authored-by: Caio Lopes <caiodesalopes@gmail.com> Co-authored-by: Drew Ritter <arittr@users.noreply.github.com> Co-authored-by: Ada Sen <ada.sen@primeradiant.com> Co-authored-by: 落尘 <cuidong111@gmail.com> Co-authored-by: m2dumpling <nightydumpling@gmail.com> Co-authored-by: Klemens Flöge <117587964+klemens-floege@users.noreply.github.com> Co-authored-by: citizen204 <161211652+citizen204@users.noreply.github.com> Co-authored-by: KaiyiQuan <156817180+KaiyiQuan@users.noreply.github.com> Co-authored-by: aruizcu1989 <192807317+aruizcu1989@users.noreply.github.com> Co-authored-by: tugrulguner <47668043+tugrulguner@users.noreply.github.com> Co-authored-by: t0domanh <3890425+t0domanh@users.noreply.github.com> Co-authored-by: pepijn-blom <322216308+pepijn-blom@users.noreply.github.com>
-rw-r--r--.antigravity-plugin/plugin.json27
-rw-r--r--.claude-plugin/marketplace.json2
-rw-r--r--.claude-plugin/plugin.json2
-rw-r--r--.codex-plugin/plugin.json2
-rw-r--r--.cursor-plugin/plugin.json2
-rw-r--r--.devin-plugin/plugin.json2
-rw-r--r--.hermes-plugin/__init__.py23
-rw-r--r--.hermes-plugin/plugin.yaml2
-rw-r--r--.kimi-plugin/plugin.json2
-rw-r--r--.muse-plugin/marketplace.json2
-rw-r--r--.muse-plugin/plugin.json2
-rw-r--r--.opencode/INSTALL.md2
-rw-r--r--.version-bump.json1
-rw-r--r--README.md9
-rw-r--r--RELEASE-NOTES.md48
-rw-r--r--assets/antigravity-logo.pngbin0 -> 16690 bytes
-rw-r--r--docs/README.opencode.md2
-rw-r--r--docs/porting-to-a-new-harness.md40
-rw-r--r--docs/superpowers/plans/2026-10-06-antigravity-marketplace.md711
-rw-r--r--docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md165
-rw-r--r--docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md181
-rw-r--r--docs/windows/polyglot-hooks.md15
-rw-r--r--gemini-extension.json2
-rwxr-xr-xhooks/run-hook.cmd52
-rwxr-xr-xhooks/session-start48
-rw-r--r--package.json2
-rwxr-xr-xscripts/bump-version.sh6
-rwxr-xr-xscripts/render-antigravity-logo.sh66
-rwxr-xr-xscripts/sync-to-codex-plugin.sh4
-rw-r--r--skills/brainstorming/SKILL.md466
-rw-r--r--skills/brainstorming/builder-check-prompt.md23
-rw-r--r--skills/brainstorming/scripts/server.cjs2
-rw-r--r--skills/brainstorming/spec-document-reviewer-prompt.md49
-rwxr-xr-xskills/executing-plans/scripts/task-done2
-rw-r--r--skills/requesting-code-review/SKILL.md2
-rwxr-xr-xskills/subagent-driven-development/scripts/sdd-workspace13
-rw-r--r--skills/systematic-debugging/SKILL.md4
-rwxr-xr-xtests/antigravity/test-antigravity-tools.sh10
-rwxr-xr-xtests/antigravity/test-logo.sh44
-rwxr-xr-xtests/antigravity/test-plugin-manifest.sh107
-rw-r--r--tests/brainstorm-server/lifecycle.test.js6
-rw-r--r--tests/brainstorm-server/server.test.js17
-rwxr-xr-xtests/claude-code/test-executing-plans-scripts.sh27
-rwxr-xr-xtests/claude-code/test-sdd-workspace.sh30
-rwxr-xr-xtests/codex-plugin-sync/test-sync-to-codex-plugin.sh14
-rw-r--r--tests/hermes/conftest.py4
-rw-r--r--tests/hermes/test_plugin.py36
-rwxr-xr-xtests/hooks/test-run-hook-cmd-windows.sh223
-rwxr-xr-xtests/hooks/test-session-start.sh100
-rw-r--r--tests/version-bump/test-bump-version.sh13
-rwxr-xr-xtests/writing-skills/test-render-graphs.sh4
51 files changed, 2219 insertions, 399 deletions
diff --git a/.antigravity-plugin/plugin.json b/.antigravity-plugin/plugin.json
new file mode 100644
index 0000000..6f85dec
--- /dev/null
+++ b/.antigravity-plugin/plugin.json
@@ -0,0 +1,27 @@
+{
+ "name": "superpowers",
+ "displayName": "Superpowers",
+ "version": "7.0.0",
+ "description": "Make your coding agent a better engineer",
+ "logo": "assets/antigravity-logo.png",
+ "suggestedPrompts": [
+ "I've got an idea for something I'd like to build",
+ "Let's figure out why this broke"
+ ],
+ "category": "Developer Tools",
+ "keywords": [
+ "skills",
+ "tdd",
+ "debugging",
+ "collaboration",
+ "best-practices",
+ "workflows"
+ ],
+ "author": {
+ "name": "Jesse Vincent",
+ "email": "jesse@fsck.com"
+ },
+ "homepage": "https://github.com/obra/superpowers",
+ "repository": "https://github.com/obra/superpowers",
+ "license": "MIT"
+}
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 87d873f..92f8ab9 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "6.4.2",
+ "version": "7.0.0",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index aa2a09c..86e0b12 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "6.4.2",
+ "version": "7.0.0",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index f147352..9a9d0fe 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "6.4.2",
+ "version": "7.0.0",
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
"author": {
"name": "Jesse Vincent",
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index 8a8475c..e769727 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
"name": "superpowers",
"displayName": "Superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "6.4.2",
+ "version": "7.0.0",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
diff --git a/.devin-plugin/plugin.json b/.devin-plugin/plugin.json
index 71d0f0b..fd40a96 100644
--- a/.devin-plugin/plugin.json
+++ b/.devin-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "6.4.2",
+ "version": "7.0.0",
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
"author": {
"name": "Jesse Vincent",
diff --git a/.hermes-plugin/__init__.py b/.hermes-plugin/__init__.py
index 3b41644..7d4e1f5 100644
--- a/.hermes-plugin/__init__.py
+++ b/.hermes-plugin/__init__.py
@@ -37,6 +37,25 @@ def _strip_frontmatter(content: str) -> str:
return (match.group(1) if match else content).strip()
+def _frontmatter_value(content: str, key: str) -> str:
+ """Return a flat ``key: value`` scalar from a SKILL.md frontmatter block.
+
+ Hermes reads a skill's description from ``register_skill``'s ``description``
+ argument, which defaults to "" — registering only the path left every stock
+ skill with a blank description in the skill catalogue, so the model had
+ nothing to select on. Stock frontmatter is a flat block of single-line
+ scalars, so a line scan covers it without a YAML dependency.
+ """
+ match = re.match(r"^---\n([\s\S]*?)\n---\n", content)
+ if not match:
+ return ""
+ for line in match.group(1).splitlines():
+ name, sep, value = line.partition(":")
+ if sep and name.strip() == key:
+ return value.strip().strip("\"'")
+ return ""
+
+
def _build_bootstrap(skills_dir: str) -> str:
with open(
os.path.join(skills_dir, "using-superpowers", "SKILL.md"),
@@ -82,7 +101,9 @@ def register(ctx):
for name in sorted(os.listdir(skills_dir)):
skill_md = os.path.join(skills_dir, name, "SKILL.md")
if os.path.isfile(skill_md):
- ctx.register_skill(name, Path(skill_md))
+ with open(skill_md, encoding="utf-8") as f:
+ description = _frontmatter_value(f.read(), "description")
+ ctx.register_skill(name, Path(skill_md), description=description)
# pre_llm_call returning {"context": ...} is the documented injection path
# (on_session_start return values are ignored, and ctx.inject_message
diff --git a/.hermes-plugin/plugin.yaml b/.hermes-plugin/plugin.yaml
index 9de7655..f2da36c 100644
--- a/.hermes-plugin/plugin.yaml
+++ b/.hermes-plugin/plugin.yaml
@@ -1,5 +1,5 @@
name: superpowers
-version: 6.4.2
+version: 7.0.0
description: Superpowers skills and workflow bootstrap for Hermes Agent
author: obra
provides_hooks:
diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json
index 1effbcf..3da881d 100644
--- a/.kimi-plugin/plugin.json
+++ b/.kimi-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "6.4.2",
+ "version": "7.0.0",
"description": "An agentic skills framework and software development methodology.",
"author": {
"name": "Jesse Vincent",
diff --git a/.muse-plugin/marketplace.json b/.muse-plugin/marketplace.json
index c3d7295..4306a70 100644
--- a/.muse-plugin/marketplace.json
+++ b/.muse-plugin/marketplace.json
@@ -9,7 +9,7 @@
{
"name": "superpowers",
"description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "6.4.2",
+ "version": "7.0.0",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.muse-plugin/plugin.json b/.muse-plugin/plugin.json
index 3588fd5..32bdcbf 100644
--- a/.muse-plugin/plugin.json
+++ b/.muse-plugin/plugin.json
@@ -2,7 +2,7 @@
"schemaVersion": 1,
"name": "superpowers",
"displayName": "Superpowers",
- "version": "6.4.2",
+ "version": "7.0.0",
"description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
"compat": {
"source": "native",
diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md
index dca404b..2102fd1 100644
--- a/.opencode/INSTALL.md
+++ b/.opencode/INSTALL.md
@@ -79,7 +79,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.2"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.0"]
}
```
diff --git a/.version-bump.json b/.version-bump.json
index 8d95be0..c80749f 100644
--- a/.version-bump.json
+++ b/.version-bump.json
@@ -7,6 +7,7 @@
{ "path": ".codex-plugin/plugin.json", "field": "version" },
{ "path": ".devin-plugin/plugin.json", "field": "version" },
{ "path": ".kimi-plugin/plugin.json", "field": "version" },
+ { "path": ".antigravity-plugin/plugin.json", "field": "version" },
{ "path": ".muse-plugin/plugin.json", "field": "version" },
{ "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
{ "path": ".muse-plugin/marketplace.json", "field": "plugins.0.version" },
diff --git a/README.md b/README.md
index cf80400..e40ddfa 100644
--- a/README.md
+++ b/README.md
@@ -89,8 +89,9 @@ Install Superpowers as a plugin from this repository:
agy plugin install https://github.com/obra/superpowers
```
-Antigravity runs the plugin's session-start hook, so Superpowers is active from
-the first message. Reinstall with the same command to update.
+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
@@ -306,7 +307,7 @@ Restart any active Muse sessions after installing so the `SessionStart` hook tak
## The Basic Workflow
-1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
+1. **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.
2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
@@ -349,7 +350,7 @@ Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of t
- **diagnosing-superpowers** - Work out what went wrong in a session, with evidence; export a scrubbed bundle or file an issue
**Collaboration**
-- **brainstorming** - Socratic design refinement
+- **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
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 44490ef..1789816 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,5 +1,53 @@
# Superpowers Release Notes
+## v7.0.0 (2026-10-09)
+
+We rebuilt brainstorming from scratch so it does a much better job of what it was always for: helping you work out what you actually want and put it into words before anything gets built. The new skill asks you to describe what you're after and why, plays back what it heard so you can correct it, and keeps asking good questions until the picture is clear. Then it matches the process to the work, from just doing it to writing a full design.
+
+This release also adds a native plugin manifest for the Antigravity Marketplace and fixes Windows hook discovery, Git Bash paths, Hermes skill descriptions, and several smaller bugs.
+
+### Brainstorming
+
+- **Brainstorming draws out what you want before it proposes anything.** Its first message offers to skip the questions and asks one open question about a real moment or a concrete picture. It offers a menu only when you're stuck. Along the way, it offers to look at prior art, your project, or the web. As it understands each part, it plays that part back in a few hundred words and marks its guesses as guesses. (#2463)
+- **It sizes the work after it understands what you want, and says so in plain words.** It does a quick, clear task right away, agrees a small change with you in chat, and writes a design document for a project. You can override its call, and it steps up a size if the work grows. (#2463)
+- **A builder check replaces the spec-document reviewer.** A fresh subagent reads the design as the person who'll build it and lists what they'd still need to ask. Brainstorming answers what it can, makes the minor calls itself and marks them as its own, and brings you the questions that change what gets built, in one round. (#2463)
+- **It finds out which choices about how the thing gets made you want to own.** Platform, language, libraries, medium: if you have strong views, it talks them through; if you hand them over, it picks sensible defaults and tells you what it picked. It does this even when you skip the questions. We made this change after a session designed an iOS app, never asked about platform, and built a web app. (#2482, #2483)
+- **It offers the visual companion whenever seeing would help more than reading:** screens, layouts, flows, options that look different, diagrams. The offer drops its token-cost warning. (#2463)
+- **The visual companion now shows screens containing `$'`, `$&`, and similar sequences intact.** The server inserted content with `String.replace`, which treats those sequences as replacement patterns. It now inserts content literally. Thanks @andrew-yian for the report and @luochen211 for the fix. (#2362, #2364)
+
+### Antigravity
+
+- **`agy plugin install https://github.com/obra/superpowers` now installs Superpowers as a native Antigravity plugin.** We added `.antigravity-plugin/plugin.json` with the Marketplace display name, logo, and suggested prompts. Previously, agy fell back to importing the repo as a Gemini CLI extension, then rejected the copied Claude-format hooks file on every session with `invalid hook "hooks": command hook must specify 'command'`. The install command stays the same. (#2479)
+- **Superpowers bootstraps on Antigravity through skill discovery.** Antigravity has no session-start hook event, but it shows the model each installed skill's description, and `using-superpowers`' "Use when starting any conversation" prompts the model to load it. We verified this on agy 1.3.1 across 12 runs: "Let's make a react todo list" and "add a settings page" triggered brainstorming before any code, and a failing test triggered systematic-debugging before any edit. We also corrected the README and porting guide, which described a session-start hook and install script that never existed. (#2479)
+
+### Hooks
+
+- **SessionStart now works when the harness launches it with a broken `PATH`.** The hooks no longer look up `dirname`, `cat`, or `bash` on `PATH`, so a startup `PATH` that can't resolve them (anthropics/claude-code#43127) no longer drops the bootstrap. Thanks @kannan983 for the report and Ada Sen for the fix. (#2310, #2349)
+- **Windows: `run-hook.cmd` finds per-user Git for Windows installs and skips WSL launchers.** It now checks `%LOCALAPPDATA%\Programs\Git`, and when it searches `PATH`, it skips the WSL `bash.exe` launchers, which fail without a Linux distro. Thanks @jp5247 for the report, and @citizen204 (#1864) and @KaiyiQuan (#2365) for the fixes we combined here. (#1863, #2393)
+- **Windows: `run-hook.cmd` ignores `bash` and `where` in the current directory.** Previously, a repository could plant `bash.cmd` or `where.bat` and have it run at session start. (#2393)
+- **Windows: `run-hook.cmd` now passes hook exit codes to the harness.** It used to report success even when the hook failed. (#2393)
+
+### Subagent-Driven Development
+
+- **`sdd-workspace` leaves a repo's own `.superpowers/sdd/.gitignore` alone.** It used to overwrite the file with `*` on every run, reverting any version a repo committed (for example, to track `progress.md` ledgers). It now writes the default only when no file exists. Thanks @aruizcu1989 for the fix. (#2161, #2399)
+- **Plan markers stay repo-relative on Windows.** On Git Bash, `sdd-workspace` compared `git rev-parse`'s `C:/…` root with the plan's `/c/…` path, so every workspace marker recorded an absolute, machine-specific path. It now resolves the root the same way as the plan path. We found this while landing @t0domanh's Windows test fixes (#2149).
+
+### Executing Plans
+
+- **`task-done` now records tasks whose test command passes silently.** When a passing command printed nothing, `task-done` exited 1 without writing the ledger line, so a finished task looked unfinished. It now records `→ (no output)`. Thanks @KenM-BT for the report and Ada Sen for the fix. (#2385, #2388)
+
+### Requesting Code Review
+
+- **The example's base-SHA command survives skill arguments.** Claude Code replaces `$1` in a skill body with the second argument word, so invoking the skill with arguments turned `awk '{print $1}'` into `awk '{print <word>}'`. The example now uses `cut -d' ' -f1`, which contains no `$`. Thanks @errmakov for the report and @klemens-floege for the fix. (#2311, #2361)
+
+### Systematic Debugging
+
+- **The multi-layer diagnostic example no longer prints the secret it checks for.** `${IDENTITY:+SET}${IDENTITY:-UNSET}` and `env | grep IDENTITY` both echoed the signing identity's value into logs. The example now reports only whether the variable is set. Thanks @kennyg-g for the report and @m2dumpling for the fix. (#2375, #2380)
+
+### Hermes Agent
+
+- **Hermes' skill list now shows Superpowers skill descriptions.** Hermes lists each plugin skill with the description passed to `register_skill`, which defaults to empty. The plugin passed only a name and path, so every skill appeared blank and the model had nothing to choose from. The plugin now passes each skill's frontmatter description. Thanks @pepijn-blom for the fix. (#2284)
+
## v6.4.2 (2026-09-25)
`writing-plans` produces leaner plans, faster. Plans now record the decisions an implementer needs (signatures, test assertions, the spec's values) instead of writing out the code. Some frontier models, including Opus 5.5, could get overzealous during plan writing and, with certain prompting, would sometimes try to implement the entire project while designing the plan. The new skill keeps planning focused on the plan. When we reproduced the original report, the scratch builds went away, and plans took a quarter of the time and about a third of the tokens. Thanks to Harper Reed for the report and session bundle. (#2333)
diff --git a/assets/antigravity-logo.png b/assets/antigravity-logo.png
new file mode 100644
index 0000000..638935d
--- /dev/null
+++ b/assets/antigravity-logo.png
Binary files differ
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 404a65d..980941e 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -111,7 +111,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.2"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.0"]
}
```
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
index ce37418..f52cd70 100644
--- a/docs/porting-to-a-new-harness.md
+++ b/docs/porting-to-a-new-harness.md
@@ -292,10 +292,10 @@ part of the installed extension** — never substitute "edit the user's global
| runs a shell command at session start and reads its stdout | A (shell-hook) | Cursor (`hooks/session-start` + `hooks/hooks-cursor.json` + `.cursor-plugin/`) |
| is a JS/TS plugin host with session/message lifecycle callbacks | B (in-process) | OpenCode (`.opencode/`) — or pi (`.pi/`) if it has no native skill tool |
| ships an extension-declared context file it always loads | C (instructions-file) | Gemini (`gemini-extension.json` + `GEMINI.md` + `references/gemini-tools.md`) |
-| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
+| lists each installed skill's description, with no session-start event and no context-file field | skill-index bootstrap (Part 5 Step 5, case 2 fallback) | Antigravity (`.antigravity-plugin/plugin.json` + `skills/` only) |
-Most real harnesses fit one row cleanly; the last is the hybrid case (rule 2 still
-holds — the bootstrap rides the install mechanism, never a user-config edit).
+Most real harnesses fit one row cleanly; the last is the soft case — see Step 5's
+fallback caveats (rule 2 still holds — never a user-config edit).
---
@@ -525,11 +525,22 @@ honors the rule rather than breaking it. Distinguish three cases:
the file-read tool when the skill applies** — the sanctioned mechanism here,
the way `references/pi-tools.md` states it.
- **For the bootstrap itself, prefer a declared context file (Part 6).** If the
- harness has a `contextFileName`-style manifest field — as Antigravity does —
- ship a generated context file through the installer: it's guaranteed-loaded and
- carries both the `using-superpowers` content and the tool mapping. That is the
- strong, preferred path.
+ **For the bootstrap itself, prefer something the harness loads every
+ session (Part 6)** — a declared context file where the manifest has a
+ `contextFileName`-style field. Antigravity has none, and its other options
+ cost more than they buy, so it uses the surfaced skill index below:
+ - Its hooks have no session-start event. `PreInvocation` runs before every
+ model call; an `ephemeralMessage` it injects is dropped on the next call,
+ and `invocationNum` resets on each user turn. A `userMessage` gated on
+ `invocationNum == 0` and `initialNumSteps == 1` injects exactly once per
+ conversation, but agy still starts the hook process on every model call.
+ `${PLUGIN_ROOT}` is not set in hooks (they run from the plugin root).
+ `hooks.json` must sit at the plugin root; no manifest field moves it.
+ - It loads `rules/*.md` from a plugin every session, but harnesses that
+ install from the git repo share its root, and Cursor is one of them: it
+ also loads any `rules/*.md` a plugin ships. A file in a shared plugin root
+ is visible to every harness that reads that root — check before adding
+ one.
**Fallback — the surfaced skill index.** If there's no context-file field but
the harness surfaces each installed skill's name + description at session start,
@@ -678,7 +689,7 @@ it. Distribution differs per harness ecosystem — find yours:
| External marketplace fork, synced by script | Codex | `scripts/sync-to-codex-plugin.sh` rsyncs the tracked plugin files into a separate fork repo and opens a PR. Read its include/exclude list so you ship the right tree (it deliberately drops repo-internal dirs and other harnesses' dotdirs). |
| Git-URL extension install | Gemini, Kimi Code, OpenCode | Users install from a git URL (`gemini extensions install …`; Kimi Code `/plugins install …`; an `opencode.json` `plugin` array entry). Document the exact command. |
| Package-manifest fields | pi | Declared through fields in the repo-root `package.json`; users install via the harness's package command. |
-| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |
+| Git-URL plugin install + marketplace | Antigravity (`agy`) | Users run `agy plugin install https://github.com/obra/superpowers`. agy reads `.antigravity-plugin/plugin.json`, whose Marketplace fields (`displayName`, `logo`, `suggestedPrompts`, `version`, `author`) also drive the Antigravity Marketplace listing. Without that manifest, agy falls back to importing `gemini-extension.json`. |
Then:
@@ -694,13 +705,9 @@ Then:
session), that is the strongest clean bootstrap: declare it, and the installer
preserves it *and* the harness loads it. Generate it at install time from the
live `using-superpowers/SKILL.md` + the tool mapping (wrapped in
- `<EXTREMELY_IMPORTANT>`) so the installed bootstrap never drifts. This is what
- `.antigravity-plugin/install.sh` does — `agy plugin install` reports
- `✔ context : ANTIGRAVITY.md`, and a clean session reads `using-superpowers`'s
- SKILL.md, loads `brainstorming`, and enters the brainstorming flow before any
- code. **Verify with a marker** that the installer keeps the file and the
- harness loads it: one porter wrongly concluded it couldn't, because they
- shipped the file *without* declaring `contextFileName` and it was stripped as
+ `<EXTREMELY_IMPORTANT>`) so the installed bootstrap never drifts.
+ **Verify with a marker** that the installer keeps the file and the
+ harness loads it: a file the manifest doesn't declare can be stripped as
unrecognized.
- **Otherwise lean on the installed `using-superpowers` skill itself.** If the
harness surfaces each installed skill's name + description at session start,
@@ -796,6 +803,7 @@ Use this as the live index; when in doubt, read the files, not this table.
| Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution |
|---|---|---|---|---|---|
+| Antigravity (`agy`) | `.antigravity-plugin/plugin.json` | surfaced skill index: `using-superpowers`' description triggers it (no session-start hook event exists) | `references/antigravity-tools.md` | `tests/antigravity/` | `agy plugin install` git URL; Antigravity Marketplace |
| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; no adapter file needed | `tests/hooks/` | marketplace |
| Codex | `.codex-plugin/plugin.json` (declares empty `hooks`) | native skill discovery (no session-start hook) | `references/codex-tools.md` | `tests/codex/`, `tests/codex-plugin-sync/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |
| Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | none needed (Claude Code–compatible tool surface) | `tests/hooks/` | hand-authored |
diff --git a/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md b/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md
new file mode 100644
index 0000000..5804e05
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md
@@ -0,0 +1,711 @@
+# Antigravity Marketplace Plugin Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a native Antigravity plugin (manifest with Marketplace fields, logo, always-on rule bootstrap) so Superpowers can be listed in the Antigravity Marketplace.
+
+**Architecture:** agy reads `.antigravity-plugin/plugin.json` and discovers `skills/` by default. A one-line always-on rule, `rules/AGENTS.md`, `@`-points at `skills/using-superpowers/SKILL.md`; agy rewrites that path to an absolute install path and the model reads it with `view_file`. The logo is a PNG rendered from `assets/superpowers-small.svg` by a script.
+
+**Tech Stack:** bash, python3 (stdlib only, in tests), `rsvg-convert` (logo rendering only), `agy` 1.3.1 (optional in tests, required for live acceptance), `jq`.
+
+**Spec:** `docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md`
+
+> **Historical record.** This plan was executed as written. The `rules/AGENTS.md` bootstrap it describes was later removed in favor of skill discovery, and the Marketplace copy was replaced; see spec §1 and §2 for the shipped design.
+
+## Global Constraints
+
+- Work on branch `antigravity-marketplace`. PRs target `dev`.
+- Never copy `using-superpowers` content into another file. The rule is a pointer only.
+- No root `plugin.json` and no root `hooks.json` (either changes how agy reads the plugin).
+- Manifest `name` is `superpowers`; must match `^[a-z0-9]+(-[a-z0-9]+)*$`.
+- Manifest `description` is at most 160 characters.
+- `suggestedPrompts`: 1–3 non-empty strings.
+- Manifest `version` equals `.claude-plugin/plugin.json`'s `version` (6.4.2 at time of writing).
+- `author` matches `.claude-plugin/plugin.json`: `{ "name": "Jesse Vincent", "email": "jesse@fsck.com" }`.
+- Logo: `assets/antigravity-logo.png`, 512×512 RGBA PNG; white rounded square inset 31px, corner radius 100; mark `#1a1a1a`, scale 0.905 about (256,256).
+- `${PLUGIN_ROOT}` is not substituted in rules. Do not use it in `rules/AGENTS.md`.
+- New shell scripts must pass `scripts/lint-shell.sh <file>`.
+- Any `agy plugin install` done for testing must be followed by `agy plugin uninstall superpowers`.
+
+---
+
+## File Map
+
+| File | Action | Responsibility |
+|---|---|---|
+| `scripts/render-antigravity-logo.sh` | Create | Compose logo SVG from `assets/superpowers-small.svg`, rasterize to PNG |
+| `assets/antigravity-logo.png` | Create (generated) | Marketplace logo |
+| `.antigravity-plugin/plugin.json` | Create | Native manifest with Marketplace fields |
+| `rules/AGENTS.md` | Create | Always-on bootstrap pointer |
+| `.version-bump.json` | Modify | Register the new manifest's version |
+| `tests/antigravity/test-logo.sh` | Create | Logo file shape checks |
+| `tests/antigravity/test-plugin-manifest.sh` | Create | Manifest, rule, and layout checks; `agy plugin validate` when available |
+| `tests/antigravity/test-antigravity-tools.sh` | Modify | Fix stale header comment |
+| `scripts/sync-to-codex-plugin.sh` | Modify | Exclude Antigravity-only files from the Codex sync |
+| `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh` | Modify | Assert those exclusions |
+| `README.md` | Modify | Antigravity section prose |
+| `docs/porting-to-a-new-harness.md` | Modify (separate commit) | Remove phantom installer; record agy findings |
+
+---
+
+### Task 1: Logo renderer and logo
+
+**Files:**
+- Create: `scripts/render-antigravity-logo.sh`
+- Create: `assets/antigravity-logo.png` (generated by the script)
+- Test: `tests/antigravity/test-logo.sh`
+
+**Interfaces:**
+- Produces: `assets/antigravity-logo.png` (Task 2's manifest `logo` field points here). `scripts/render-antigravity-logo.sh [--output PATH]`, default output `assets/antigravity-logo.png`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/antigravity/test-logo.sh`:
+
+```bash
+#!/usr/bin/env bash
+# Check the Antigravity Marketplace logo: a square RGBA PNG at least 128x128
+# (the Marketplace minimum), at the path the manifest names. When rsvg-convert
+# is available, also check the committed PNG matches a fresh render, so the
+# asset can't drift from scripts/render-antigravity-logo.sh.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+LOGO="$REPO_ROOT/assets/antigravity-logo.png"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+echo "test-logo: checking Antigravity logo"
+
+[ -f "$LOGO" ] || fail "logo missing at $LOGO"
+
+python3 - "$LOGO" <<'PY'
+import struct
+import sys
+
+data = open(sys.argv[1], "rb").read()
+if data[:8] != b"\x89PNG\r\n\x1a\n":
+ raise SystemExit("FAIL: logo is not a PNG")
+width, height, bit_depth, color_type = struct.unpack(">IIBB", data[16:26])
+if width != height:
+ raise SystemExit(f"FAIL: logo is not square ({width}x{height})")
+if width < 128:
+ raise SystemExit(f"FAIL: logo is smaller than 128x128 ({width}x{height})")
+if color_type != 6:
+ raise SystemExit(f"FAIL: logo is not RGBA (PNG color type {color_type})")
+PY
+
+if command -v rsvg-convert >/dev/null 2>&1; then
+ tmp="$(mktemp -d)"
+ trap 'rm -f "$tmp/logo.png"; rmdir "$tmp"' EXIT
+ bash "$REPO_ROOT/scripts/render-antigravity-logo.sh" --output "$tmp/logo.png" >/dev/null
+ cmp -s "$tmp/logo.png" "$LOGO" \
+ || fail "assets/antigravity-logo.png is stale; run scripts/render-antigravity-logo.sh"
+else
+ echo "SKIP: rsvg-convert not on PATH; not checking logo freshness"
+fi
+
+echo "PASS: Antigravity logo valid"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bash tests/antigravity/test-logo.sh`
+Expected: `FAIL: logo missing at .../assets/antigravity-logo.png`, exit 1.
+
+- [ ] **Step 3: Write the renderer**
+
+Create `scripts/render-antigravity-logo.sh`:
+
+```bash
+#!/usr/bin/env bash
+#
+# Render the Antigravity Marketplace logo from assets/superpowers-small.svg.
+#
+# Usage:
+# scripts/render-antigravity-logo.sh [--output PATH]
+#
+# Draws the Superpowers mark in near-black on a white rounded square with
+# transparent corners, 512x512 PNG. Run it whenever superpowers-small.svg
+# changes; tests/antigravity/test-logo.sh fails if the committed PNG is stale.
+# Requires rsvg-convert (Homebrew: librsvg).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SOURCE_SVG="$REPO_ROOT/assets/superpowers-small.svg"
+OUTPUT="$REPO_ROOT/assets/antigravity-logo.png"
+
+usage() {
+ sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+die() {
+ echo "error: $*" >&2
+ exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --output)
+ [[ $# -ge 2 ]] || die "--output needs a path"
+ OUTPUT="$2"
+ shift 2
+ ;;
+ -h | --help)
+ usage
+ exit 0
+ ;;
+ *)
+ usage >&2
+ die "unknown argument: $1"
+ ;;
+ esac
+done
+
+command -v rsvg-convert >/dev/null 2>&1 \
+ || die "rsvg-convert is not on PATH (install librsvg, e.g. 'brew install librsvg')"
+[[ -r "$SOURCE_SVG" ]] || die "source mark not readable: $SOURCE_SVG"
+
+# Everything inside the source <svg> element: the mark's paths and ellipse.
+mark="$(sed -E 's/^.*<svg[^>]*>//; s#</svg>.*$##' "$SOURCE_SVG")"
+[[ -n "$mark" ]] || die "could not extract the mark from $SOURCE_SVG"
+
+# The mark's bounding box is centered at (256,256) in its 512 viewBox and is
+# 348 units wide; scale 0.905 makes it ~70% of the 450-unit rounded square.
+composed="$(mktemp)"
+trap 'rm -f "$composed"' EXIT
+cat >"$composed" <<EOF
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+ <rect x="31" y="31" width="450" height="450" rx="100" ry="100" fill="#ffffff"/>
+ <g fill="#1a1a1a" transform="translate(256 256) scale(0.905) translate(-256 -256)">$mark</g>
+</svg>
+EOF
+
+rsvg-convert -w 512 -h 512 "$composed" -o "$OUTPUT"
+echo "wrote $OUTPUT"
+```
+
+Then: `chmod +x scripts/render-antigravity-logo.sh`
+
+- [ ] **Step 4: Render the logo and look at it**
+
+Run: `bash scripts/render-antigravity-logo.sh`
+Expected: `wrote .../assets/antigravity-logo.png`.
+
+Open `assets/antigravity-logo.png` with the Read tool and confirm: white rounded square, transparent corners, full mark (two arcs, two inner strokes, and the center dot) centered in near-black.
+
+- [ ] **Step 5: Run the test and the shell linter**
+
+Run: `bash tests/antigravity/test-logo.sh && scripts/lint-shell.sh scripts/render-antigravity-logo.sh tests/antigravity/test-logo.sh`
+Expected: `PASS: Antigravity logo valid`, linter clean. Also run `bash scripts/render-antigravity-logo.sh --help` and confirm it prints usage.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/render-antigravity-logo.sh assets/antigravity-logo.png tests/antigravity/test-logo.sh
+git commit -m "feat(antigravity): render Marketplace logo from the Superpowers mark"
+```
+
+---
+
+### Task 2: Native manifest, bootstrap rule, version bump
+
+**Files:**
+- Create: `.antigravity-plugin/plugin.json`
+- Create: `rules/AGENTS.md`
+- Modify: `.version-bump.json` (add one entry to `files`)
+- Test: `tests/antigravity/test-plugin-manifest.sh`
+
+**Interfaces:**
+- Consumes: `assets/antigravity-logo.png` from Task 1.
+- Produces: `.antigravity-plugin/plugin.json`, `rules/AGENTS.md` (Task 3 excludes both from the Codex sync; Task 5 installs them).
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/antigravity/test-plugin-manifest.sh`:
+
+```bash
+#!/usr/bin/env bash
+# Validate the native Antigravity plugin: the Marketplace manifest, the
+# always-on rule that bootstraps using-superpowers, and the repo layout agy
+# depends on. CI-safe; when `agy` is on PATH, also runs `agy plugin validate`.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+echo "test-plugin-manifest: checking Antigravity plugin"
+
+python3 - "$REPO_ROOT" <<'PY'
+import json
+import re
+import struct
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+
+def fail(message):
+ raise SystemExit(f"FAIL: {message}")
+
+manifest_path = root / ".antigravity-plugin" / "plugin.json"
+if not manifest_path.is_file():
+ fail(f"manifest missing at {manifest_path}")
+manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+
+# --- Marketplace-required fields -------------------------------------------
+for field in ["name", "description", "displayName", "logo",
+ "suggestedPrompts", "version", "author"]:
+ if not manifest.get(field):
+ fail(f"manifest field {field!r} is missing or empty")
+
+if manifest["name"] != "superpowers":
+ fail(f"name must be 'superpowers', got {manifest['name']!r}")
+if not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", manifest["name"]):
+ fail("name is not kebab-case")
+
+description_length = len(manifest["description"])
+if not 120 <= description_length <= 160:
+ fail(f"description is {description_length} characters; Marketplace wants 120-160")
+
+prompts = manifest["suggestedPrompts"]
+if not isinstance(prompts, list) or not 1 <= len(prompts) <= 3:
+ fail("suggestedPrompts must be a list of 1-3 prompts")
+if not all(isinstance(p, str) and p.strip() for p in prompts):
+ fail("suggestedPrompts entries must be non-empty strings")
+
+claude_manifest = json.loads(
+ (root / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))
+if manifest["version"] != claude_manifest["version"]:
+ fail(f"version {manifest['version']!r} != .claude-plugin version "
+ f"{claude_manifest['version']!r}")
+if manifest["author"] != claude_manifest["author"]:
+ fail("author does not match .claude-plugin/plugin.json")
+
+# --- Logo ------------------------------------------------------------------
+logo = root / manifest["logo"]
+if not logo.is_file():
+ fail(f"logo {manifest['logo']!r} does not exist")
+header = logo.read_bytes()[:26]
+if header[:8] != b"\x89PNG\r\n\x1a\n":
+ fail("logo is not a PNG")
+width, height = struct.unpack(">II", header[16:24])
+if width != height or width < 128:
+ fail(f"logo must be square and at least 128x128, got {width}x{height}")
+
+# --- Version bumps ---------------------------------------------------------
+version_config = json.loads((root / ".version-bump.json").read_text(encoding="utf-8"))
+if not any(entry.get("path") == ".antigravity-plugin/plugin.json"
+ and entry.get("field") == "version"
+ for entry in version_config.get("files", [])):
+ fail(".version-bump.json does not register .antigravity-plugin/plugin.json")
+
+# --- Bootstrap rule: @-pointers only, each resolving from rules/ -----------
+rule = root / "rules" / "AGENTS.md"
+if not rule.is_file():
+ fail(f"bootstrap rule missing at {rule}")
+lines = [line.strip() for line in rule.read_text(encoding="utf-8").splitlines()
+ if line.strip()]
+if not lines:
+ fail("bootstrap rule is empty")
+for line in lines:
+ if not line.startswith("@"):
+ fail(f"bootstrap rule must contain only @-pointers, found: {line!r}")
+ target = (rule.parent / line[1:]).resolve()
+ if not target.is_file():
+ fail(f"rule pointer {line!r} does not resolve from rules/ to a file")
+if not any(line.endswith("skills/using-superpowers/SKILL.md") for line in lines):
+ fail("bootstrap rule does not point at using-superpowers")
+
+# --- Layout agy depends on -------------------------------------------------
+for stray in ["plugin.json", "hooks.json"]:
+ if (root / stray).exists():
+ fail(f"root {stray} must not exist; agy would read it instead")
+PY
+
+if command -v agy >/dev/null 2>&1; then
+ output="$(agy plugin validate "$REPO_ROOT" 2>&1)" \
+ || { echo "$output" >&2; echo "FAIL: agy plugin validate failed" >&2; exit 1; }
+ grep -q '\[ok\]' <<<"$output" \
+ || { echo "$output" >&2; echo "FAIL: agy plugin validate did not report [ok]" >&2; exit 1; }
+ grep -qE 'skills +: [0-9]+ processed' <<<"$output" \
+ || { echo "$output" >&2; echo "FAIL: agy found no skills" >&2; exit 1; }
+else
+ echo "SKIP: agy not on PATH; not running agy plugin validate"
+fi
+
+echo "PASS: Antigravity plugin manifest and bootstrap rule valid"
+```
+
+Note: `agy plugin validate` output contains ANSI color codes around `[ok]`; the `grep -q '\[ok\]'` still matches because the codes surround, not split, the text. Verify this in Step 4; if it does not match, strip codes with `sed 's/\x1b\[[0-9;]*m//g'` before grepping.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bash tests/antigravity/test-plugin-manifest.sh`
+Expected: `FAIL: manifest missing at .../.antigravity-plugin/plugin.json`, exit 1.
+
+- [ ] **Step 3: Write the manifest, the rule, and the version-bump entry**
+
+Create `.antigravity-plugin/plugin.json`:
+
+```json
+{
+ "name": "superpowers",
+ "displayName": "Superpowers",
+ "version": "6.4.2",
+ "description": "Skills that make your coding agent work like a senior engineer: brainstorming, planning, test-driven development, systematic debugging, and code review.",
+ "logo": "assets/antigravity-logo.png",
+ "suggestedPrompts": [
+ "Let's brainstorm a new feature before writing any code",
+ "Help me systematically debug a failing test",
+ "Write an implementation plan for this change"
+ ],
+ "category": "Developer Tools",
+ "keywords": [
+ "skills",
+ "tdd",
+ "debugging",
+ "collaboration",
+ "best-practices",
+ "workflows"
+ ],
+ "author": {
+ "name": "Jesse Vincent",
+ "email": "jesse@fsck.com"
+ },
+ "homepage": "https://github.com/obra/superpowers",
+ "repository": "https://github.com/obra/superpowers",
+ "license": "MIT"
+}
+```
+
+The `description` and `suggestedPrompts` copy needs Jesse's approval before this commit. If he changes it, keep the description 120–160 characters.
+
+Create `rules/AGENTS.md` containing exactly one line:
+
+```
+@../skills/using-superpowers/SKILL.md
+```
+
+In `.version-bump.json`, add after the `.kimi-plugin/plugin.json` entry:
+
+```json
+ { "path": ".antigravity-plugin/plugin.json", "field": "version" },
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bash tests/antigravity/test-plugin-manifest.sh && scripts/bump-version.sh --check && scripts/bump-version.sh --audit && bash tests/version-bump/test-bump-version.sh && scripts/lint-shell.sh tests/antigravity/test-plugin-manifest.sh`
+Expected: `PASS: Antigravity plugin manifest and bootstrap rule valid` (with the agy validate step running, since agy is installed here), version check reports all files at 6.4.2, audit finds no unlisted version strings, version-bump test passes, linter clean.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add .antigravity-plugin/plugin.json rules/AGENTS.md .version-bump.json tests/antigravity/test-plugin-manifest.sh
+git commit -m "feat(antigravity): native plugin manifest with always-on bootstrap rule"
+```
+
+---
+
+### Task 3: Keep Antigravity-only files out of the Codex sync
+
+**Files:**
+- Modify: `scripts/sync-to-codex-plugin.sh` (the `EXCLUDES=(` array, ~line 45)
+- Test: `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
+
+**Interfaces:**
+- Consumes: the paths `.antigravity-plugin/plugin.json`, `rules/AGENTS.md`, `assets/antigravity-logo.png`.
+
+- [ ] **Step 1: Write the failing test**
+
+In `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`:
+
+In `write_upstream_fixture`, add `"$repo/.antigravity-plugin"` and `"$repo/rules"` to the `mkdir -p` list. After the `.kimi-plugin/plugin.json` heredoc (~line 242), add:
+
+```bash
+ cat > "$repo/.antigravity-plugin/plugin.json" <<EOF
+{
+ "name": "superpowers",
+ "version": "$MANIFEST_VERSION"
+}
+EOF
+
+ printf '@../skills/using-superpowers/SKILL.md\n' > "$repo/rules/AGENTS.md"
+ printf 'antigravity png fixture\n' > "$repo/assets/antigravity-logo.png"
+```
+
+Add these three paths to that function's `git -C "$repo" add` list:
+
+```bash
+ .antigravity-plugin/plugin.json \
+ rules/AGENTS.md \
+ assets/antigravity-logo.png \
+```
+
+After the existing assertion `assert_not_contains "$preview_section" ".kimi-plugin/plugin.json" ...` (~line 659), add:
+
+```bash
+ assert_not_contains "$preview_section" ".antigravity-plugin/plugin.json" "Preview excludes Antigravity manifest from Codex sync"
+ assert_not_contains "$preview_section" "rules/AGENTS.md" "Preview excludes Antigravity bootstrap rule from Codex sync"
+ assert_not_contains "$preview_section" "assets/antigravity-logo.png" "Preview excludes Antigravity logo from Codex sync"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
+Expected: the three new assertions FAIL (the files appear in the preview); the rest pass.
+
+- [ ] **Step 3: Add the exclusions**
+
+In `scripts/sync-to-codex-plugin.sh`, in `EXCLUDES=(`:
+
+After `"/.claude/"` (alphabetical among dotdirs), add:
+
+```bash
+ "/.antigravity-plugin/"
+```
+
+Under `# Directories not shipped by canonical Codex plugins`, add `"/rules/"` in alphabetical position (after `"/lib/"`):
+
+```bash
+ "/rules/"
+```
+
+Add a new group after the directories group:
+
+```bash
+
+ # Other harnesses' assets
+ "/assets/antigravity-logo.png"
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh && scripts/lint-shell.sh scripts/sync-to-codex-plugin.sh tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
+Expected: all assertions pass, including `assets/app-icon.png` and `assets/superpowers-small.svg` still included; linter clean.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/sync-to-codex-plugin.sh tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
+git commit -m "fix(codex-sync): exclude Antigravity manifest, rule, and logo"
+```
+
+---
+
+### Task 4: README and stale test comment
+
+**Files:**
+- Modify: `README.md:84-93` (the `### Antigravity` section)
+- Modify: `tests/antigravity/test-antigravity-tools.sh:1-10` (header comment)
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Update the README section**
+
+Replace the body of `### Antigravity` (keep the heading) with:
+
+````markdown
+Install Superpowers as a plugin from this repository:
+
+```bash
+agy plugin install https://github.com/obra/superpowers
+```
+
+The plugin ships an always-on rule that loads the `using-superpowers` skill, so
+Superpowers is active from the first message. Reinstall with the same command to
+update.
+````
+
+- [ ] **Step 2: Fix the stale header comment**
+
+In `tests/antigravity/test-antigravity-tools.sh`, replace lines 2–7:
+
+```bash
+# Validate the Antigravity (agy) integration. agy installs the existing plugin
+# directly (`agy plugin install <repo-url>`): it loads the bundled skills and
+# runs the SessionStart hook for bootstrap, so there is no agy-specific scaffold
+# to test. What IS agy-specific is the tool mapping — subagent dispatch via
+# invoke_subagent (self/research types) and task tracking via a task artifact —
+# and SKILL.md pointing at it.
+```
+
+with:
+
+```bash
+# Validate the Antigravity (agy) tool mapping: subagent dispatch via
+# invoke_subagent (self/research types), task tracking via a task artifact, and
+# SKILL.md pointing at the mapping. The plugin manifest and bootstrap rule are
+# checked by test-plugin-manifest.sh.
+```
+
+- [ ] **Step 3: Run the Antigravity suite**
+
+Run: `bash tests/antigravity/run-tests.sh`
+Expected: all three tests pass, ending `=== All Antigravity tests passed ===`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md tests/antigravity/test-antigravity-tools.sh
+git commit -m "docs(antigravity): describe the always-on rule bootstrap"
+```
+
+---
+
+### Task 5: Live acceptance on agy
+
+No repo changes. This is the end-to-end proof required by AGENTS.md's "New Harness Support" section.
+
+**Files:** none (scratch only).
+
+**Interfaces:**
+- Consumes: the committed tree from Tasks 1–4.
+
+- [ ] **Step 1: Stage the committed tree and install it**
+
+Use the scratchpad directory (`$SCRATCH` below), never the repo:
+
+```bash
+mkdir -p "$SCRATCH/accept/superpowers"
+git archive HEAD | tar -x -C "$SCRATCH/accept/superpowers"
+agy plugin install "$SCRATCH/accept/superpowers"
+agy plugin list
+```
+
+Expected: install `[ok]`, skills processed, hooks skipped; `agy plugin list` shows `"source": "antigravity"`.
+
+- [ ] **Step 2: Run the acceptance prompt three times in fresh workspaces**
+
+For `n` in 1 2 3:
+
+```bash
+mkdir -p "$SCRATCH/accept/ws$n"
+cd "$SCRATCH/accept/ws$n"
+agy -p "Let's make a react todo list" --output-format stream-json --print-timeout 240s > out.jsonl 2> err.txt
+```
+
+For each run, list the tool steps:
+
+```bash
+python3 -I -c "
+import json
+for l in open('out.jsonl'):
+ e=json.loads(l); s=e.get('step_update') or {}
+ if s.get('state') in ('DONE','ERROR'):
+ p=(s.get('tool_info') or {}).get('parameters') or {}
+ print(s.get('step_index'), s.get('tool_name'), str(p.get('AbsolutePath') or p.get('TargetFile') or p.get('CommandLine') or '')[-90:])
+ if e.get('event')=='result': print('RESULT:', e['result'].get('response','')[:600])
+"
+```
+
+Pass criteria for each run: a `view_file` of `.../skills/using-superpowers/SKILL.md` and of `.../skills/brainstorming/SKILL.md` occur before any `write_to_file` outside the agy `brain/` directory, and no project files (`package.json`, `*.jsx`, `*.tsx`) exist in the workspace afterward. Record each run's tool sequence and the final response.
+
+Also confirm `grep -c 'failed to parse hooks' ~/.gemini/antigravity-cli/cli.log` did not increase across the runs.
+
+- [ ] **Step 3: Uninstall**
+
+```bash
+agy plugin uninstall superpowers
+agy plugin list
+```
+
+Expected: `No imported plugins.`
+
+- [ ] **Step 4: Report**
+
+If any run fails, stop and report to Jesse with the tool sequence; do not change the rule without his approval. If all pass, save the three transcripts' tool sequences for the PR description.
+
+---
+
+### Task 6: Porting guide (separate commit)
+
+**Files:**
+- Modify: `docs/porting-to-a-new-harness.md` (lines ~295, ~520-534, ~681, ~690-705, index table ~797-810)
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Routing table row (~line 295)**
+
+Replace:
+
+```markdown
+| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
+```
+
+with:
+
+```markdown
+| loads always-on rule files shipped inside a plugin | C via a plugin rule | Antigravity (`.antigravity-plugin/plugin.json` + `rules/AGENTS.md`, a one-line `@` pointer to `using-superpowers` — Part 6) |
+```
+
+- [ ] **Step 2: "No `Skill` tool" case (~lines 527-532)**
+
+Replace the paragraph beginning `**For the bootstrap itself, prefer a declared context file (Part 6).**` with:
+
+```markdown
+ **For the bootstrap itself, prefer something the harness loads every
+ session (Part 6).** That's a declared context file where the manifest has a
+ `contextFileName`-style field, or an always-on rule where the plugin format
+ has rules. Antigravity uses a rule: `rules/AGENTS.md` holds one line,
+ `@../skills/using-superpowers/SKILL.md`. agy rewrites a rule-relative `@`
+ path to the absolute install path but does not inline the file; the model
+ reads it with `view_file`. agy does not substitute `${PLUGIN_ROOT}` in rules.
+ Point at `using-superpowers`; never copy it into the rule.
+```
+
+- [ ] **Step 3: Distribution table row (~line 681)**
+
+Replace:
+
+```markdown
+| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |
+```
+
+with:
+
+```markdown
+| Git-URL plugin install + marketplace | Antigravity (`agy`) | Users run `agy plugin install https://github.com/obra/superpowers`. agy reads `.antigravity-plugin/plugin.json`, whose Marketplace fields (`displayName`, `logo`, `suggestedPrompts`, `version`, `author`) also drive the Antigravity Marketplace listing. Without that manifest, agy falls back to importing `gemini-extension.json`. |
+```
+
+- [ ] **Step 4: Installer-stripping section (~lines 690-705)**
+
+In the bullet beginning `**Ship a context file the manifest declares.**`, delete the sentences from `This is what` through `unrecognized.` (the `.antigravity-plugin/install.sh` / `ANTIGRAVITY.md` example), and replace them with:
+
+```markdown
+ **Verify with a marker** that the installer keeps the file and the
+ harness loads it: a file the manifest doesn't declare can be stripped as
+ unrecognized.
+```
+
+Immediately after that bullet, add a new bullet:
+
+```markdown
+ - **Or ship an always-on rule, if the plugin format has rules.** Antigravity
+ loads `rules/AGENTS.md` from an installed plugin every session; a one-line
+ `@` pointer there bootstraps `using-superpowers`. Run a marker test to
+ confirm what the harness does with `@` paths in rules — agy rewrites them
+ to absolute paths without inlining them.
+```
+
+- [ ] **Step 5: Harness index row (~line 799)**
+
+The table is alphabetical. Add this as the first data row, directly above `| Claude Code | ...`:
+
+```markdown
+| Antigravity (`agy`) | `.antigravity-plugin/plugin.json` + `rules/AGENTS.md` | always-on plugin rule `@`-points at `using-superpowers` (no session-start hook event exists) | `references/antigravity-tools.md` | `tests/antigravity/` | `agy plugin install` git URL; Antigravity Marketplace |
+```
+
+- [ ] **Step 6: Check nothing else references the phantom files**
+
+Run: `grep -rn 'install.sh\|ANTIGRAVITY.md\|contextFileName' docs/porting-to-a-new-harness.md`
+Expected: no remaining line ties `install.sh` or `ANTIGRAVITY.md` to Antigravity. Remaining `contextFileName` mentions must be generic or about Gemini.
+
+- [ ] **Step 7: Commit (on its own)**
+
+```bash
+git add docs/porting-to-a-new-harness.md
+git commit -m "docs(porting): describe Antigravity's rule bootstrap, drop phantom installer"
+```
diff --git a/docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md b/docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md
new file mode 100644
index 0000000..527a298
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md
@@ -0,0 +1,165 @@
+# Brainstorming rebuild: intent
+
+## Why this exists
+
+Coding agents are very good at building. They build what they believe the
+human wants, and they rarely ask enough or look around enough before they
+start. The brainstorming skill exists to close that gap: draw the human's
+real intent out of them, including the parts they haven't worked out yet,
+before anything gets built.
+
+The original superpowers prompt did this well in about forty words: "I've
+got an idea in my head. I'd like you to ask me lots of questions about it.
+As you think you understand what I really want, describe it to me in
+chunks of about 200-300 words. Once we're dialed in, write out an informal
+spec." The current skill has grown to about 2,600 words, almost all of it
+about routing (spike / bounded / architectural), approval gates, and the
+spec-to-plan handoff. Intent got squeezed into one paragraph whose default
+move is "ask one focused question about purpose", which doesn't work on
+people.
+
+This is a rewrite from scratch, not an edit.
+
+## Goals
+
+- The agent understands the *why* behind anything non-trivial, because an
+ agent that knows the why makes the hundred unstated decisions well.
+- The human ends up thinking through what they actually want. Good
+ questions help them flesh out an idea they haven't finished forming.
+- Works for any domain: software, a talk, a renovation, a small business.
+- Ends with a document a talented builder in that domain could plan from
+ without going back to the human.
+
+## How a session should feel
+
+**Start with a private check.** The agent asks itself: what do I actually
+know about what they want, and why? If the answer is "nearly everything"
+("make the icon cornflower blue"), it confirms and moves on. If anything
+non-trivial is missing, it starts asking.
+
+**Ask, one question at a time.** Plain language by default, pitched just a
+little above the human's level. Questions should help the human think, not
+quiz them.
+
+- Get them describing first. Open questions beat menus because menus
+ garden-path people toward the agent's assumptions.
+- Offer a menu only when they're struggling.
+- If they say "just guess" or "what do you think", always propose.
+- Ground questions in real moments ("walk me through the last time...")
+ and concrete tradeoffs ("if it could only do one of these well...").
+- Ask about prior art and current state: what exists elsewhere, what
+ exists now.
+- Ask which parts of the *how* they want to decide, and which they'd
+ rather hand to the builder.
+
+The ground to cover, loosely in order: what kind of thing this is, what
+makes it special, goals, non-goals, anti-goals, the details they care
+about, and what they want to delegate. These are territory, not a script.
+The agent never reads them out as literal questions.
+
+**Offer recon.** Once there's some grounding, the agent offers to go look:
+the codebase or project, the human's own files and data, or the web. The
+human decides whether it goes.
+
+**Show, don't tell, once things get concrete.** Use the visual companion
+for diagrams, mockups, and throwaway prototypes where seeing beats reading.
+
+**Spike to feel things out.** Agentic development is waterfall, but very,
+very fast. A quick throwaway build is often the cheapest way to find out
+what the human wants or whether something works, and the agent should
+offer one when it would help. When the human just wants to spike, the
+agent gets out of the way. Spikes have no tests or minimal ones, aren't
+bulletproof, and don't go through the full plan, implementation, and
+review process. What a spike teaches feeds back into the conversation.
+
+**Think wide internally.** Before proposing anything, the agent generates
+several ideas and discards the weak ones. It shows the human the comparison
+only when that helps them decide.
+
+**Play it back.** Once the agent thinks it understands, it describes its
+understanding in chunks of roughly 200-300 words and adjusts after each.
+
+## What it produces
+
+A plain written document covering:
+
+- intent and the why
+- goals, non-goals, anti-goals
+- constraints
+- the parts of the how the human cares about, as they decided them
+- what's explicitly left to the builder
+
+**Done test:** before the human reviews it, a fresh subagent playing a
+talented builder in the domain reads the document and lists what it would
+still need to ask. Those questions go back to the human. The document is
+done when the builder has nothing important left to ask.
+
+**Sizing the work.** Once intent is clear, the agent sorts the work into
+one of three sizes, says which out loud, and lets the human override:
+
+- **A quick, clear task.** Intent was clear from the start. Confirm and do it.
+- **A small change.** The full description lives in chat. No document file.
+- **A project with a written design.** The full description is the
+ document above, followed by a full plan (for software, the writing-plans
+ skill).
+
+This is where the old spike / bounded / architectural choice lives now:
+after intent, not before it, with plain names.
+
+**Approval.** Whatever the size, the human approves the full description
+before anything gets built: in chat for a small change, by reading the
+document for a project.
+
+**Opting out.** Early in the session, the agent mentions once that if the
+human doesn't want to go through this process, they can just say so.
+
+## Non-goals
+
+- Designing architecture the human didn't ask to decide. The doc records
+ the how the human cares about; the rest belongs to the builder.
+- Being software-specific.
+- Ceremony for trivial requests.
+
+## Anti-goals
+
+- Interrogation: a checklist of questions read at the human.
+- Garden-pathing: steering the human into the agent's preferred idea with
+ leading menus.
+- "What are you actually trying to do?" style questions that ask the human
+ to do the agent's thinking.
+- Small asks inflating into multi-phase projects.
+- Building before the human agrees with the playback.
+
+## Decisions
+
+- The skill keeps the name `brainstorming`. Other skills and the README
+ point at it.
+- The visual companion and its server scripts stay as they are.
+- `spec-document-reviewer-prompt.md` is replaced by the builder-check prompt.
+- The agent screens the builder check's questions before bringing them to
+ the human: it answers what it can from context and drops questions about
+ delegated details. Without a subagent tool, it runs the check itself.
+- A short hard gate stays: nothing gets built until the human approves the
+ full description. One exception: a spike the human said yes to. It stays
+ labeled throwaway. Keeping what it produced is a new request and goes
+ through the gate.
+- The builder check runs only on the written document. Small changes stay
+ in chat.
+- The trigger description keeps the strong "use before any creative work"
+ wording. The opening check keeps trivial asks cheap.
+- The todo-list example from the old skill goes. The evals that encode the
+ old routing (`brainstorming-todo-purpose-discovery`,
+ `brainstorming-todo-shared-intent`) get rewritten to match.
+- Software projects keep `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+ as the default location for the document.
+
+## Left to the builder
+
+- Section structure and wording of the skill.
+- Exact prompts for the builder check.
+- Where non-software documents get saved, absent a human preference.
+
+## Will be tuned after first use
+
+Jesse expects to tune the skill after real sessions. Ship something small
+and sharp rather than complete.
diff --git a/docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md b/docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md
new file mode 100644
index 0000000..aab6ad2
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md
@@ -0,0 +1,181 @@
+# Antigravity Marketplace plugin
+
+## Goal
+
+List Superpowers in the Google Antigravity plugin Marketplace, as part of a
+partnership with Google. That requires a native Antigravity plugin manifest with
+the Marketplace presentation fields, a logo, and a session bootstrap that works
+on the native plugin path.
+
+Source: "Antigravity Plugin Marketplace Publishing Guide" (PDF from Google), plus
+probes against `agy` 1.3.1 recorded below.
+
+## Current state (agy 1.3.1)
+
+- `agy plugin install https://github.com/obra/superpowers` succeeds, but only
+ through agy's Gemini-extension fallback: `agy plugin list` reports
+ `"source": "gemini-cli"`. The bootstrap rides `GEMINI.md`'s `@` lines, which
+ the model treats as hints and follows with `view_file`. The acceptance test
+ passes on this path.
+- agy copies our Claude-format `hooks/hooks.json` to the install root as
+ `hooks.json` and fails to parse it on every session:
+ `invalid hook "hooks": command hook must specify 'command'`.
+- `agy plugin validate .` on the repo fails: `missing plugin.json`.
+
+## Probe findings (agy 1.3.1)
+
+Each probe installed a throwaway plugin, ran `agy -p`, and uninstalled it.
+
+1. agy's hook events are `PreToolUse`, `PostToolUse`, `PreInvocation`,
+ `PostInvocation`, and `Stop`. There is no `SessionStart`. agy's embedded docs
+ use named top-level hooks (`{"<name>": {"PreToolUse": [...]}}`), which differs
+ from the PDF's `{"hooks": {...}}` example.
+2. `rules/AGENTS.md` in a plugin loads as an always-on rule on every session.
+3. In a rule, an `@` path relative to the rule file is rewritten to an absolute
+ install path (`@../skills/x/SKILL.md` becomes
+ `@/Users/<u>/.gemini/config/plugins/<plugin>/skills/x/SKILL.md`). Its content
+ is not inlined. `${PLUGIN_ROOT}` is not substituted in rules. A path that does
+ not resolve relative to the rule file is left as written.
+4. With `.antigravity-plugin/plugin.json` present, agy installs the plugin as
+ `"source": "antigravity"`, finds all 15 skills, and skips hooks (no root
+ `hooks.json`), so the parse warning goes away.
+5. A staged copy of the repo with the native manifest and a one-line
+ `rules/AGENTS.md` (`@../skills/using-superpowers/SKILL.md`) passed the
+ acceptance test: the model read `using-superpowers`, then
+ `antigravity-tools.md`, then `brainstorming`, and replied
+ "Using superpowers:brainstorming…" with a clarifying question. No code.
+6. The repo-root `AGENTS.md` (contributor guidelines) is copied into the install
+ but is not loaded as a rule. Only `rules/AGENTS.md` is.
+
+## Design
+
+### 1. Native manifest: `.antigravity-plugin/plugin.json`
+
+The guide allows the manifest at `.antigravity-plugin/plugin.json`, which
+matches our other harness dotdirs. Fields:
+
+| Field | Value |
+|---|---|
+| `name` | `superpowers` |
+| `displayName` | `Superpowers` |
+| `version` | current release version, maintained by `.version-bump.json` |
+| `description` | `Make your coding agent a better engineer` (Jesse's copy; shorter than the guide's recommended 120–160, at most 160) |
+| `logo` | `assets/antigravity-logo.png` |
+| `suggestedPrompts` | `I've got an idea for something I'd like to build`, `Let's figure out why this broke` (Jesse's copy) |
+| `category` | `Developer Tools` |
+| `keywords` | lowercase, matching `.claude-plugin/plugin.json` keywords |
+| `author` | `{ "name": "Jesse Vincent", "email": "jesse@fsck.com" }`, matching `.claude-plugin/plugin.json` |
+| `homepage`, `repository` | `https://github.com/obra/superpowers` |
+| `license` | `MIT` |
+
+No `skills` or `mcpServers` fields: the defaults (`skills/`, no MCP config) are
+what we want, and probe 4 confirmed default discovery finds all skills.
+
+
+### 2. Bootstrap: skill discovery, no extra files
+
+agy lists each installed skill's description, and `using-superpowers`'
+"Use when starting any conversation" gets the model to load it. The plugin
+ships no `rules/` and no `hooks.json`.
+
+This replaced a first design, a one-line `rules/AGENTS.md` pointer, after the
+final review found that Cursor also loads any `rules/*.md` a plugin ships from
+the same repo root. Alternatives probed on agy 1.3.1 and rejected:
+
+- A `PreInvocation` hook. It runs before every model call and `hooks.json`
+ must sit at the plugin root. An `ephemeralMessage` is dropped on the next
+ call; a `userMessage` persists, and gating it on `invocationNum == 0` and
+ `initialNumSteps == 1` injects exactly once per conversation, but agy still
+ starts the hook process on every call.
+- No manifest field relocates `hooks.json` or `rules/`.
+
+Verified with no bootstrap file, 12/12 runs: "Let's make a react todo list"
+(3) and "add a settings page" (3) load brainstorming before any code; "this
+test is failing, can you fix it?" (3) loads systematic-debugging before any
+edit; a react-todo second turn after an unrelated first turn (3) loads
+brainstorming. Model: Gemini 3.8 Flash. The risk is that triggering depends on
+the model honoring a skill description; the once-per-conversation hook is the
+fallback if it slips.
+
+### 3. Logo: `assets/antigravity-logo.png`
+
+512×512 PNG, transparent background. A white rounded square (inset 31px,
+corner radius 100) holds the `assets/superpowers-small.svg` mark in `#1a1a1a`,
+scaled to about 70% of the square's width and centered. No border; on a light
+theme it reads as a bare mark on white, which is acceptable.
+
+`scripts/render-antigravity-logo.sh` composes the SVG from
+`superpowers-small.svg` and rasterizes it with `rsvg-convert`. It is the only way
+the PNG gets regenerated; it has help text and fails clearly when
+`rsvg-convert` is missing.
+
+### 4. Version bumps
+
+Add `{ "path": ".antigravity-plugin/plugin.json", "field": "version" }` to
+`.version-bump.json`.
+
+### 5. Codex sync
+
+Add `/.antigravity-plugin/` and `/assets/antigravity-logo.png` to
+`EXCLUDES` in `scripts/sync-to-codex-plugin.sh`, and cover them in
+`tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`.
+
+### 6. README
+
+The Antigravity install command stays
+`agy plugin install https://github.com/obra/superpowers`. The prose changes from
+"runs the plugin's session-start hook" to describing skill discovery. Add the
+Marketplace route once it exists; until then, no claim about it.
+
+### 7. Tests: `tests/antigravity/`
+
+- `test-plugin-manifest.sh` (CI-safe, mirrors `tests/kimi/test-plugin-manifest.sh`):
+ - manifest parses; `name` matches the kebab-case pattern and equals
+ `superpowers`;
+ - every Marketplace-required field is present and non-empty: `name`,
+ `description`, `displayName`, `logo`, `suggestedPrompts` (1–3 non-empty
+ strings), `version`, `author`;
+ - `description` is at most 160 characters;
+ - `version` equals `.claude-plugin/plugin.json`'s version;
+ - `logo` file exists, is a PNG, and is square and at least 128×128;
+ - `.version-bump.json` lists the manifest;
+ - `using-superpowers`' description still says "Use when starting any
+ conversation", which the bootstrap relies on;
+ - no root `plugin.json`, `hooks.json`, or `rules/` exists.
+- When `agy` is on `PATH`, also run `agy plugin validate` on the repo and
+ require `[ok]` with skills processed.
+- Update the header comment of `test-antigravity-tools.sh`, which still says agy
+ runs the SessionStart hook.
+
+Live acceptance (not in CI): install the branch's tree into agy, run
+"Let's make a react todo list" at least three times in clean workspaces, and
+require that brainstorming triggers before any code each time. Uninstall
+afterward.
+
+### 8. Porting guide: separate commit
+
+`docs/porting-to-a-new-harness.md` describes `.antigravity-plugin/install.sh`
+and a generated `ANTIGRAVITY.md` that do not exist. Fix it in its own commit:
+
+- Routing table row: Antigravity uses the surfaced skill index.
+- The "no `Skill` tool" section: replace the `contextFileName` advice for
+ Antigravity with the skill-index bootstrap, and record the hook and rule
+ findings (no session-start event, `PreInvocation` per call, no
+ `${PLUGIN_ROOT}` in hooks, shared plugin roots leak `rules/` into Cursor).
+- The distribution table: Antigravity installs from a git URL (`agy plugin
+ install <url>`) and lists in its Marketplace.
+- The installer-stripping section: drop the `install.sh` / `ANTIGRAVITY.md`
+ example.
+- The harness index table has no Antigravity row; add one (manifest,
+ bootstrap, tool mapping, tests, install).
+
+## Out of scope
+
+- Marketplace submission mechanics. The guide does not describe how to submit;
+ that goes through Jesse's Google contact.
+- Antigravity 2.0 and the IDE. Not installed here, so not verified. The README
+ makes no claims about them.
+- Open PR #2350, which copies `using-superpowers` into a generated rule. Jesse
+ decides how to respond after this lands; I draft the reply.
+- `.hermes-plugin/` and `.muse-plugin/` are missing from the Codex sync
+ excludes. Unrelated; noted for a separate fix.
diff --git a/docs/windows/polyglot-hooks.md b/docs/windows/polyglot-hooks.md
index d1bcb84..3da01ae 100644
--- a/docs/windows/polyglot-hooks.md
+++ b/docs/windows/polyglot-hooks.md
@@ -77,12 +77,19 @@ afterward.
1. The batch section validates the script name and resolves the hook directory
from the dispatcher's own location.
-2. It tries bash in three places:
+2. It tries bash in four places, in order:
- `C:\Program Files\Git\bin\bash.exe`
- `C:\Program Files (x86)\Git\bin\bash.exe`
- - `bash` on `PATH` (MSYS2, Cygwin, or a non-default Git install)
+ - `%LOCALAPPDATA%\Programs\Git\bin\bash.exe` (a per-user Git for Windows
+ install), only when `LOCALAPPDATA` is set
+ - `bash` on `PATH` (MSYS2, Cygwin, or a non-default Git install), found by
+ running `%SystemRoot%\System32\where.exe $PATH:bash`, so neither `where`
+ nor `bash` is taken from the current directory. The WSL launchers
+ (`bash.exe` in `System32`, `Sysnative`, or
+ `%LOCALAPPDATA%\Microsoft\WindowsApps`) and extensionless matches are
+ skipped, since the launchers fail when no Linux distro is installed.
3. If bash is found, it runs the named extensionless hook script from the hooks
- directory.
+ directory and exits with the script's exit code.
4. If no bash is found, the dispatcher exits `0` silently — the plugin
continues working, it just skips the hook.
5. `exit /b` stops CMD before it reaches the Unix section.
@@ -142,7 +149,7 @@ escape_for_json() {
### "bash is not recognized"
-CMD couldn't find bash in any of the three locations the dispatcher tries. The dispatcher exits silently (0) rather than erroring, so the hook is skipped. Install Git for Windows at the standard path or ensure `bash` is on `PATH`.
+CMD couldn't find bash in any of the four locations the dispatcher tries. The dispatcher exits silently (0) rather than erroring, so the hook is skipped. Install Git for Windows (system-wide or per-user) or ensure a non-WSL `bash` is on `PATH`.
### Hook runs on Unix but does nothing on Windows
diff --git a/gemini-extension.json b/gemini-extension.json
index 915bfd2..878b94a 100644
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "6.4.2",
+ "version": "7.0.0",
"contextFileName": "GEMINI.md"
}
diff --git a/hooks/run-hook.cmd b/hooks/run-hook.cmd
index ceec3a7..a2f7c48 100755
--- a/hooks/run-hook.cmd
+++ b/hooks/run-hook.cmd
@@ -15,32 +15,48 @@ if "%~1"=="" (
exit /b 1
)
+setlocal
set "HOOK_DIR=%~dp0"
+set "BASH_EXE="
-REM Try Git for Windows bash in standard locations
-if exist "C:\Program Files\Git\bin\bash.exe" (
- "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
- exit /b %ERRORLEVEL%
-)
-if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
- "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
- exit /b %ERRORLEVEL%
-)
+REM Git for Windows in its standard system-wide locations
+if exist "C:\Program Files\Git\bin\bash.exe" set "BASH_EXE=C:\Program Files\Git\bin\bash.exe"
+if not defined BASH_EXE if exist "C:\Program Files (x86)\Git\bin\bash.exe" set "BASH_EXE=C:\Program Files (x86)\Git\bin\bash.exe"
-REM Try bash on PATH (e.g. user-installed Git Bash, MSYS2, Cygwin)
-where bash >nul 2>nul
-if %ERRORLEVEL% equ 0 (
- bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
- exit /b %ERRORLEVEL%
-)
+REM Per-user Git for Windows install (no admin rights needed). The defined
+REM check matters: with LOCALAPPDATA unset the path would collapse to
+REM \Programs\Git\... on the current drive, where any user can create it.
+if not defined BASH_EXE if defined LOCALAPPDATA if exist "%LOCALAPPDATA%\Programs\Git\bin\bash.exe" set "BASH_EXE=%LOCALAPPDATA%\Programs\Git\bin\bash.exe"
+
+REM bash on PATH (MSYS2, Cygwin, a non-default Git install). where.exe is
+REM called by full path and with $PATH: so neither it nor bash can come from
+REM the current directory. The filters use for-variable modifiers, which never
+REM re-expand the path, and skip extensionless matches and the WSL launchers
+REM (System32, Sysnative, the Store alias in WindowsApps), which fail when no
+REM Linux distro is installed.
+if not defined BASH_EXE if defined SystemRoot for /f "delims=" %%B in ('"%SystemRoot%\System32\where.exe" $PATH:bash 2^>nul') do if not defined BASH_EXE if not "%%~xB"=="" if /i not "%%~dpB"=="%SystemRoot%\System32\" if /i not "%%~dpB"=="%SystemRoot%\Sysnative\" if /i not "%%~dpB"=="%LOCALAPPDATA%\Microsoft\WindowsApps\" set "BASH_EXE=%%B"
REM No bash found - exit silently rather than error
REM (plugin still works, just without SessionStart context injection)
-exit /b 0
+if not defined BASH_EXE exit /b 0
+
+REM Run bash outside any parenthesized block: cmd expands %ERRORLEVEL%
+REM inside a block when it parses the block, which would lose the hook's
+REM exit code.
+"%BASH_EXE%" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
CMDBLOCK
# Unix: run the named script directly
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# Splits $0 on its last / or \ (cmd passes Windows paths) instead of calling
+# dirname, and uses $BASH (bash's own absolute path, always set once bash is
+# running) instead of a PATH lookup for bash, so this keeps working when
+# Claude Code spawns the SessionStart hook with a broken/empty PATH
+# (anthropics/claude-code#43127).
+case "$0" in
+ */*|*\\*) SCRIPT_DIR="$(cd "${0%[/\\]*}" && pwd)" ;;
+ *) SCRIPT_DIR="$(pwd)" ;;
+esac
SCRIPT_NAME="$1"
shift
-exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
+exec "${BASH:-bash}" "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
diff --git a/hooks/session-start b/hooks/session-start
index 083cb23..63f82a6 100755
--- a/hooks/session-start
+++ b/hooks/session-start
@@ -3,12 +3,26 @@
set -euo pipefail
-# Determine plugin root directory
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# Determine plugin root directory.
+# Splits $0 on its last / or \ (run-hook.cmd's cmd half passes a Windows
+# path), with no separator meaning the current directory. This avoids
+# dirname because a SessionStart:startup hook can run with a broken/empty
+# PATH (anthropics/claude-code#43127) before any PATH-repairing sibling hook
+# in the same startup batch takes effect.
+case "$0" in
+ */*|*\\*) SCRIPT_DIR="$(cd "${0%[/\\]*}" && pwd)" ;;
+ *) SCRIPT_DIR="$(pwd)" ;;
+esac
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-# Read using-superpowers content
-using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
+# Read using-superpowers content via bash's builtin $(< file) instead of
+# cat, for the same PATH-independence reason.
+skill_md="${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md"
+if [ -r "$skill_md" ]; then
+ using_superpowers_content="$(<"$skill_md")"
+else
+ using_superpowers_content="Error reading using-superpowers skill"
+fi
# Escape string for JSON embedding using bash parameter substitution.
# Each ${s//old/new} is a single C-level pass - orders of magnitude
@@ -36,18 +50,36 @@ session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the
#
# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
# See: https://github.com/obra/superpowers/issues/571
+#
+# emit_json pipes printf through `cat` when cat is on PATH, to absorb EPIPE
+# on Windows. On Windows + Git Bash, the harness can close the hook's stdout
+# before printf finishes, and Git Bash's printf reports that EPIPE as
+# "printf: write error: Permission denied", which `set -euo pipefail` lets
+# escape as a startup diagnostic every session. Letting cat receive the EPIPE
+# keeps it out of the hook's error path (#1612). When PATH is broken and cat
+# can't be found (#2310), it falls back to printf alone so context still
+# gets injected.
+emit_json() {
+ # shellcheck disable=SC2059 # every caller passes a literal format string
+ if command -v cat >/dev/null 2>&1; then
+ printf "$@" | cat
+ else
+ printf "$@"
+ fi
+}
+
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
# Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT)
- printf '{\n "additional_context": "%s"\n}\n' "$session_context" | cat
+ emit_json '{\n "additional_context": "%s"\n}\n' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ] && [ -z "${MUSE_PLUGIN_ROOT:-}" ]; then
# Claude Code sets CLAUDE_PLUGIN_ROOT without COPILOT_CLI/MUSE_PLUGIN_ROOT
- printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context" | cat
+ emit_json '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context"
elif [ -n "${MUSE_PLUGIN_ROOT:-}" ]; then
# Muse sets MUSE_PLUGIN_ROOT — try Claude-style nested output for Muse Spark
- printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context" | cat
+ emit_json '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context"
else
# Copilot CLI (sets COPILOT_CLI=1) or unknown platform — SDK standard format
- printf '{\n "additionalContext": "%s"\n}\n' "$session_context" | cat
+ emit_json '{\n "additionalContext": "%s"\n}\n' "$session_context"
fi
exit 0
diff --git a/package.json b/package.json
index d9339ad..1dc53c2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "6.4.2",
+ "version": "7.0.0",
"description": "Superpowers skills and runtime bootstrap for coding agents",
"type": "module",
"main": ".opencode/plugins/superpowers.js",
diff --git a/scripts/bump-version.sh b/scripts/bump-version.sh
index 14ead00..2f3acee 100755
--- a/scripts/bump-version.sh
+++ b/scripts/bump-version.sh
@@ -188,7 +188,9 @@ cmd_audit() {
declared_paths+=("$path")
done < <(declared_files)
- # Grep for the version string
+ # Grep for the version string, but not inside a longer number such as an
+ # IP address; a "v" prefix or surrounding quotes still match.
+ local version_pattern="(^|[^0-9.])${current_version//./\\.}([^0-9]|$)"
local found_undeclared=0
while IFS= read -r match; do
local match_file
@@ -212,7 +214,7 @@ cmd_audit() {
fi
echo " $match"
fi
- done < <(grep -rn "${exclude_args[@]}" -F "$current_version" "$REPO_ROOT" 2>/dev/null || true)
+ done < <(grep -rnE "${exclude_args[@]}" "$version_pattern" "$REPO_ROOT" 2>/dev/null || true)
if [[ "$found_undeclared" -eq 0 ]]; then
echo "No undeclared files contain the version string. All clear."
diff --git a/scripts/render-antigravity-logo.sh b/scripts/render-antigravity-logo.sh
new file mode 100755
index 0000000..82a5bd8
--- /dev/null
+++ b/scripts/render-antigravity-logo.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#
+# Render the Antigravity Marketplace logo from assets/superpowers-small.svg.
+#
+# Usage:
+# scripts/render-antigravity-logo.sh [--output PATH]
+#
+# Draws the Superpowers mark in near-black on a white rounded square with
+# transparent corners, 512x512 PNG. Run it whenever superpowers-small.svg
+# changes; tests/antigravity/test-logo.sh fails if the committed PNG is stale.
+# Requires rsvg-convert (Homebrew: librsvg).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SOURCE_SVG="$REPO_ROOT/assets/superpowers-small.svg"
+OUTPUT="$REPO_ROOT/assets/antigravity-logo.png"
+
+usage() {
+ sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+die() {
+ echo "error: $*" >&2
+ exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --output)
+ [[ $# -ge 2 ]] || die "--output needs a path"
+ OUTPUT="$2"
+ shift 2
+ ;;
+ -h | --help)
+ usage
+ exit 0
+ ;;
+ *)
+ usage >&2
+ die "unknown argument: $1"
+ ;;
+ esac
+done
+
+command -v rsvg-convert >/dev/null 2>&1 \
+ || die "rsvg-convert is not on PATH (install librsvg, e.g. 'brew install librsvg')"
+[[ -r "$SOURCE_SVG" ]] || die "source mark not readable: $SOURCE_SVG"
+
+# Everything inside the source <svg> element: the mark's paths and ellipse.
+mark="$(sed -E 's/^.*<svg[^>]*>//; s#</svg>.*$##' "$SOURCE_SVG")"
+[[ -n "$mark" ]] || die "could not extract the mark from $SOURCE_SVG"
+
+# The mark's bounding box is centered at (256,256) in its 512 viewBox and is
+# 348 units wide; scale 0.905 makes it ~70% of the 450-unit rounded square.
+composed="$(mktemp)"
+trap 'rm -f "$composed"' EXIT
+cat >"$composed" <<EOF
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+ <rect x="31" y="31" width="450" height="450" rx="100" ry="100" fill="#ffffff"/>
+ <g fill="#1a1a1a" transform="translate(256 256) scale(0.905) translate(-256 -256)">$mark</g>
+</svg>
+EOF
+
+rsvg-convert -w 512 -h 512 "$composed" -o "$OUTPUT"
+echo "wrote $OUTPUT"
diff --git a/scripts/sync-to-codex-plugin.sh b/scripts/sync-to-codex-plugin.sh
index 8ff283a..fc80ab2 100755
--- a/scripts/sync-to-codex-plugin.sh
+++ b/scripts/sync-to-codex-plugin.sh
@@ -44,6 +44,7 @@ DEST_REL="plugins/superpowers"
# (.DS_Store is intentionally unanchored — Finder creates them everywhere.)
EXCLUDES=(
# Dotfiles and infra — top-level only
+ "/.antigravity-plugin/"
"/.claude/"
"/.claude-plugin/"
"/.codex/"
@@ -80,6 +81,9 @@ EXCLUDES=(
"/scripts/"
"/tests/"
"/tmp/"
+
+ # Other harnesses' assets
+ "/assets/antigravity-logo.png"
)
# =============================================================================
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md
index e3f1788..22b98fc 100644
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -1,285 +1,225 @@
---
name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation)."
---
-# Brainstorming Ideas Into Designs
+# Brainstorming
+
+You are very good at building. You build what you believe your human
+partner wants, and that belief is usually thinner than it feels. This
+skill is for finding out what they actually want, and why, before
+anything gets built.
+
+People often haven't finished working out what they want. Good questions
+help them think it through. When you understand the why, you make the
+hundred decisions they never mention the way they would have made them.
+
+## First: What Do You Actually Know?
+
+Before you reply, ask yourself: what do I know about what they want, and
+why?
+
+- **Everything that matters is in the request** ("make the icon cornflower
+ blue"). This is a quick, clear task. Do it, and say what you did.
+- **Something non-trivial is missing.** Start the conversation.
+
+## Your First Message
+
+Your first message is two things, in this order:
+
+1. One line letting them know that if they'd rather skip the questions and
+ have you just start, they can say so. If they take you up on it, this
+ skill is done: state any significant how-it-gets-made choice
+ (platform, language, medium) in one plain line, then do what they
+ asked through the normal workflow.
+2. One open question that gets them describing. Ask about a real moment
+ or a concrete picture: "What's the moment you find yourself wishing
+ this existed?" or "Tell me about the people who'll be in the room."
+
+That's the whole message.
+
+## The Conversation
+
+Each message ends with one question: a single sentence with no list of
+example answers hanging off it. Use plain language, pitched just a little
+above where your human partner is. Match their vocabulary; never use
+process jargon.
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+Be clear and concise. Lead with what matters. Avoid jargon. When you
+report what you found, give them the most important findings and offer
+the rest.
-Start by classifying how much process the request needs, then work
-through your path: understand the context, refine the idea, present a
-design, and get your human partner's approval.
-
-## Establish Shared Understanding
-
-The outcome of brainstorming is an understanding your human partner can
-recognize and correct, grounded in what they want to accomplish.
-
-1. **Discover intent.** Use the request and available context to identify
- the intended outcome, who it is for, and what success looks like. When
- that information is missing, ask one focused question about purpose or
- intended use before proposing features or an approach. Knowing the app
- genre does not tell you why your partner wants it. Gathering missing
- requirements does not ask them to authorize the task again.
-2. **Write back your understanding.** Summarize the intended outcome,
- relevant constraints, and success criteria in a short note your partner
- can assess. Separate what they said from assumptions. Invite correction
- and incorporate their answer before treating this as the design brief.
-3. **Carry intent into the design.** Preserve the agreed understanding in
- the selected path's design artifact: the written spec for architectural
- work, or the in-chat design/probe for bounded work and spikes. Check
- proposed features and technical choices against that understanding.
-
-When the request already supplies the purpose and constraints, reflect
-that understanding instead of asking the same questions again. Keep the
-note concise; its accuracy and the opportunity to correct it matter.
+**Get them describing.** Open questions come first. Their own words carry
+intent that your options can't. Offer a short menu only when they're
+stuck. When they say "just guess" or "what do you think?", propose
+something concrete.
+
+**How it gets made.** Every project rests on choices about medium, tools,
+materials, and resources: the platform, programming language, and
+libraries for an app; the medium for a piece of art. Find out early which
+of those choices they want to make, which they're handing to you, and what
+they already have to work with. Someone with strong views or skills will
+want to talk it through. Someone counting on you needs sensible defaults,
+said in plain words. When there's existing work, build on what it already
+uses. Any choice you make goes in the design as your call, never as
+something they agreed to.
+
+**Ground to cover.** This is territory, not a script. Never read these
+out as questions:
+
+- what kind of thing this is, and what makes it special
+- why now, and what success looks like to them
+- goals, non-goals, and anti-goals (what would make this a failure even
+ if it technically works)
+- prior art: what they've seen elsewhere, loved or hated
+- current state: what exists now, what they've tried
+- the details they care about
+
+**Questions that work** anchor in specifics: "Walk me through the last
+time...", "If it could only do one of these well, which?", "What would
+make you wince if I got it wrong?" A guess they can correct ("I'm
+guessing this is because X keeps biting you?") often beats a question.
+
+**Offer recon.** Once you have a bit of grounding and looking would help,
+offer to go look: their codebase or project, their own files and data,
+or the web. Say what you'd look for. They decide whether you go.
+
+**Think wide privately.** Before you propose anything, come up with
+several ideas and drop the weak ones, including any that fight what
+they've told you about why. Show the comparison only when it helps them
+decide.
+
+**Show, don't tell.** Offer the visual companion (below) whenever seeing
+would help more than reading:
+
+- something they'll look at: a screen, a page, a printout, a sign
+- a layout or arrangement: of a screen, a room, a schedule
+- a flow or a sequence of steps
+- options that would look different from each other
+- a structure that's easier to see than read: a diagram, a timeline, a map
+
+Once they've accepted, use it for mockups to react to, side-by-side
+options, and throwaway prototypes they can click.
+
+**Spike to feel things out.** Agentic work is waterfall, but very, very
+fast. A quick throwaway build is often the cheapest way to learn what
+they want or whether something works. Offer one when it would help.
+When they just want to spike, get out of the way. Spikes get no tests
+or minimal ones, aren't bulletproof, and skip the plan, implementation,
+and review process. Bring what the spike taught you back into the
+conversation.
+
+## Play It Back
+
+Play back as you go. As soon as you understand one part well enough to
+describe it (what it's for and who it serves, say, or how one piece
+behaves), describe that part back in about 200-300 words, then return to
+questions about the next part. Playback and questions alternate through
+the whole conversation; the last chunk covers whatever is left.
+
+Mark anything you're guessing as your guess; only what they said goes in
+as theirs. End each chunk by asking what's wrong or missing.
+
+Before you send a chunk, check it: does it describe something they'll
+look at, like a page, a screen, a schedule, or a printout? If so, and
+they haven't seen the visual companion offer yet, send the offer instead
+(its own message, below) and hold the chunk for the next message. Once
+they've accepted, put a mockup next to the description.
+
+## Size the Work
+
+Once you understand what they want, pick a size and say it in plain
+words. They can override it.
+
+| Size | The full description | Then |
+|------|----------------------|------|
+| A quick, clear task | the request itself | do it |
+| A small change | in chat | build it through the normal workflow |
+| A project with a written design | a written design document | a full plan (for software: superpowers:writing-plans) |
+
+If it grows mid-task, stop, say so, and step up a size.
+
+If this is really several independent projects, say so, agree on an
+order, and brainstorm them one at a time.
+
+## The Written Design
+
+For a project, write a plain document a talented builder in the domain
+could plan from without going back to your human partner. Cover:
+
+- intent and the why
+- goals, non-goals, anti-goals
+- constraints
+- the parts of the how they decided, as they decided them
+- what's left to the builder
+
+**Where it goes:** in a software repo,
+`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed.
+Otherwise, ask. Your human partner's preferences override both.
+
+**Builder check:** dispatch a fresh subagent with
+`builder-check-prompt.md` in this directory. When you tell your human
+partner you're writing it up, say a reviewer will read it first and you
+may come back once with a few questions. Don't hand over the document
+until the check is back. Sort what the builder asks into three piles:
+
+- **Answered already** by the conversation or the project: put the answer
+ in the document.
+- **Minor:** a sensible builder could settle it without changing what gets
+ built. Settle it yourself and mark it in the document as your call.
+- **Theirs:** only your human partner can answer it, and the answer changes
+ what gets built.
+
+Bring the "theirs" pile in one message, most important first. Update the
+document with their answers, then hand it over with a short list of the
+calls you made so they can check those while reading. That's the only
+round of questions the check produces. Without a subagent tool, read the
+document as that builder yourself.
<HARD-GATE>
-Before taking any implementation action, including invoking an
-implementation skill, writing product code, scaffolding, installing
-product dependencies, or creating an external project, complete the
-selected path's prerequisites:
-
-- Spike: the human partner approves the question and probe.
-- Bounded: the human partner approves the short in-chat design.
-- Architectural: the human partner reviews and approves the written spec,
- then reviews the written implementation plan and selects its execution
- method. Conversational design approval only permits writing the spec;
- written-spec approval only permits invoking writing-plans.
-
-A reply approves the stage actually presented. Approval of an idea or
-feature scope does not approve artifacts that do not exist yet. Resume
-at the earliest incomplete stage; do not turn one approval into permission
-to skip the rest of the selected path. Read-only project exploration is
-allowed while those prerequisites remain incomplete.
+Nothing gets built until your human partner approves the full
+description: in chat for a small change, the document for a project.
+Building includes writing product code, scaffolding, installing
+dependencies, creating projects, and invoking an implementation skill.
+Reading and exploring are fine.
+
+Two exceptions. If they opted out of the questions, the skill is done
+and the gate goes with it. A spike they said yes to may be built; it
+stays labeled throwaway, and keeping what it produced is a new request
+that comes back through this gate.
+
+After a project's document is approved, the next step is the plan. For
+software, invoke superpowers:writing-plans and no other skill.
</HARD-GATE>
-## Three Paths
-
-Before your first question, classify the request and say the
-classification out loud — "this looks bounded, so I'll present a short
-design here rather than write a spec" — so your human partner can
-override it:
-
-- **Spike** — a feasibility question ("can we...", "is it possible...",
- "quick and dirty is fine") whose output is an answer, not code you
- keep. Present the question and what you'll try in 2-3 sentences, get
- a nod, then find out as cheaply as correctness allows. No design
- doc, no spec file. Report findings as a recommendation; anything you
- built stays labeled throwaway.
-- **Bounded** — a well-scoped change to code that already exists in
- this repo: a new flag, a small endpoint, a one-file fix.
- Understanding the kind of app is not enough — bounded means the flow
- you are changing is already here to read. If there is no existing
- flow to change, the task is not bounded. Ask the clarifying
- questions that matter, present a short design IN CHAT (a few
- sentences to a few short paragraphs), and STOP. Implementation
- starts only after your human partner says yes to that design — a
- bounded task's approval is as hard a gate as an architectural
- one. No spec file, no implementation plan document.
-- **Architectural** — new projects, new subsystems, changes that
- restructure how components fit together or alter interfaces others
- depend on. Follow the full process: questions, approaches, sectioned
- design, written spec, then the writing-plans skill.
-
-When in doubt between two paths, take the heavier one. The ratchet is
-one-way: hidden complexity discovered mid-task upgrades the path —
-stop, say so, and step up. Nothing downgrades mid-task.
-
-## Anti-Pattern: "Too Simple To Need Approval"
-
-Every path ends with your human partner approving the required design
-before implementation. A bounded change may need only two sentences in
-chat. A new todo-list project is architectural and requires the written
-spec and planning handoffs. Scale the artifact to the selected path;
-complete that path's reviews before implementation.
-
## Red Flags
| Thought | Reality |
|---------|---------|
-| "This is too simple to need a design" | Follow the selected path: a bounded change gets a short chat design; an architectural change gets the written spec and planning handoffs. |
-| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
-| "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
-| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
-| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. |
-| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
-| "They approved the spike, so the follow-up change is approved too" | Each task gets its own classification and its own approval. |
-
-## Checklist
-
-Classify first, announce the path, then create a task for each item on
-your path and complete them in order.
-
-**Spike:**
-1. **Explore project context** — enough to frame the probe
-2. **Present question + probe plan** — 2-3 sentences
-3. **Get approval** — a nod is enough
-4. **Investigate** — as cheaply as correctness allows
-5. **Report findings** — a recommendation; label anything built as throwaway
-
-**Bounded:**
-1. **Explore project context** — check files, docs, recent commits
-2. **Ask clarifying questions** — one at a time, the ones that matter
-3. **Present short design in chat** — approach, files touched, testing
-4. **Get approval** — STOP and wait for an explicit yes; presenting the design and starting in the same breath is skipping the gate
-5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document
-
-**Architectural:**
-1. **Explore project context** — check files, docs, recent commits
-2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below.
-3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
-4. **Propose 2-3 approaches** — with trade-offs and your recommendation
-5. **Present design** — in sections scaled to their complexity, get user approval after each section
-6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
-7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
-8. **User reviews written spec** — ask user to review the spec file before proceeding
-9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
-
-## Process Flow
-
-```dot
-digraph brainstorming {
- "Classify: spike / bounded / architectural" [shape=diamond];
- "Present question + probe (2-3 sentences)" [shape=box];
- "Ask clarifying questions (bounded)" [shape=box];
- "Present short design in chat" [shape=box];
- "Human approves?" [shape=diamond];
- "Investigate; report recommendation" [shape=doublecircle];
- "Implement via normal workflow (no plan doc)" [shape=doublecircle];
- "Explore project context" [shape=box];
- "Ask clarifying questions" [shape=box];
- "Propose 2-3 approaches" [shape=box];
- "Present design sections" [shape=box];
- "User approves design?" [shape=diamond];
- "Write design doc" [shape=box];
- "Spec self-review\n(fix inline)" [shape=box];
- "User reviews spec?" [shape=diamond];
- "Invoke writing-plans skill" [shape=doublecircle];
- "Hidden complexity? Upgrade path" [shape=box];
-
- "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
- "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"];
- "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"];
- "Present question + probe (2-3 sentences)" -> "Human approves?";
- "Ask clarifying questions (bounded)" -> "Present short design in chat";
- "Present short design in chat" -> "Human approves?";
- "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"];
- "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"];
- "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural";
- "Explore project context" -> "Ask clarifying questions";
- "Ask clarifying questions" -> "Propose 2-3 approaches";
- "Propose 2-3 approaches" -> "Present design sections";
- "Present design sections" -> "User approves design?";
- "User approves design?" -> "Present design sections" [label="no, revise"];
- "User approves design?" -> "Write design doc" [label="yes"];
- "Write design doc" -> "Spec self-review\n(fix inline)";
- "Spec self-review\n(fix inline)" -> "User reviews spec?";
- "User reviews spec?" -> "Write design doc" [label="changes requested"];
- "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
-}
-```
-
-**Terminal states are path-bound.** Architectural: the ONLY skill you
-invoke after brainstorming is writing-plans — never frontend-design,
-mcp-builder, or any other implementation skill. Bounded: after
-approval, implementation proceeds directly through the normal
-development workflow; no plan document. Spike: the terminal state is a
-reported recommendation.
-
-## The Process
-
-The subsections below serve the bounded and architectural paths (a
-spike stops at "present the probe, get a nod"). Sections from
-**Exploring approaches** onward are architectural-path depth — for
-bounded work, context plus a few questions plus a short in-chat design
-is the whole process.
-
-**Understanding the idea:**
-
-- Check out the current project state first (files, docs, recent commits)
-- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
-- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
-- For appropriately-scoped projects, ask questions one at a time to refine the idea
-- Prefer multiple choice questions when possible, but open-ended is fine too
-- Only one question per message - if a topic needs more exploration, break it into multiple questions
-- Focus on understanding: purpose, constraints, success criteria
-
-**Exploring approaches:**
-
-- Propose 2-3 different approaches with trade-offs
-- Present options conversationally with your recommendation and reasoning
-- Lead with your recommended option and explain why
-- YAGNI ruthlessly - remove unnecessary features from every approach and design
-
-**Presenting the design:**
-
-- Once you believe you understand what you're building, present the design
-- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
-- Ask after each section whether it looks right so far
-- Cover: architecture, components, data flow, error handling, testing
-- Be ready to go back and clarify if something doesn't make sense
-
-**Design for isolation and clarity:**
-
-- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
-- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
-- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
-- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
-
-**Working in existing codebases:**
-
-- Explore the current structure before proposing changes. Follow existing patterns.
-- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
-- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
-
-## After the Design (architectural path)
-
-**Documentation:**
-
-- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
- - (User preferences for spec location override this default)
-- Use elements-of-style:writing-clearly-and-concisely skill if available
-- Commit the design document to git
-
-**Spec Self-Review:**
-After writing the spec document, look at it with fresh eyes:
-
-1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
-2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
-3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
-4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
-
-Fix any issues inline. No need to re-review — just fix and move on.
-
-**User Review Gate:**
-After the spec review loop passes, ask the user to review the written spec before proceeding:
-
-> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
-
-Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
-
-**Implementation:**
-
-- Invoke the writing-plans skill to create a detailed implementation plan
-- Do NOT invoke any other skill. writing-plans is the next step.
+| "I'll offer options to save them effort" | Options steer. Ask them to describe it first. |
+| "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. |
+| "I should explain the process first" | Ask your question. The process shows itself. |
+| "They said 'sounds good' to the idea" | Approval covers what you showed them. A description you haven't written isn't approved. |
+| "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. |
## Visual Companion
-A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
-
-**Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message:
-> "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you."
+A browser tab for showing mockups, diagrams, and prototypes. It's a
+tool, not a mode: accepting it doesn't send every question to the
+browser.
-**This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with `--open` so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it.
+**Offer it just-in-time.** Offer it the first time one of the moments
+above comes up, never upfront. The offer is its own message with nothing
+else in it:
-**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+> "This might be easier if I show you. Want me to open a browser tab with some mockups?"
-- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
-- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+If they decline, stay in text and don't offer again unless they raise it.
-A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
+**Per question, ask: would they understand this better by seeing it?**
+Mockups, layouts, diagrams, and side-by-side designs go in the browser.
+Requirements, scope, tradeoffs, and conceptual choices stay in text. A
+question about a UI topic isn't automatically a visual question.
-If they agree to the companion, read the detailed guide before proceeding:
-`skills/brainstorming/visual-companion.md`
+If they accept, read `visual-companion.md` in this directory before
+starting the server.
diff --git a/skills/brainstorming/builder-check-prompt.md b/skills/brainstorming/builder-check-prompt.md
new file mode 100644
index 0000000..136e9c1
--- /dev/null
+++ b/skills/brainstorming/builder-check-prompt.md
@@ -0,0 +1,23 @@
+# Builder Check Prompt
+
+Dispatch a fresh general-purpose subagent with this prompt once the
+written design exists. Fill in the domain and the document path.
+
+```
+You are a talented [DOMAIN, e.g. "software engineer", "event planner",
+"bakery consultant"]. You've been handed a design document and asked to
+put together a plan to build what it describes. You will not be able to
+talk to the person who wrote it.
+
+Read [DOCUMENT_PATH].
+
+Report only the questions you'd still need answered before you could plan
+this well: places where you'd have to guess and a wrong guess would
+matter. For each, give the question and why the answer changes the plan.
+Rank them by importance.
+
+Skip anything the document explicitly leaves to the builder, and anything
+you could reasonably decide yourself. Skip nitpicks about wording.
+
+If nothing important is left, say "nothing important left".
+```
diff --git a/skills/brainstorming/scripts/server.cjs b/skills/brainstorming/scripts/server.cjs
index a828b35..fdc7961 100644
--- a/skills/brainstorming/scripts/server.cjs
+++ b/skills/brainstorming/scripts/server.cjs
@@ -261,7 +261,7 @@ function isFullDocument(html) {
}
function wrapInFrame(content) {
- return renderBranding(frameTemplate).replace('<!-- CONTENT -->', content);
+ return renderBranding(frameTemplate).replace('<!-- CONTENT -->', () => content);
}
function getNewestScreen() {
diff --git a/skills/brainstorming/spec-document-reviewer-prompt.md b/skills/brainstorming/spec-document-reviewer-prompt.md
deleted file mode 100644
index 6099312..0000000
--- a/skills/brainstorming/spec-document-reviewer-prompt.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Spec Document Reviewer Prompt Template
-
-Use this template when dispatching a spec document reviewer subagent.
-
-**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
-
-**Dispatch after:** Spec document is written to docs/superpowers/specs/
-
-```
-Subagent (general-purpose):
- description: "Review spec document"
- prompt: |
- You are a spec document reviewer. Verify this spec is complete and ready for planning.
-
- **Spec to review:** [SPEC_FILE_PATH]
-
- ## What to Check
-
- | Category | What to Look For |
- |----------|------------------|
- | Completeness | TODOs, placeholders, "TBD", incomplete sections |
- | Consistency | Internal contradictions, conflicting requirements |
- | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
- | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
- | YAGNI | Unrequested features, over-engineering |
-
- ## Calibration
-
- **Only flag issues that would cause real problems during implementation planning.**
- A missing section, a contradiction, or a requirement so ambiguous it could be
- interpreted two different ways — those are issues. Minor wording improvements,
- stylistic preferences, and "sections less detailed than others" are not.
-
- Approve unless there are serious gaps that would lead to a flawed plan.
-
- ## Output Format
-
- ## Spec Review
-
- **Status:** Approved | Issues Found
-
- **Issues (if any):**
- - [Section X]: [specific issue] - [why it matters for planning]
-
- **Recommendations (advisory, do not block approval):**
- - [suggestions for improvement]
-```
-
-**Reviewer returns:** Status, Issues (if any), Recommendations
diff --git a/skills/executing-plans/scripts/task-done b/skills/executing-plans/scripts/task-done
index dd09871..e5fc6a9 100755
--- a/skills/executing-plans/scripts/task-done
+++ b/skills/executing-plans/scripts/task-done
@@ -45,7 +45,7 @@ if [ "$rc" -ne 0 ]; then
exit "$rc"
fi
-last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1)
+last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1) || last="(no output)"
[ -f "$ledger" ] || printf '# SDD ledger — plan: %s\n' "$plan" > "$ledger"
line="Task $n: complete (commits $(git rev-parse --short=7 "$base")..$(git rev-parse --short=7 HEAD), tests: $cmd → $last)"
printf '%s\n' "$line" >> "$ledger"
diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md
index 6d995da..68d338a 100644
--- a/skills/requesting-code-review/SKILL.md
+++ b/skills/requesting-code-review/SKILL.md
@@ -52,7 +52,7 @@ Dispatch a `general-purpose` subagent, filling the template at [code-reviewer.md
You: Let me request code review before proceeding.
-BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | cut -d' ' -f1)
HEAD_SHA=$(git rev-parse HEAD)
[Dispatch code reviewer subagent]
diff --git a/skills/subagent-driven-development/scripts/sdd-workspace b/skills/subagent-driven-development/scripts/sdd-workspace
index ff6b983..b4661eb 100755
--- a/skills/subagent-driven-development/scripts/sdd-workspace
+++ b/skills/subagent-driven-development/scripts/sdd-workspace
@@ -42,13 +42,16 @@ slug=$(basename "$plan" .md)
[ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
|| { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
-root=$(git rev-parse --show-toplevel)
+# Physical path, spelled the way pwd -P spells the plan path below: on Git
+# Bash, rev-parse prints C:/Users/... while pwd prints /c/Users/..., and the
+# repo-relative marker check needs both in the same form.
+root=$(CDPATH='' cd -- "$(git rev-parse --show-toplevel)" && pwd -P)
base="$root/.superpowers/sdd"
# Normalize the plan path (physical directory, so relative/absolute/../
# spellings of one plan compare equal) and express it as the marker value:
# repo-relative when the plan lives under the repo root, absolute otherwise.
-plan_dir=$(CDPATH= cd -- "$(dirname "$plan")" && pwd -P)
+plan_dir=$(CDPATH='' cd -- "$(dirname "$plan")" && pwd -P)
plan_abs="$plan_dir/$(basename "$plan")"
case "$plan_abs" in
"$root"/*) plan_id=${plan_abs#"$root"/} ;;
@@ -78,5 +81,7 @@ if ! owns "$dir"; then
fi
fi
-printf '*\n' > "$base/.gitignore"
-CDPATH= cd -- "$dir" && pwd
+# Create-only: a repo may commit its own .gitignore here (e.g. to version
+# progress.md ledgers); overwriting it would revert that on every run.
+[ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore"
+CDPATH='' cd -- "$dir" && pwd
diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md
index 095d194..62fc752 100644
--- a/skills/systematic-debugging/SKILL.md
+++ b/skills/systematic-debugging/SKILL.md
@@ -88,11 +88,11 @@ You MUST complete each phase before proceeding to the next.
```bash
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
- echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+ echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
- env | grep IDENTITY || echo "IDENTITY not in environment"
+ printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
diff --git a/tests/antigravity/test-antigravity-tools.sh b/tests/antigravity/test-antigravity-tools.sh
index e10edd4..ca83065 100755
--- a/tests/antigravity/test-antigravity-tools.sh
+++ b/tests/antigravity/test-antigravity-tools.sh
@@ -1,10 +1,8 @@
#!/usr/bin/env bash
-# Validate the Antigravity (agy) integration. agy installs the existing plugin
-# directly (`agy plugin install <repo-url>`): it loads the bundled skills and
-# runs the SessionStart hook for bootstrap, so there is no agy-specific scaffold
-# to test. What IS agy-specific is the tool mapping — subagent dispatch via
-# invoke_subagent (self/research types) and task tracking via a task artifact —
-# and SKILL.md pointing at it.
+# Validate the Antigravity (agy) tool mapping: subagent dispatch via
+# invoke_subagent (self/research types), task tracking via a task artifact, and
+# SKILL.md pointing at the mapping. The plugin manifest and layout are checked
+# by test-plugin-manifest.sh.
#
# Mirrors tests/pi/test-pi-extension.mjs's "tools reference documents
# harness-specific mappings" check. CI-safe: does not require `agy` installed.
diff --git a/tests/antigravity/test-logo.sh b/tests/antigravity/test-logo.sh
new file mode 100755
index 0000000..6132e47
--- /dev/null
+++ b/tests/antigravity/test-logo.sh
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Check the Antigravity Marketplace logo: a square RGBA PNG at least 128x128
+# (the Marketplace minimum), at the path the manifest names. When rsvg-convert
+# is available, also check the committed PNG matches a fresh render, so the
+# asset can't drift from scripts/render-antigravity-logo.sh.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+LOGO="$REPO_ROOT/assets/antigravity-logo.png"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+echo "test-logo: checking Antigravity logo"
+
+[ -f "$LOGO" ] || fail "logo missing at $LOGO"
+
+python3 - "$LOGO" <<'PY'
+import struct
+import sys
+
+data = open(sys.argv[1], "rb").read()
+if data[:8] != b"\x89PNG\r\n\x1a\n":
+ raise SystemExit("FAIL: logo is not a PNG")
+width, height, bit_depth, color_type = struct.unpack(">IIBB", data[16:26])
+if width != height:
+ raise SystemExit(f"FAIL: logo is not square ({width}x{height})")
+if width < 128:
+ raise SystemExit(f"FAIL: logo is smaller than 128x128 ({width}x{height})")
+if color_type != 6:
+ raise SystemExit(f"FAIL: logo is not RGBA (PNG color type {color_type})")
+PY
+
+if command -v rsvg-convert >/dev/null 2>&1; then
+ tmp="$(mktemp -d)"
+ trap 'rm -f "$tmp/logo.png"; rmdir "$tmp"' EXIT
+ bash "$REPO_ROOT/scripts/render-antigravity-logo.sh" --output "$tmp/logo.png" >/dev/null
+ cmp -s "$tmp/logo.png" "$LOGO" \
+ || fail "assets/antigravity-logo.png is stale; run scripts/render-antigravity-logo.sh"
+else
+ echo "SKIP: rsvg-convert not on PATH; not checking logo freshness"
+fi
+
+echo "PASS: Antigravity logo valid"
diff --git a/tests/antigravity/test-plugin-manifest.sh b/tests/antigravity/test-plugin-manifest.sh
new file mode 100755
index 0000000..ca2dad7
--- /dev/null
+++ b/tests/antigravity/test-plugin-manifest.sh
@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Validate the native Antigravity plugin: the Marketplace manifest, the skill
+# description agy relies on to bootstrap using-superpowers, and the repo layout
+# agy depends on. CI-safe; when `agy` is on PATH, also runs `agy plugin validate`.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+echo "test-plugin-manifest: checking Antigravity plugin"
+
+python3 - "$REPO_ROOT" <<'PY'
+import json
+import re
+import struct
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+
+def fail(message):
+ raise SystemExit(f"FAIL: {message}")
+
+manifest_path = root / ".antigravity-plugin" / "plugin.json"
+if not manifest_path.is_file():
+ fail(f"manifest missing at {manifest_path}")
+manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+
+# --- Marketplace-required fields -------------------------------------------
+for field in ["name", "description", "displayName", "logo",
+ "suggestedPrompts", "version", "author"]:
+ if not manifest.get(field):
+ fail(f"manifest field {field!r} is missing or empty")
+
+if manifest["name"] != "superpowers":
+ fail(f"name must be 'superpowers', got {manifest['name']!r}")
+if not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", manifest["name"]):
+ fail("name is not kebab-case")
+
+description_length = len(manifest["description"])
+# The guide recommends 120-160 characters for Marketplace cards; we use a
+# shorter tagline by choice, so enforce only the upper bound.
+if description_length > 160:
+ fail(f"description is {description_length} characters; Marketplace cards fit at most 160")
+
+prompts = manifest["suggestedPrompts"]
+if not isinstance(prompts, list) or not 1 <= len(prompts) <= 3:
+ fail("suggestedPrompts must be a list of 1-3 prompts")
+if not all(isinstance(p, str) and p.strip() for p in prompts):
+ fail("suggestedPrompts entries must be non-empty strings")
+
+claude_manifest = json.loads(
+ (root / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))
+if manifest["version"] != claude_manifest["version"]:
+ fail(f"version {manifest['version']!r} != .claude-plugin version "
+ f"{claude_manifest['version']!r}")
+if manifest["author"] != claude_manifest["author"]:
+ fail("author does not match .claude-plugin/plugin.json")
+
+# --- Logo ------------------------------------------------------------------
+logo = root / manifest["logo"]
+if not logo.is_file():
+ fail(f"logo {manifest['logo']!r} does not exist")
+header = logo.read_bytes()[:26]
+if header[:8] != b"\x89PNG\r\n\x1a\n":
+ fail("logo is not a PNG")
+width, height = struct.unpack(">II", header[16:24])
+if width != height or width < 128:
+ fail(f"logo must be square and at least 128x128, got {width}x{height}")
+
+# --- Version bumps ---------------------------------------------------------
+version_config = json.loads((root / ".version-bump.json").read_text(encoding="utf-8"))
+if not any(entry.get("path") == ".antigravity-plugin/plugin.json"
+ and entry.get("field") == "version"
+ for entry in version_config.get("files", [])):
+ fail(".version-bump.json does not register .antigravity-plugin/plugin.json")
+
+# --- Bootstrap: agy lists each skill's description, and using-superpowers'
+# description is what gets the model to load it at the start of a session.
+skill_md = (root / "skills" / "using-superpowers" / "SKILL.md").read_text(encoding="utf-8")
+frontmatter = re.match(r"---\n(.*?)\n---\n", skill_md, re.DOTALL)
+description = frontmatter and re.search(r"^description:(.*)$", frontmatter.group(1), re.MULTILINE)
+if not description or "Use when starting any conversation" not in description.group(1):
+ fail("using-superpowers description no longer says 'Use when starting any "
+ "conversation'; Antigravity relies on it to bootstrap")
+
+# --- Layout agy depends on -------------------------------------------------
+# A root plugin.json would be read instead of .antigravity-plugin/plugin.json,
+# a root hooks.json would run on every model call, and Cursor loads any
+# rules/*.md shipped in a plugin.
+for stray in ["plugin.json", "hooks.json", "rules"]:
+ if (root / stray).exists():
+ fail(f"root {stray} must not exist")
+PY
+
+if command -v agy >/dev/null 2>&1; then
+ output="$(agy plugin validate "$REPO_ROOT" 2>&1)" \
+ || { echo "$output" >&2; echo "FAIL: agy plugin validate failed" >&2; exit 1; }
+ grep -q '\[ok\]' <<<"$output" \
+ || { echo "$output" >&2; echo "FAIL: agy plugin validate did not report [ok]" >&2; exit 1; }
+ grep -qE 'skills +: [0-9]+ processed' <<<"$output" \
+ || { echo "$output" >&2; echo "FAIL: agy found no skills" >&2; exit 1; }
+else
+ echo "SKIP: agy not on PATH; not running agy plugin validate"
+fi
+
+echo "PASS: Antigravity plugin manifest and layout valid"
diff --git a/tests/brainstorm-server/lifecycle.test.js b/tests/brainstorm-server/lifecycle.test.js
index c43d8c0..83b3193 100644
--- a/tests/brainstorm-server/lifecycle.test.js
+++ b/tests/brainstorm-server/lifecycle.test.js
@@ -102,16 +102,16 @@ async function waitForStartedOutput(child, timeoutMs = 5000) {
}
function makeShellTempDir(prefix) {
- return execFileSync('bash', ['-lc', `mktemp -d "\${TMPDIR:-/tmp}/${prefix}-XXXXXX"`], { encoding: 'utf8' }).trim();
+ return execFileSync('bash', ['-c', `mktemp -d "\${TMPDIR:-/tmp}/${prefix}-XXXXXX"`], { encoding: 'utf8' }).trim();
}
function removeShellPath(p) {
- execFileSync('bash', ['-lc', 'rm -rf "$1"', 'bash', p], { stdio: 'ignore' });
+ execFileSync('bash', ['-c', 'rm -rf "$1"', 'bash', p], { stdio: 'ignore' });
}
function newestSessionDir(projectDir) {
const sessionDir = execFileSync('bash', [
- '-lc',
+ '-c',
'find "$1/.superpowers/brainstorm" -mindepth 1 -maxdepth 1 -type d -print | sort | tail -1',
'bash',
projectDir
diff --git a/tests/brainstorm-server/server.test.js b/tests/brainstorm-server/server.test.js
index 5d62323..510ee98 100644
--- a/tests/brainstorm-server/server.test.js
+++ b/tests/brainstorm-server/server.test.js
@@ -211,6 +211,20 @@ async function runTests() {
assert(res.body.includes('data-choice="a"'), 'Fragment interactive elements intact');
});
+ await test('preserves literal replacement tokens in content fragments', async () => {
+ const tokens = ["$'", '$`', '$&', '$$', '$1', '$<name>'];
+ const fragment = '<h2>Literal tokens</h2><pre>' + tokens.join(' | ') + '</pre>';
+ fs.writeFileSync(path.join(CONTENT_DIR, 'literal-tokens.html'), fragment);
+ await sleep(300);
+
+ const res = await fetch(`http://localhost:${TEST_PORT}/`);
+ assert.strictEqual(res.status, 200);
+ assert(res.body.includes(fragment), 'Fragment must be inserted verbatim');
+ assert.strictEqual(res.body.split('<div class="header">').length - 1, 1, 'Frame chrome must not be duplicated');
+ assert(!res.body.includes('<!-- CONTENT -->'), 'Replacement tokens must not restore the placeholder');
+ assert(res.body.includes('WebSocket'), 'Helper must still be injected');
+ });
+
await test('serves newest file by mtime', async () => {
fs.writeFileSync(path.join(CONTENT_DIR, 'older.html'), '<h2>Older</h2>');
await sleep(100);
@@ -577,7 +591,8 @@ async function runTests() {
// ========== Summary ==========
console.log(`\n--- Results: ${passed} passed, ${failed} failed, ${skipped} skipped ---`);
- if (failed > 0) process.exit(1);
+ // exitCode, not exit(): exit() would skip the finally below and orphan the server.
+ if (failed > 0) process.exitCode = 1;
} finally {
server.kill();
diff --git a/tests/claude-code/test-executing-plans-scripts.sh b/tests/claude-code/test-executing-plans-scripts.sh
index 994733b..e4e3904 100755
--- a/tests/claude-code/test-executing-plans-scripts.sh
+++ b/tests/claude-code/test-executing-plans-scripts.sh
@@ -33,6 +33,8 @@ main() {
git init -q -b main "$TEST_ROOT/repo"
local repo
repo="$(cd "$TEST_ROOT/repo" && git rev-parse --show-toplevel)"
+ # Same spelling as the scripts print (pwd), not rev-parse's C:/... on Git Bash.
+ repo="$(cd "$repo" && pwd)"
local git_id=(-c user.email=t@example.com -c user.name=t -c commit.gpgsign=false)
cat > "$repo/plan.md" <<'PLAN'
@@ -127,6 +129,31 @@ PLAN
echo " got: $out"
fi
+ # --- task-done: records a passing task whose test command prints nothing ---
+ # https://github.com/obra/superpowers/issues/2385 -- under `set -euo
+ # pipefail`, the ledger's `grep -v '^[[:space:]]*$' log | tail -n 1`
+ # exits 1 on an empty/blank log, which used to abort the whole script
+ # (silently, no ledger line) even though the test command itself passed.
+ ( cd "$repo" && echo y > work2.txt && git add work2.txt && git "${git_id[@]}" commit -qm "task 2" )
+ local head2
+ head2="$(cd "$repo" && git rev-parse HEAD)"
+ rc=0
+ out="$(cd "$repo" && "$EP_SCRIPTS/task-done" plan.md 2 "$head" -- true 2>&1)" || rc=$?
+ if [[ "$rc" -eq 0 ]]; then
+ pass "task-done exits 0 when a passing test command prints nothing"
+ else
+ fail "task-done exits 0 when a passing test command prints nothing (got rc=$rc)"
+ echo " got: $out"
+ fi
+ local expected2="Task 2: complete (commits ${head:0:7}..${head2:0:7}, tests: true → (no output))"
+ if [[ -f "$ledger" ]] && grep -qF "$expected2" "$ledger"; then
+ pass "task-done records a passing task that printed no output"
+ else
+ fail "task-done records a passing task that printed no output"
+ echo " expected: $expected2"
+ echo " ledger:"; sed 's/^/ /' "$ledger" 2>/dev/null || echo " (missing)"
+ fi
+
echo
if [[ "$FAILURES" -eq 0 ]]; then
echo "PASS"
diff --git a/tests/claude-code/test-sdd-workspace.sh b/tests/claude-code/test-sdd-workspace.sh
index 2e8c227..16cf50d 100755
--- a/tests/claude-code/test-sdd-workspace.sh
+++ b/tests/claude-code/test-sdd-workspace.sh
@@ -17,6 +17,16 @@ fail() {
FAILURES=$((FAILURES + 1))
}
+# Push a path through the same `cd ... && pwd` normalization that
+# sdd-workspace's own printed output goes through, so both sides of a
+# string comparison are guaranteed to be spelled identically. On Windows
+# Git Bash/MSYS, `git rev-parse --show-toplevel` (Windows-style,
+# C:/Users/...) and `cd ... && pwd` (MSYS-style, /c/Users/...) can print
+# different spellings of the identical physical directory; on Linux/macOS
+# this is a no-op since the two already agree (module the resolved-symlink
+# /var -> /private/var case handled by the mktemp comment above).
+physical_path() { (cd "$1" && pwd); }
+
cleanup() {
if [[ -n "$TEST_ROOT" && -d "$TEST_ROOT" ]]; then
rm -rf "$TEST_ROOT"
@@ -35,6 +45,7 @@ main() {
git init -q -b main "$TEST_ROOT/repo"
local repo
repo="$(cd "$TEST_ROOT/repo" && git rev-parse --show-toplevel)"
+ repo="$(physical_path "$repo")"
cat > "$repo/plan-a.md" <<'PLAN'
# Plan A
@@ -194,6 +205,7 @@ PLAN
( cd "$repo" && git worktree add -q "$wt" -b wt-feature )
local wt_root wt_dir
wt_root="$(cd "$wt" && git rev-parse --show-toplevel)"
+ wt_root="$(physical_path "$wt_root")"
wt_dir="$(cd "$wt" && "$SDD_SCRIPTS/sdd-workspace" plan-a.md)"
if [[ "$wt_dir" == "$wt_root/.superpowers/sdd/plan-a" && "$wt_dir" != "$dir_a" ]]; then
pass "linked worktree resolves its own distinct workspace"
@@ -350,6 +362,24 @@ PLAN
echo " marker: $(cat "$dir_out/plan-path" 2>/dev/null)"
fi
+ # --- A repo's own committed .superpowers/sdd/.gitignore is left alone ---
+ git init -q -b main "$TEST_ROOT/own-ignore"
+ local own own_ignore
+ own="$(cd "$TEST_ROOT/own-ignore" && git rev-parse --show-toplevel)"
+ own_ignore=$'*\n!.gitignore\n!*/\n!*/progress.md'
+ mkdir -p "$own/.superpowers/sdd"
+ printf '%s\n' "$own_ignore" > "$own/.superpowers/sdd/.gitignore"
+ printf '# Plan\n\n## Task 1: One\n\nOne.\n' > "$own/plan.md"
+ (cd "$own" && git add -A && git -c user.name=t -c user.email=t@t commit -qm init)
+ (cd "$own" && "$SDD_SCRIPTS/sdd-workspace" plan.md >/dev/null)
+ if [[ "$(cat "$own/.superpowers/sdd/.gitignore")" == "$own_ignore" \
+ && -z "$(cd "$own" && git status --porcelain -- .superpowers/sdd/.gitignore)" ]]; then
+ pass "an existing .superpowers/sdd/.gitignore is not overwritten"
+ else
+ fail "an existing .superpowers/sdd/.gitignore is not overwritten"
+ echo " now: $(cat "$own/.superpowers/sdd/.gitignore")"
+ fi
+
echo ""
if [[ "$FAILURES" -ne 0 ]]; then
echo "FAILED: $FAILURES assertion(s)."
diff --git a/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh b/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
index 265aea1..84282c2 100755
--- a/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
+++ b/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
@@ -174,6 +174,7 @@ write_upstream_fixture() {
local with_pure_ignored="${2:-1}"
mkdir -p \
+ "$repo/.antigravity-plugin" \
"$repo/.codex-plugin" \
"$repo/.kimi-plugin" \
"$repo/.private-journal" \
@@ -241,6 +242,15 @@ EOF
}
EOF
+ cat > "$repo/.antigravity-plugin/plugin.json" <<EOF
+{
+ "name": "superpowers",
+ "version": "$MANIFEST_VERSION"
+}
+EOF
+
+ printf 'antigravity png fixture\n' > "$repo/assets/antigravity-logo.png"
+
cat > "$repo/assets/superpowers-small.svg" <<'EOF'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 1"></svg>
EOF
@@ -295,11 +305,13 @@ EOF
fi
git -C "$repo" add \
+ .antigravity-plugin/plugin.json \
.codex-plugin/plugin.json \
.kimi-plugin/plugin.json \
.gitignore \
.gitmodules \
.pre-commit-config.yaml \
+ assets/antigravity-logo.png \
assets/app-icon.png \
assets/superpowers-small.svg \
evals/drill/README.md \
@@ -657,6 +669,8 @@ main() {
assert_not_contains "$preview_output" "Version: $PACKAGE_VERSION" "Preview does not use package.json version"
assert_contains "$preview_section" ".codex-plugin/plugin.json" "Preview includes manifest path"
assert_not_contains "$preview_section" ".kimi-plugin/plugin.json" "Preview excludes Kimi manifest from Codex sync"
+ assert_not_contains "$preview_section" ".antigravity-plugin/plugin.json" "Preview excludes Antigravity manifest from Codex sync"
+ assert_not_contains "$preview_section" "assets/antigravity-logo.png" "Preview excludes Antigravity logo from Codex sync"
assert_contains "$preview_section" "assets/superpowers-small.svg" "Preview includes SVG asset"
assert_contains "$preview_section" "assets/app-icon.png" "Preview includes PNG asset"
assert_contains "$preview_section" "hooks/hooks-codex.json" "Preview includes Codex hook manifest"
diff --git a/tests/hermes/conftest.py b/tests/hermes/conftest.py
index 561cd8c..ec22bed 100644
--- a/tests/hermes/conftest.py
+++ b/tests/hermes/conftest.py
@@ -9,11 +9,12 @@ def mock_ctx():
ctx = MagicMock()
ctx._hooks = {}
ctx._skills = {}
+ ctx._descriptions = {}
def register_hook(event, fn):
ctx._hooks[event] = fn
- def register_skill(name, path):
+ def register_skill(name, path, description="", frontmatter=None):
# Mimic hermes' real register_skill, which calls path.exists() and
# therefore breaks on a str (the bug that silently disabled the whole
# plugin, found 2026-07-23). Keeping that fidelity here means a
@@ -24,6 +25,7 @@ def mock_ctx():
f"register_skill requires a pathlib.Path, got {type(path).__name__}"
)
ctx._skills[name] = path
+ ctx._descriptions[name] = description
ctx.register_hook.side_effect = register_hook
ctx.register_skill.side_effect = register_skill
diff --git a/tests/hermes/test_plugin.py b/tests/hermes/test_plugin.py
index 9c6c4f0..57d619e 100644
--- a/tests/hermes/test_plugin.py
+++ b/tests/hermes/test_plugin.py
@@ -1,6 +1,7 @@
import importlib
import importlib.util
import os
+import re
import shutil
import sys
from pathlib import Path
@@ -140,3 +141,38 @@ class TestLayoutResolution:
mod = self._load_from(plugdir)
with pytest.raises(RuntimeError, match="cannot find the skills"):
mod.register(mock_ctx)
+
+
+class TestSkillDescriptions:
+ """Hermes builds its skill catalogue from register_skill(description=...),
+ which defaults to "". Registering the path alone left every stock skill
+ blank in that catalogue, so the model had nothing to select on."""
+
+ def test_every_stock_skill_registers_a_description(self, mock_ctx):
+ plugin = _load_plugin()
+ plugin.register(mock_ctx)
+ assert set(mock_ctx._descriptions) == set(mock_ctx._skills)
+ blank = sorted(n for n, d in mock_ctx._descriptions.items() if not d.strip())
+ assert blank == [], f"registered without a description: {blank}"
+
+ def test_descriptions_match_the_skill_frontmatter(self, mock_ctx):
+ plugin = _load_plugin()
+ plugin.register(mock_ctx)
+ skills_dir = Path(plugin._skills_dir())
+ for name, description in mock_ctx._descriptions.items():
+ text = (skills_dir / name / "SKILL.md").read_text(encoding="utf-8")
+ declared = re.search(r"^description:\s*(.+)$", text, re.M).group(1)
+ assert description == declared.strip().strip('"').strip("'")
+
+ @pytest.mark.parametrize(
+ "block, expected",
+ [
+ ('---\nname: demo\ndescription: "Quoted value."\n---\nbody', "Quoted value."),
+ ("---\nname: demo\ndescription: Bare value\n---\nbody", "Bare value"),
+ ("---\nname: demo\n---\nbody", ""),
+ ("no frontmatter at all", ""),
+ ],
+ )
+ def test_frontmatter_value_parsing(self, block, expected):
+ plugin = _load_plugin()
+ assert plugin._frontmatter_value(block, "description") == expected
diff --git a/tests/hooks/test-run-hook-cmd-windows.sh b/tests/hooks/test-run-hook-cmd-windows.sh
new file mode 100755
index 0000000..b58c6d1
--- /dev/null
+++ b/tests/hooks/test-run-hook-cmd-windows.sh
@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# Tests for the Windows (cmd) half of hooks/run-hook.cmd: how it finds bash
+# and whether the hook's exit code survives. Run from Git Bash on Windows;
+# skips anywhere cmd.exe isn't available.
+#
+# Most cases need the fallback branches, which a machine with Git in
+# Program Files never reaches. Those cases run a sandbox copy of the wrapper
+# whose Program Files paths point at a directory that doesn't exist.
+set -euo pipefail
+
+if ! command -v cmd >/dev/null 2>&1 || ! command -v cygpath >/dev/null 2>&1; then
+ echo "SKIP: cmd.exe not available (these tests run in Git Bash on Windows)"
+ exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PF_GIT='C:\Program Files\Git'
+# Spelled out: inside Git Bash, cygpath maps its own install dir to "/".
+PF_GIT_UNIX='/c/Program Files/Git'
+
+if [[ ! -e "$PF_GIT_UNIX/bin/bash.exe" ]]; then
+ echo "SKIP: needs Git for Windows in $PF_GIT to stand in for other installs"
+ exit 0
+fi
+
+FAILURES=0
+TEST_ROOT="$(mktemp -d)"
+JUNCTIONS=()
+
+cleanup() {
+ # Remove junctions with cmd's rmdir first, which never touches the
+ # target, so nothing below can recurse into the real Git install.
+ local j left=0
+ for j in "${JUNCTIONS[@]}"; do
+ cmd //c rmdir "$j" >/dev/null 2>&1 || true
+ if [[ -e "$(cygpath "$j")" ]]; then
+ echo "WARNING: junction $j still exists; not deleting $TEST_ROOT" >&2
+ left=1
+ fi
+ done
+ [[ "$left" -eq 0 ]] && rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+pass() { echo " [PASS] $1"; }
+fail() { echo " [FAIL] $1"; FAILURES=$((FAILURES + 1)); }
+
+junction() {
+ local link="$1" target="$2"
+ # Keep Git Bash from rewriting /J into a path.
+ MSYS2_ARG_CONV_EXCL="*" cmd /c mklink /J "$link" "$target" >/dev/null
+ JUNCTIONS+=("$link")
+}
+
+# A plugin root with probe hooks. $1 = "real" keeps the wrapper as is;
+# "sandbox" points its Program Files paths at nothing.
+make_plugin() {
+ local dir="$1" mode="$2"
+ mkdir -p "$dir/hooks"
+ if [[ "$mode" == sandbox ]]; then
+ sed -e 's#C:\\Program Files\\Git\\#C:\\no-such-program-files\\Git\\#g' \
+ -e 's#C:\\Program Files (x86)\\Git\\#C:\\no-such-program-files\\Git\\#g' \
+ "$REPO_ROOT/hooks/run-hook.cmd" > "$dir/hooks/run-hook.cmd"
+ if grep -q 'Program Files' "$dir/hooks/run-hook.cmd"; then
+ echo "sandbox wrapper still mentions Program Files" >&2
+ exit 1
+ fi
+ else
+ cp "$REPO_ROOT/hooks/run-hook.cmd" "$dir/hooks/run-hook.cmd"
+ fi
+ printf 'echo probe-ran\n' > "$dir/hooks/probe-ok"
+ printf 'echo probe-ran\nexit 7\n' > "$dir/hooks/probe-exit"
+}
+
+# run_hook PLUGIN_DIR CWD PROBE [VAR=value...] -> sets OUT and RC
+run_hook() {
+ local plugin="$1" cwd="$2" probe="$3"
+ shift 3
+ RC=0
+ # tr drops the NUL bytes the WSL launcher prints (UTF-16 text).
+ OUT="$(cd "$cwd" && env "$@" cmd //c "$(cygpath -w "$plugin")\\hooks\\run-hook.cmd" "$probe" 2>&1 | tr -d '\000'; exit "${PIPESTATUS[0]}")" || RC=$?
+}
+
+SYS32_PATH="/c/Windows/System32"
+GIT_USR_BIN="$PF_GIT_UNIX/usr/bin"
+NO_LA='C:\no-such-localappdata'
+
+echo "run-hook.cmd (Windows) tests"
+
+# --- exit code of the hook survives the wrapper ---
+real="$TEST_ROOT/real"
+make_plugin "$real" real
+run_hook "$real" "$TEST_ROOT" probe-exit
+if [[ "$RC" -eq 7 && "$OUT" == *probe-ran* ]]; then
+ pass "hook exit code propagates through run-hook.cmd"
+else
+ fail "hook exit code propagates through run-hook.cmd (rc=$RC, out=$OUT)"
+fi
+
+sandbox="$TEST_ROOT/sandbox"
+make_plugin "$sandbox" sandbox
+
+# --- per-user Git install (%LOCALAPPDATA%\Programs\Git) ---
+la="$TEST_ROOT/localappdata"
+mkdir -p "$la/Programs"
+junction "$(cygpath -w "$la/Programs/Git")" "$PF_GIT"
+run_hook "$sandbox" "$TEST_ROOT" probe-exit \
+ LOCALAPPDATA="$(cygpath -w "$la")" PATH="$SYS32_PATH"
+if [[ "$RC" -eq 7 && "$OUT" == *probe-ran* ]]; then
+ pass "per-user Git install is found and its exit code propagates"
+else
+ fail "per-user Git install is found and its exit code propagates (rc=$RC, out=$OUT)"
+fi
+
+# --- the System32 WSL launcher on PATH is skipped for a real bash ---
+run_hook "$sandbox" "$TEST_ROOT" probe-ok \
+ LOCALAPPDATA="$NO_LA" PATH="$SYS32_PATH:$GIT_USR_BIN"
+if [[ "$RC" -eq 0 && "$OUT" == *probe-ran* ]]; then
+ pass "System32 bash.exe (WSL launcher) is skipped in favor of Git's bash on PATH"
+else
+ fail "System32 bash.exe (WSL launcher) is skipped in favor of Git's bash on PATH (rc=$RC, out=$OUT)"
+fi
+
+# --- a bash under a WindowsApps directory (the Store WSL stub) is skipped ---
+apps_la="$TEST_ROOT/apps-localappdata"
+apps="$apps_la/Microsoft/WindowsApps"
+mkdir -p "$apps"
+apps_marker="$TEST_ROOT/windowsapps-ran"
+printf '@echo off\r\necho stub> "%s"\r\n' "$(cygpath -w "$apps_marker")" > "$apps/bash.cmd"
+run_hook "$sandbox" "$TEST_ROOT" probe-ok \
+ LOCALAPPDATA="$(cygpath -w "$apps_la")" PATH="$apps:$SYS32_PATH:$GIT_USR_BIN"
+if [[ ! -e "$apps_marker" && "$OUT" == *probe-ran* ]]; then
+ pass "bash under WindowsApps (Store WSL stub) is skipped"
+else
+ fail "bash under WindowsApps (Store WSL stub) is skipped (stub ran: $([[ -e $apps_marker ]] && echo yes || echo no), out=$OUT)"
+fi
+
+# --- nothing in the current directory is run: not bash, not where ---
+plant="$TEST_ROOT/planted-cwd"
+mkdir -p "$plant"
+for name in bash.cmd where.bat; do
+ printf '@echo off\r\necho planted> "%s"\r\n' "$(cygpath -w "$TEST_ROOT/ran-$name")" > "$plant/$name"
+done
+run_hook "$sandbox" "$plant" probe-ok \
+ LOCALAPPDATA="$NO_LA" PATH="$SYS32_PATH:$GIT_USR_BIN"
+for name in bash.cmd where.bat; do
+ if [[ ! -e "$TEST_ROOT/ran-$name" && "$OUT" == *probe-ran* ]]; then
+ pass "$name in the current directory is not run"
+ else
+ fail "$name in the current directory is not run (ran: $([[ -e $TEST_ROOT/ran-$name ]] && echo yes || echo no), out=$OUT)"
+ fi
+done
+
+# --- PATH entries whose names cmd could misparse still work ---
+# fake_bash DIR: a bash.cmd that reports it ran.
+fake_bash() {
+ mkdir -p "$1"
+ printf '@echo off\r\necho fake-bash-ran\r\n' > "$1/bash.cmd"
+}
+for dir_name in 'caret^and%OS%percent' $'caf\u00e9-bin' 'extensionless'; do
+ dir="$TEST_ROOT/$dir_name"
+ case "$dir_name" in
+ extensionless)
+ # An extensionless "bash" first on PATH must be skipped.
+ mkdir -p "$dir"
+ printf 'not a program\n' > "$dir/bash"
+ fake_bash "$TEST_ROOT/after-extensionless"
+ path="$dir:$TEST_ROOT/after-extensionless:$SYS32_PATH"
+ ;;
+ *)
+ fake_bash "$dir"
+ path="$dir:$SYS32_PATH"
+ ;;
+ esac
+ run_hook "$sandbox" "$TEST_ROOT" probe-ok LOCALAPPDATA="$NO_LA" PATH="$path"
+ if [[ "$RC" -eq 0 && "$OUT" == *fake-bash-ran* ]]; then
+ pass "bash on PATH is found under $dir_name"
+ else
+ fail "bash on PATH is found under $dir_name (rc=$RC, out=$OUT)"
+ fi
+done
+
+# --- unset SystemRoot must not let the WSL launcher through ---
+run_hook "$sandbox" "$TEST_ROOT" probe-ok -u SystemRoot \
+ LOCALAPPDATA="$NO_LA" PATH="$SYS32_PATH:$GIT_USR_BIN"
+if [[ "$RC" -eq 0 && "$OUT" != *Subsystem* ]]; then
+ pass "unset SystemRoot does not run the WSL launcher"
+else
+ fail "unset SystemRoot does not run the WSL launcher (rc=$RC, out=$OUT)"
+fi
+
+# --- unset LOCALAPPDATA must not probe \Programs\Git on the current drive ---
+drive_programs="/c/Programs"
+if [[ -e "$drive_programs" ]]; then
+ echo " [SKIP] unset LOCALAPPDATA: C:\\Programs already exists"
+else
+ mkdir "$drive_programs"
+ junction 'C:\Programs\Git' "$PF_GIT"
+ run_hook "$sandbox" "$TEST_ROOT" probe-ok -u LOCALAPPDATA PATH="$SYS32_PATH"
+ cmd //c rmdir 'C:\Programs\Git' >/dev/null 2>&1 || true
+ rmdir "$drive_programs"
+ if [[ "$RC" -eq 0 && "$OUT" != *probe-ran* ]]; then
+ pass "unset LOCALAPPDATA does not run \\Programs\\Git on the current drive"
+ else
+ fail "unset LOCALAPPDATA does not run \\Programs\\Git on the current drive (rc=$RC, out=$OUT)"
+ fi
+fi
+
+# --- no usable bash: exit 0 quietly, without invoking the WSL launcher ---
+run_hook "$sandbox" "$TEST_ROOT" probe-ok \
+ LOCALAPPDATA="$NO_LA" PATH="$SYS32_PATH"
+if [[ "$RC" -eq 0 && -z "$OUT" ]]; then
+ pass "no usable bash exits 0 with no output"
+else
+ fail "no usable bash exits 0 with no output (rc=$RC, out=$OUT)"
+fi
+
+if [[ "$FAILURES" -gt 0 ]]; then
+ echo "STATUS: FAILED ($FAILURES failure(s))"
+ exit 1
+fi
+echo "STATUS: PASSED"
diff --git a/tests/hooks/test-session-start.sh b/tests/hooks/test-session-start.sh
index c150829..6ddf011 100755
--- a/tests/hooks/test-session-start.sh
+++ b/tests/hooks/test-session-start.sh
@@ -217,6 +217,106 @@ assert_command_output \
CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
bash "$HOOK_UNDER_TEST"
+# Regression for #2310: Claude Code can spawn SessionStart:startup hooks with
+# a broken/empty PATH (anthropics/claude-code#43127). session-start and
+# run-hook.cmd's Unix half both shell out to external binaries (dirname, cat)
+# that an empty PATH cannot resolve, even though bash itself was invoked by
+# absolute path. Every call here should use bash's own builtins/redirection
+# instead, so an empty PATH must not change the result.
+bash_bin="$(command -v bash)"
+
+broken_path_home="$(make_home broken-path)"
+assert_command_output \
+ "session-start with empty PATH still emits nested additionalContext" \
+ "nested" \
+ "" \
+ "" \
+ "$broken_path_home" \
+ PATH="" \
+ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$bash_bin" "$HOOK_UNDER_TEST"
+
+broken_path_wrapper_home="$(make_home broken-path-wrapper)"
+assert_command_output \
+ "run-hook.cmd with empty PATH still dispatches session-start" \
+ "nested" \
+ "" \
+ "" \
+ "$broken_path_wrapper_home" \
+ PATH="" \
+ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$bash_bin" "$WRAPPER_UNDER_TEST" session-start
+
+# Run by bare filename from inside hooks/ ($0 has no slash), the plugin root
+# must still resolve.
+bare_name_home="$(make_home bare-name)"
+assert_command_output \
+ "session-start run by bare filename from hooks/ still emits nested additionalContext" \
+ "nested" \
+ "" \
+ "" \
+ "$bare_name_home" \
+ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$bash_bin" -c 'cd "$1" && exec "$2" session-start' _ "$REPO_ROOT/hooks" "$bash_bin"
+
+bare_name_wrapper_home="$(make_home bare-name-wrapper)"
+assert_command_output \
+ "run-hook.cmd run by bare filename from hooks/ still dispatches session-start" \
+ "nested" \
+ "" \
+ "" \
+ "$bare_name_wrapper_home" \
+ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$bash_bin" -c 'cd "$1" && exec "$2" run-hook.cmd session-start' _ "$REPO_ROOT/hooks" "$bash_bin"
+
+# run-hook.cmd's Windows half starts bash with a backslash path
+# (C:\...\hooks\session-start), so $0 can use \ as its separator. The skill
+# must still be found. On Windows use the real Windows path; elsewhere build
+# a plugin root whose hook is reached through a name containing a backslash.
+backslash_home="$(make_home backslash)"
+if command -v cygpath >/dev/null 2>&1; then
+ backslash_cwd="$REPO_ROOT"
+ backslash_hook="$(cygpath -w "$HOOK_UNDER_TEST")"
+else
+ backslash_cwd="$TEST_ROOT/backslash/root"
+ mkdir -p "$backslash_cwd"
+ ln -s "$REPO_ROOT/hooks" "$backslash_cwd/hooks"
+ ln -s "$REPO_ROOT/skills" "$backslash_cwd/skills"
+ ln -s "$REPO_ROOT/hooks/session-start" "$backslash_cwd/hooks\\session-start"
+ backslash_hook='hooks\session-start'
+fi
+assert_command_output \
+ "session-start reached through a backslash path still reads the skill" \
+ "nested" \
+ "" \
+ "Error reading using-superpowers skill" \
+ "$backslash_home" \
+ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$bash_bin" -c 'cd "$1" && exec "$2" "$3"' _ "$backslash_cwd" "$bash_bin" "$backslash_hook"
+
+# When cat is on PATH, the JSON must still go through it: the pipe absorbs
+# EPIPE on Windows + Git Bash (#1612). The stub records that it ran.
+cat_stub_dir="$TEST_ROOT/cat-stub/bin"
+cat_marker="$TEST_ROOT/cat-stub/used"
+mkdir -p "$cat_stub_dir"
+printf '#!%s\n: > "%s"\nexec /bin/cat "$@"\n' "$bash_bin" "$cat_marker" > "$cat_stub_dir/cat"
+chmod +x "$cat_stub_dir/cat"
+cat_stub_home="$(make_home cat-stub)"
+assert_command_output \
+ "session-start with cat on PATH emits nested additionalContext" \
+ "nested" \
+ "" \
+ "" \
+ "$cat_stub_home" \
+ PATH="$cat_stub_dir" \
+ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$bash_bin" "$HOOK_UNDER_TEST"
+if [[ -f "$cat_marker" ]]; then
+ pass "session-start pipes its JSON through cat when cat is on PATH"
+else
+ fail "session-start pipes its JSON through cat when cat is on PATH"
+fi
+
if [[ "$FAILURES" -gt 0 ]]; then
echo "STATUS: FAILED ($FAILURES failure(s))"
exit 1
diff --git a/tests/version-bump/test-bump-version.sh b/tests/version-bump/test-bump-version.sh
index 195d88a..2f77a48 100644
--- a/tests/version-bump/test-bump-version.sh
+++ b/tests/version-bump/test-bump-version.sh
@@ -73,4 +73,17 @@ cmp -s "$TEST_ROOT/package.before" "$invalid_repo/package.json" \
cmp -s "$TEST_ROOT/plugin.before" "$invalid_repo/.hermes-plugin/plugin.yaml" \
|| fail "invalid YAML manifest changed"
+audit_repo="$TEST_ROOT/audit-boundaries"
+make_fixture "$audit_repo" $'name: superpowers\nversion: 1.2.3'
+/bin/bash "$audit_repo/scripts/bump-version.sh" 4.0.0 >/dev/null
+printf 'host = "10.4.0.0"\n' >"$audit_repo/server.js"
+printf 'pin: superpowers.git#v4.0.0\n' >"$audit_repo/INSTALL.md"
+/bin/bash "$audit_repo/scripts/bump-version.sh" --audit >"$TEST_ROOT/audit-boundaries.out"
+
+grep -q 'INSTALL.md' "$TEST_ROOT/audit-boundaries.out" \
+ || fail "audit missed an undeclared #v4.0.0 pin"
+if grep -q 'server.js' "$TEST_ROOT/audit-boundaries.out"; then
+ fail "audit flagged 10.4.0.0 as version 4.0.0"
+fi
+
echo "Version-bump tests passed"
diff --git a/tests/writing-skills/test-render-graphs.sh b/tests/writing-skills/test-render-graphs.sh
index 349cd47..8bda626 100755
--- a/tests/writing-skills/test-render-graphs.sh
+++ b/tests/writing-skills/test-render-graphs.sh
@@ -4,7 +4,9 @@ set -u
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
SCRIPT_UNDER_TEST="$REPO_ROOT/skills/writing-skills/render-graphs.js"
-NODE_BIN="$(command -v node)"
+# Resolve the real binary: version-manager shims (mise, asdf) can't find node
+# under the empty PATH used for the missing-Graphviz case.
+NODE_BIN="$(node -p 'process.execPath')"
PASSES=0
FAILURES=0