Compare commits

..

66 Commits

Author SHA1 Message Date
Drew Ritter 34d4f64f91 feat(codex): ship the compaction hook as a plugin-provided hook
The compaction re-injection hook previously required users to hand-merge
an example into user-level ~/.codex/hooks.json — which renders in the
Codex hooks UI as an anonymous, unattributed "Hook 1" and puts the
install burden on every user. Restore the plugin-provided delivery this
repo used before "Remove Codex hooks" (640ce6c0): the Codex manifest
points hooks at hooks/hooks-codex.json, which runs session-start-codex
via ${PLUGIN_ROOT}/hooks/run-hook.cmd with matcher "compact".

Unlike the removed hook, this one never fires at session start — Codex
surfaces skills natively there, which is why the old startup-injecting
hook was removed. The matcher plus the script's own source gate restrict
it to post-compaction re-starts. The explicit manifest pointer also
keeps suppressing Codex's hooks/hooks.json auto-discovery fallback,
which the previous empty-object declaration existed for (7d8d3d4b).

The Codex portal archive now ships hooks/hooks-codex.json,
hooks/run-hook.cmd, and hooks/session-start-codex; other-harness hook
files stay excluded.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-23 13:26:01 -07:00
Drew Ritter 5ab3297ad7 docs(codex): wire the compaction hook into README and codex-tools, add drift-cure footer
README gains the hook install step for Codex users (hooks.json merge,
one-time trust prompt, --dangerously-bypass-hook-trust for headless
automation). codex-tools.md aligns its claims with the mechanism — the
dispatch rules bind every spawn, the printed hints appear at scripted
boundaries, and the hook covers post-compaction re-grounding — and adds
a section telling controllers compaction sheds these instructions and
to treat every printed hint as authoritative.

The hints file gains a drift-cure footer both scripts print after the
role line: in the instrumented run that broke post-compaction,
reprinted hints alone did not heal the already-broken dispatch pattern
across three subsequent boundaries — recovery text must name the drift
and prescribe the re-read.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-23 12:23:17 -07:00
Drew Ritter 1744d69413 feat(codex): re-inject the bootstrap after context compaction via SessionStart hook
Codex 0.145 re-fires SessionStart with source:"compact" after every
context compaction, and injects hook stdout into the live model context
(both verified with sentinel probes on codex-cli 0.145.0). Compaction
replaces the transcript with a summary that sheds the using-superpowers
bootstrap and the active skill's instructions; in instrumented SDD runs
the first post-compaction dispatch that lacked a freshly printed
reminder reverted to harness defaults (fork_turns=all, inherited
frontier model) and the drift then self-perpetuated. Claude Code never
exhibits this because its SessionStart matcher (startup|clear|compact)
re-injects the bootstrap at the same moment — this hook restores that
parity on Codex.

On source:"startup" the hook emits nothing: the native plugin path owns
session-start injection, and duplicating it would recreate the
redundancy that led to the original session-start-codex removal. Output
is plain text (Codex consumes raw stdout, unlike the JSON envelopes
hooks/session-start emits for other harnesses), and every failure path
is fail-open: bad stdin, missing skill file, or any error yields empty
output and exit 0 so a hook problem can never break a session.

Ships with hooks-codex.json.example for the user-level ~/.codex/hooks.json
merge and tests covering source filtering, whitespace-tolerant matching,
decoy fields, and fail-open behavior.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-23 12:21:49 -07:00
Drew Ritter c686bb947a feat(sdd): evidence-locked gate claims in the implementer report
Responds to maintainer review asking for better implementer
self-reflection. The report format already demands command+output for
TDD evidence and fix-round covering tests, but the full-suite claim
asked only for prose — and that is the claim that rotted in the field:
three consecutive fix rounds shipped a "full suite passes" claim the
fix reviewer found unreproducible, each time because the suite had run
before later edits made the result stale.

Two changes, both at the moment the report is written: every claimed
gate needs its exact command and the tail of fresh output — fresh
meaning after the final edit, otherwise rerun or report the gate as
unverified — and a missing pasted output is itself a defect for the
reviewer to flag, which puts enforcement at the consumption side the
same way the dispatch hints do. Fix reports claiming a full-suite pass
need a fresh run, not the pre-findings one.

This is verification-before-completion's gate function relocated into
the one prompt subagents actually receive.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 15:34:14 -07:00
Drew Ritter 4ed49b6a41 rename(sdd): re-review -> fix review, a scoped review of the fix diff
Responds to maintainer review: "re-review" names the action badly — it
reads as "review again," which is the exact failure observed in the
field (fix reviewers re-running full reviews and package-wide suites
against explicit scope instructions). "Fix review" names the artifact
under review — the fix diff since the previous review — and makes the
scope self-enforcing.

Pure vocabulary substitution: re-review-prompt.md becomes
fix-review-prompt.md, SKILL.md and the review-package --role value
follow, and the term is introduced once as "a scoped fix review — a
review of the fix diff, not a fresh review." No behavioral rules
changed. Historical records (docs/superpowers/plans, specs,
RELEASE-NOTES) keep the old vocabulary; other skills' generic verb
usage ("no need to re-review") is untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 15:33:48 -07:00
Drew Ritter cdcadda4be refactor(sdd): platform-owned dispatch hints — shared scripts carry no Codex literals
Responds to maintainer review of this branch: the dispatch-hint lines
were hardcoded Codex strings inside shared skill tooling that every
harness runs.

The per-role hint lines now live in a platform-owned data file,
skills/using-superpowers/references/codex-dispatch.hints, and the
task-brief/review-package scripts only relay the current role's line.
The relay is suppressed when CLAUDECODE is set (Claude Code's dispatch
templates already carry model selection) and on any harness with no
hints file; unknown harnesses fail toward printing, because a silent
no-op in the environment that needs the hint is the failure mode this
mechanism exists to prevent. Printing at the moment of dispatch is
load-bearing: skill text loaded at session start does not survive
context compaction, but script output reprints every round.

codex-tools.md's SDD dispatch section shrinks to the behavioral rules
(fork_turns: "none" always; copy the printed hint verbatim; reviewer
tier never exceeds implementer tier; no effort bumps; the <=0.144
inheritance fallback) and points at the hints file for values.

Tests cover the relay path, the per-role efforts, and the new
CLAUDECODE suppression case.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 15:31:50 -07:00
Drew Ritter c97988d8d1 feat(codex): SDD dispatch routing, fork hygiene, and final-review wave termination
Codex SDD runs at frontier tiers spin out: subagents inherit the
session's model and effort, review seats find real-but-endless defects
every round, and the final whole-branch review has no reachable
termination state. Field forensics across multiple real sessions traced
the mechanism: spawn_agent's fork_turns defaults to "all" (full-context
forks that also refuse model overrides), omitted model/effort params
inherit the frontier parent, and dispatch rules loaded at session start
do not survive context compaction — a compacted controller reverts to
inheritance exactly when the session is longest and most expensive.

Three coordinated changes:
- codex-tools.md: every SDD spawn sets fork_turns "none" plus explicit
  model/reasoning_effort when the schema supports them (Codex 0.145+),
  with an inheritance warning for older builds; reviewer tier never
  exceeds implementer tier and fix rounds never get effort bumps.
- task-brief/review-package print a dispatch tuple with their output
  (review-package grows --role for re-review/final-review), putting the
  routing values in front of the controller at the moment of dispatch —
  reprinted every round, so they survive compaction by construction.
- SKILL.md: the final-review wave closing is policy, not a verdict —
  one fix dispatch, one scoped re-review, residuals adjudicated to the
  ledger; one-off review procedures never become standing; Model
  Selection defers to platform role tables where one exists.

Validated live: a previously spun-out 14-task run (8h, 6 tasks, died
mid-loop) re-executed to completion under these changes — bounded fix
loops, single-cycle final review, ~20 consecutive correctly-routed
dispatches across two compactions. Reviewer-tier matrix (125 cells)
showed no calibration cost: clean-diff approvals and planted-defect
recall are identical across tiers. Eval scenarios to follow before any
upstream submission.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-21 22:57:28 -07:00
Drew Ritter d123bde46e exp(codex): print dispatch tuples from SDD scripts — v2 chokepoint for PRI-2672
Run-2 dispatch-4 autopsy: after compaction, the codex-tools role table
fell out of context and the controller reasoned itself into an inherited
sol@max reviewer — the harness's own 'inherited parent model is preferred'
plus SKILL.md's 'most capable model' outvoted the compaction summary's
distilled 'terra/high' line. Its introspection named the only artifact it
actually consults at the moment of dispatch: the review-package output.

So the role tuple now rides the script output, reprinted fresh every
round, immune to compaction by construction:
- task-brief prints role=implementer terra/high fork_turns=none
- review-package prints per role via a new leading --role flag
  (task-review default | re-review | final-review), and SKILL.md call
  sites pass the flag at the re-review and final-review sites
- SKILL.md Model Selection now defers to platform role tables and the
  printed dispatch hints, closing the 'most capable model' loophole
- codex-tools.md tells the controller to copy the printed tuple verbatim

Harness detection considered and rejected: gating the print on CODEX_CI
risks a silent no-op in exactly the environment that needs it; the line
is labeled '(codex spawn_agent)' instead, and CC controllers — whose
templates carry their own model fields — can ignore it.

Experiment branch for PRI-2672 validation; not for merge without eval
evidence.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-21 14:30:12 -07:00
Drew Ritter 3921dc9998 exp(codex): surgical spinout mitigations for PRI-2672 manual App validation
Experiment branch — NOT for merge without eval evidence (writing-skills
discipline; RED/GREEN campaign to follow if the manual run validates).

Two targeted changes against the measured Codex 5.6-era spinout
(36% of SDD runs >8h, PRI-2672):

1. codex-tools.md — SDD dispatch rules: fork_turns "none" on every
   spawn (the default "all" forks the whole transcript and refuses
   model/effort overrides — S2's terminal 13-agent final wave was all
   full-history forks at sol/xhigh); capability-check for 0.145+ spawn
   params with an explicit terra/high role table (re-review terra/medium),
   no sol seats, no effort escalation between fix rounds; honest
   inheritance warning for <=0.144 where routing is impossible (T0-probed
   on 0.144.4: schema is {task_name, message, fork_turns} only, role
   TOMLs inert).

   Role-table bet: census shows task seats already ran terra/high in the
   spinout sessions — the surgical bet is fork_turns:none + no-sol-seats
   + wave termination, not task-seat downgrade. T1 cross-review matrix
   will refine reviewer tiers (may support terra/medium or lower).

2. SKILL.md final review — wave closure is policy, not a verdict:
   strong reviewers find real defects indefinitely, so "review until
   clean" never terminates; new breakage in the final fix diff joins
   residual adjudication instead of opening wave two; one-off human
   review procedures (competing reviewers, scoring) never become
   standing. Two matching rationalization-table rows.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-21 12:36:50 -07:00
Jesse Vincent cc690476fc feat(sdd): lifecycle restructure with resume-based fix loop, five-round breaker, and rationalization table 2026-07-19 12:36:33 -07:00
Jesse Vincent 7ce7620d44 feat(sdd): align templates and codex reference with resume-based fix rounds 2026-07-19 12:36:33 -07:00
Jesse Vincent f428cba185 feat(sdd): add scoped re-review prompt template 2026-07-19 12:36:33 -07:00
Jesse Vincent eb1ff1f11f 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.
2026-07-19 12:36:33 -07:00
Jesse Vincent bea92dce1a 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.
2026-07-19 12:36:33 -07:00
Jesse Vincent 0634449ca6 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.
2026-07-19 12:04:46 -07:00
Jesse Vincent 3fe3cb0530 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.
2026-07-19 12:04:46 -07:00
Jesse Vincent fe0b24390e docs(windows): document shell:bash hook dispatch and the PowerShell/CMD fallback hazards 2026-07-19 12:03:59 -07:00
Jesse Vincent df78c6bfaf 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
2026-07-19 12:03:59 -07:00
Jesse Vincent 30ff376cb6 chore(sdd): consistency sweep for plan-scoped workspace signatures 2026-07-19 12:03:18 -07:00
Jesse Vincent 75f4e9414e eval(sdd): GREEN results — plan-scoped resolution replaces cross-plan forensics 2026-07-19 12:03:18 -07:00
Jesse Vincent c15e041e03 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.
2026-07-19 12:03:18 -07:00
Jesse Vincent 9816a9cee2 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.
2026-07-19 12:03:18 -07:00
Jesse Vincent 9d9eae52f9 eval(sdd): RED baseline — 25/25 controllers refuse stale ledgers, at a forensic cost 2026-07-19 12:03:18 -07:00
Jesse Vincent 6ddb0bfcd9 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.
2026-07-19 12:03:18 -07:00
Jesse Vincent 194907435d 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.
2026-07-19 12:03:18 -07:00
Jesse Vincent c10431b14c 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).
2026-07-19 12:03:18 -07:00
Jesse Vincent 0da87665c8 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.
2026-07-19 12:03:18 -07:00
Jesse Vincent 20940deae8 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.
2026-07-19 12:03:18 -07:00
Jesse Vincent fb7b07088e 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
2026-07-15 19:15:16 +00:00
Gaurav Dubey 7a81eb7177 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.
2026-07-15 11:10:55 -07:00
Gaurav Dubey 2b1c06a849 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.
2026-07-15 11:10:55 -07:00
Jesse Vincent 4562d18dcf 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.
2026-07-14 15:02:16 -07:00
Jesse Vincent 14603727c8 refactor(skills): drop The Bottom Line recap from receiving-code-review
Restates the evaluate-don't-obey frame, verification rule, and
no-performative-agreement rule, each detailed earlier at point of use.
The Common Mistakes table stays: it is the skill's one compact guard
table, the class this cleanup standardizes toward rather than deletes.
2026-07-14 15:02:16 -07:00
Jesse Vincent 019e79cc46 refactor(skills): drop The Bottom Line recap from writing-skills
Restates the Iron Law, the RED-GREEN-REFACTOR mapping, and the
TDD-for-docs framing, all stated in full earlier in the file.
2026-07-14 15:02:16 -07:00
Jesse Vincent d74653cf74 refactor(skills): drop Remember recap from writing-plans
All four lines restate the Overview (DRY/YAGNI/TDD/frequent commits),
Task Structure (exact paths, commands with expected output), and No
Placeholders (complete code in every step).
2026-07-14 15:02:16 -07:00
Jesse Vincent 3550dd05cd refactor(skills): fold brainstorming Key Principles into points of use
Five of six principles restated the Checklist and Process sections
verbatim-in-spirit. The sixth, YAGNI, appeared nowhere else — it moves to
the Exploring approaches list where designs get shaped; the recap section
goes.
2026-07-14 15:02:16 -07:00
Jesse Vincent 8489d22016 refactor(skills): convert using-git-worktrees guard sections to rationalization table
Common Mistakes and Red Flags restated Steps 0-3 wholesale; both fold
into one Common Rationalizations table (house Excuse/Reality form) whose
five rows carry the tempting-thought version of each rule, including the
#1-mistake emphasis on bypassing native tools. Quick Reference stays as
the compact decision aid.
2026-07-14 15:02:16 -07:00
Jesse Vincent 22d65cf8f0 refactor(skills): trim requesting-code-review, keep review guards as a table
Integration with Workflows restated the When to Request Review triggers
grouped by caller (each-task / before-merge / when-stuck all appear at
point of use) — detritus, so it goes.

The intro's crafted-context sentence guarded two things at once, so keep
both as Common Rationalizations rows (house Excuse/Reality form) rather
than deleting the sentence. The skill's reader is the coordinator, not
the code's author:

- Don't review the diff inline — that burns the coordinator's context
  window; dispatch a subagent so the diff and evaluation live in its
  context and only findings return. ("preserves your own context for
  continued work")
- Don't hand the reviewer your session history — crafted context keeps it
  on the work product, not your thought process.
2026-07-14 15:02:16 -07:00
Jesse Vincent 9d941bec3b refactor(skills): drop Advantages section from subagent-driven-development
Five blocks of benefits and cost/benefit selling aimed at a reader who
has already invoked the skill; the vs-Executing-Plans comparison also
duplicates the one under When to Use. Integration section untouched
(PR #1932 owns it).
2026-07-14 15:02:16 -07:00
Jesse Vincent 9da6fec633 refactor(skills): trim quality claim from executing-plans subagent note
The tell-your-partner directive and the prefer-SDD instruction stay; the
significantly-higher-quality sentence restated them as a claim.
Integration section untouched (PR #1932 owns it).
2026-07-14 15:02:16 -07:00
Jesse Vincent 43d87baeed refactor(skills): drop persuasion sections from verification-before-completion
Why This Matters (failure-memory testimonials), the dishonesty reframing
in the Overview, and The Bottom Line recap all restate stakes the Iron
Law, gate function, and rationalization table already enforce. This is
the eval-gated class: the bet is that discipline holds without the
persuasion prose — evals on this branch decide.
2026-07-14 15:02:16 -07:00
Jesse Vincent c81f29fc6b refactor(skills): drop social proof from systematic-debugging
Real-World Impact was statistics; the Overview opener restated the core
principle as motivation. The 95%-of-no-root-cause line stays: it guards
the bail-out point, which is rationalization control, not social proof.
Supporting Techniques/Related skills untouched (PR #1932 owns that).
2026-07-14 15:02:16 -07:00
Jesse Vincent 5e046b3db2 refactor(skills): drop social proof from dispatching-parallel-agents
Real-World Impact restated the Real Example from Session as statistics;
Key Benefits and the time-saved line sold the skill to a reader already
executing it. Instructions unchanged.
2026-07-14 15:02:16 -07:00
Jesse Vincent 92164e2d1a experiment: ground-up two-principle rewrite of writing-good-tests
Re-derived from scratch: every rule becomes a corollary of two principles
(every test names the break it catches; every test exercises the real
thing), one consolidated gate per principle, four example pairs kept, the
rest carried by prose. Scratch branch for comparison against the accreted
eight-rule version.
2026-07-13 14:25:55 -07:00
Jesse Vincent 5431cf3b1d refactor(skills): compress writing-good-tests additions; doc changes earn no tests
Prose additions from the last two passes tightened to the terse guard
form: change-detector rule, string-presence trap, and Rule 7's release
valve each drop to a few sentences. Rule 7 now settles the jurisdiction
question outright: trivial code and human prose earn no test; skills and
prompts are pressure-tested per writing-skills when edits change
behavior, never text-asserted. Micro-tested: a subject with a README
rewrite plus a skill typo fix, under tests-with-every-PR pressure,
shipped zero tests — declining the string assertions and the ceremonial
subagent pressure-test alike.
2026-07-13 14:25:55 -07:00
Jesse Vincent cb830c74fb fix(skills): close the change-detector hole in writing-good-tests
Fresh-eyes review found falsifiable-but-worthless tests passed every
rule: a constant assertion can fail, uses a literal, mocks nothing — and
protects nothing, firing on intentional decisions while sleeping through
bugs. Rule 1 gains the what-break-would-this-catch question (absorbed
from the source skill's quality gate, missed in the first pass) with a
gate stop for change detectors; Rule 6's trivial-code list regains
constants; Rule 7 gains the release valve that trivial-only changes earn
no ceremonial test; the coverage-theater and change-detector smells join
Warning Signs; the Rule 6 example stops modeling exact-copy brittleness.
Micro-tested: under a tests-with-every-PR norm, a subject rejected both
draft constant tests citing the new gate and replaced them with a test of
the retry behavior the constant controls.
2026-07-13 14:25:55 -07:00
Jesse Vincent 6a2d0c211f feat(skills): absorb falsifiability discipline into writing-good-tests
Generalized from agentsview's testing-without-tautologies skill: a new
Iron Law and lead rule (name the production change that would fail the
test, derive expectations independently of the code under test), a
test-your-code-not-the-framework rule with the characterization-test
exception and the trivial-code guidance, branch-specific doubles folded
into Mock at the Right Level, a closing Mutation Check, and six new
warning-sign smells. Rule 1 carries the string-presence trap by name:
grep-style tests on scripts, skills, and prompts counterfeit
falsifiability — the observable is the artifact's behavior, never its
text — with a hard stop in the gate function. Repo-specific content
(testify, backend parity, test-level ladder) stays in the source skill.
Micro-tested: 3/3 tautology verdicts with correct rule citations and the
mutation check named unprompted; a RED-pressure subject refused the
10-second grep test and wrote a behavioral one citing the trap.
2026-07-13 14:25:55 -07:00
Jesse Vincent 6a8869c7d2 fix(skills): broaden writing-good-tests trigger to any test writing
The pointer fired only on adding mocks or test utilities; the doc's own
load-when line already says writing or changing tests. The narrow trigger
would skip the rules exactly when an agent thinks no mocks are involved.
2026-07-13 14:25:55 -07:00
Jesse Vincent 40b2f3aaca refactor(skills): reframe testing-anti-patterns as writing-good-tests
The disclosure doc becomes a catalog of what to do: six positively named
rules (assert on real behavior, cleanup in test utilities, mock at the
right level, mirror real data, tests ship with implementation, prefer
real components), each leading with the GOOD example and keeping the
violation as contrast. Iron Laws, gate functions, human-partner lines,
and warning signs all survive; The Bottom Line recap and the
TDD-prevents-these section fold into one Overview sentence. SKILL.md's
pointer moves into the Good Tests section it belongs with. Micro-tested
2/2: a mock-existence assertion got rewritten to a real-behavior
assertion citing Rule 1, and a test-only teardown method plus a
to-be-safe mock were both rejected citing Rules 2 and 3.
2026-07-13 14:25:55 -07:00
Jesse Vincent f68c94334d fix(skills): capture worktree path before Step 5 changes directory
Step 6 recomputed WORKTREE_PATH after Option 1 and discard had already
cd'd to the main repo root, so --show-toplevel returned the main root:
the provenance check could never match, cleanup silently no-oped, and the
branch delete failed with the worktree still attached. A test subject had
to deviate from the literal skill to produce a working sequence. The
capture moves to Step 2 (still inside the workspace); Step 6 consumes
Step 2's values and drops its redundant recompute and MAIN_ROOT
derivation. Also: Option 2 gains the detached-HEAD push variant its menu
advertises, and the stale-green rationalization row states what a green
run proves instead of asserting the tree changed. Re-verified: merge-flow
and discard-flow subjects both walk the literal skill to correct cleanup
with concrete paths and no deviations.
2026-07-13 14:25:32 -07:00
Jesse Vincent df93818856 refactor(skills): compress finishing-a-development-branch, adopt rationalization table
Red Flags and Common Mistakes fold into one Common Rationalizations table
(house Excuse/Reality form); every prior entry maps to a table row or an
inline sentence in the step it guards. Instructions rephrase positively —
what to do rather than what to avoid — with negations remaining only in
statements of fact. Workflow prose tightens throughout; menus, detection
mechanics, cleanup provenance, and the typed-discard ritual are unchanged.
Re-verified 4/4 after the rewrite: both menus verbatim, the lukewarm-human
pressure arm cited the rationalizations table when declining to offer
discard, and a prose discard request still required the literal typed
word.
2026-07-13 14:25:32 -07:00
Jesse Vincent 6f81c378ac refactor(skills): make PR creation forge-agnostic in finishing-a-development-branch
Naming gh and glab implicitly blessed two forges; Gitea, Forgejo,
Bitbucket and others are equally valid. Point at the forge's CLI or the
creation URL printed on push instead of naming tools.
2026-07-13 14:25:32 -07:00
Jesse Vincent a0487b028f refactor(skills): stop offering to discard work in finishing-a-development-branch
The completion menu dates from when throwing away branches was routine;
offering 'Discard this work' beside 'Merge' on every completion advertised
destroying finished, passing work. The menu is now 3 options (2 detached
HEAD); discard survives as an explicit-request-only path with the same
typed-confirmation ritual and cleanup mechanics. Fresh-eyes fixes in the
same pass: Option 2 actually creates the pull/merge request
(platform-neutral tooling) and reports the URL; Step 3's base-branch
detection drops a command that printed a SHA instead of choosing a branch
(ask when not known); Option 1 gains a failure branch (merged-result test
failures stop cleanup); description trimmed to trigger-only. Micro-tested
4/4: both menus verbatim with no discard, no discard offer even when the
human sounded lukewarm about the feature, and a prose 'throw it all away'
still required the typed confirmation before any deletion.
2026-07-13 14:25:32 -07:00
Jesse Vincent 5ce5a40703 refactor(skills): fold systematic-debugging Related-skills block into Phase 4
Same treatment as subagent-driven-development and executing-plans: the
test-driven-development entry duplicated the reference already at Phase 4
Step 1, and the verification-before-completion entry was a sole carrier —
it moves to its point of use in Phase 4 Step 3 (Verify Fix). Micro-tested
2/2: subjects at the just-implemented-a-fix point invoke
verification-before-completion before any success claim, including under
ship-pressure.
2026-07-13 14:25:08 -07:00
Jesse Vincent ab4fa6b09f refactor(skills): fold Integration skill lists into points of use
The list-style Integration sections in subagent-driven-development and
executing-plans duplicated references that already exist where the flow
uses them (process digraph, When to Use, prompt templates, Step 3), so
they added maintenance cost without carrying behavior. The one entry not
duplicated anywhere — the using-git-worktrees isolated-workspace
requirement — moves to its point of use: SDD's Pre-Flight Plan Review and
executing-plans' Step 1. Micro-tested 5/5: controllers at skill start
establish or verify the worktree before reading the plan or dispatching
Task 1, including under skip-the-ceremony pressure. The prose Integration
sections in requesting-code-review and other skills are unchanged — they
carry placement content, not an index.
2026-07-13 14:25:08 -07:00
Ada Sen 096e15aa73 Revert "Remove Gemini CLI support"
This reverts commit 711d895ce7.
2026-07-10 11:58:08 -04:00
Jesse Vincent c809093a2a Release v6.1.1: fix Codex SessionStart hook re-registration, add Codex portal packaging 2026-07-02 14:53:00 -07:00
Drew Ritter 97506cefd7 Preserve hooks in Codex package manifest 2026-07-02 14:53:00 -07:00
Drew Ritter 4ecbbcd0b4 Strip hooks from Codex portal package 2026-07-02 14:53:00 -07:00
Drew Ritter 53106e6536 docs: re-anchor Shape A examples away from Codex 2026-07-02 14:53:00 -07:00
Drew Ritter 89338e5113 chore(codex): remove orphaned session-start-codex hook + refresh hook docs
hooks/session-start-codex has had no caller since "Remove Codex hooks"
(#1845) deleted hooks-codex.json and its manifest registration; the
Codex manifest now declares an empty hooks object so Codex registers no
session-start hook at all. The script is Codex-specific dead code —
nothing executes it on Codex or any other harness.

- Delete hooks/session-start-codex.
- tests/hooks/test-session-start.sh: drop the two Codex cases that are
  redundant with the generic session-start tests (nested-format and the
  legacy-warning omission are already covered by the Claude Code cases).
  Re-point the "wrapper dispatches" case to the live `session-start`
  script so run-hook.cmd dispatch coverage — used by Claude Code and
  Cursor in production — is preserved rather than lost.
- docs/porting-to-a-new-harness.md: Codex is no longer a Shape A
  (shell-hook) harness, so re-anchor that worked example to Cursor (a
  live shell-hook harness that demonstrates the same per-harness field,
  schema, and matcher variance) and mark Codex as native skill discovery
  with no session-start hook. Clears the references to the deleted
  hooks-codex.json.
- docs/windows/polyglot-hooks.md: the "check hooks-codex.json" pointer
  referenced a file deleted in #1845; re-point to hooks-cursor.json.

RELEASE-NOTES.md keeps its historical mention of hooks-codex.json (it
accurately records what that release did). The tests/codex-plugin-sync
fixtures build their own synthetic session-start-codex and test the sync
mechanism generically, so they are intentionally left as-is.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 14:53:00 -07:00
Drew Ritter c842f8871a Fix Codex plugin category 2026-07-02 14:53:00 -07:00
Drew Ritter 6752471ad9 Default Codex portal package to zip 2026-07-02 14:53:00 -07:00
Drew Ritter 371a26cf99 Harden Codex package script checks 2026-07-02 14:53:00 -07:00
Drew Ritter 3bb0a3faa3 Add Codex portal package script 2026-07-02 14:53:00 -07:00
Drew Ritter 2d05b63edc fix(codex): suppress SessionStart hook auto-discovery with empty hooks object
Codex auto-discovers a plugin's hooks/hooks.json whenever the Codex
manifest has no `hooks` field: load_plugin_hooks falls back to a
hardcoded DEFAULT_HOOKS_CONFIG_FILE = "hooks/hooks.json" and registers
it. hooks/hooks.json is the Claude Code SessionStart hook, it is tracked
in this repo, and the Codex marketplace installs the whole repo root
(source url "./"), so the fallback re-registered the SessionStart hook
and its install-time trust prompt on Codex.

Removing the Codex hook file and the manifest `hooks` pointer (commit
"Remove Codex hooks") did not disable the hook on Codex — it removed the
explicit declaration that was overriding the fallback, so the fallback
took over and found the Claude hooks/hooks.json.

Declare an empty inline hooks object ({}) in .codex-plugin/plugin.json.
It parses as an empty inline hook set and stops Codex reaching the
auto-discovery fallback. An absent field, an empty array ([]), and an
empty inline list all collapse back to the fallback, so the value must
be exactly {}.

Update the test to assert the manifest declares hooks: {} (and that
hooks/hooks.json exists, which is what makes the declaration necessary),
replacing the prior assertion that the field was absent — which passed
while the hook was still being auto-discovered.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 14:53:00 -07:00
27 changed files with 498 additions and 205 deletions
+1 -1
View File
@@ -9,7 +9,7 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
"version": "6.2.0",
"version": "6.1.1",
"source": "./",
"author": {
"name": "Jesse Vincent",
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
"version": "6.2.0",
"version": "6.1.1",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "superpowers",
"version": "6.2.0",
"version": "6.1.1",
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
"author": {
"name": "Jesse Vincent",
@@ -21,7 +21,7 @@
"workflow"
],
"skills": "./skills/",
"hooks": {},
"hooks": "./hooks/hooks-codex.json",
"interface": {
"displayName": "Superpowers",
"shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
+1 -1
View File
@@ -2,7 +2,7 @@
"name": "superpowers",
"displayName": "Superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
"version": "6.2.0",
"version": "6.1.1",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "superpowers",
"version": "6.2.0",
"version": "6.1.1",
"description": "An agentic skills framework and software development methodology.",
"author": {
"name": "Jesse Vincent",
+16
View File
@@ -98,6 +98,22 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
- Select `Install Plugin`.
#### Codex: compaction re-injection hook
Codex compacts long sessions, replacing the transcript with a summary that
drops Superpowers' skill instructions mid-run — long autonomous workflows
(like subagent-driven-development) then drift back to harness defaults.
Claude Code re-injects the bootstrap after every compaction; the plugin ships
a SessionStart hook (`hooks/hooks-codex.json`) that restores the same
behavior on Codex (0.145+). It fires only on post-compaction re-starts
(`source: "compact"`) and is silent at normal session start.
The hook installs with the plugin — no configuration needed. Codex asks you
to review and trust it once, the first time it loads after install or update.
Headless automation (CI, eval harnesses) must pass
`--dangerously-bypass-hook-trust` instead, because untrusted hooks are
skipped silently.
### Cursor
- In Cursor Agent chat, install from marketplace:
-33
View File
@@ -1,38 +1,5 @@
# Superpowers Release Notes
## v6.2.0 (2026-07-23)
### Subagent-Driven Development
Two structural changes to how SDD tracks progress and closes out review findings, both developed against live eval campaigns.
- **The workspace is now plan-scoped.** `.superpowers/sdd/` had no plan identity and no end-of-life: a follow-up plan in the same working tree could read the previous plan's ledger as its own progress (observed in the wild, with multiple contamination rounds and ad-hoc workarounds). `sdd-workspace` now requires the plan file and resolves a per-plan directory, `.superpowers/sdd/<plan-basename>/`; `task-brief` and `review-package` write into their plan's directory (`review-package` gains the plan file as its first argument); the ledger names its plan on its first line; and the workspace is deleted once the final review is clean — git history is the durable record. Baseline evals showed controllers already refused foreign ledgers, but at a cost of 613 tool calls of cross-plan git forensics per resume; plan-scoping makes the answer structural instead. (25/25 baseline and GREEN eval runs documented in `docs/specs/` and `docs/plans/`.)
- **The review-fix loop resumes the implementer.** The lifecycle restructure gives fix rounds resume-the-implementer semantics instead of fresh dispatches, adds a scoped re-review prompt (`re-review-prompt.md`) so the re-reviewer checks the fixes rather than re-reading the whole task, and installs a five-round circuit breaker with controller adjudication when it trips. SKILL.md reorganizes by lifecycle, and its Red Flags convert to the house rationalization-table form.
### Skills
A branch-wide compression campaign: recap sections, social proof, and benefits-selling prose aimed at a reader who has already invoked the skill are gone, with every load-bearing argument folded into a rationalization-table row or moved to its point of use. Each cut was micro-tested with subagent probes, and the one cut that measurably degraded behavior was reworked rather than shipped.
- **`testing-anti-patterns.md` is now `writing-good-tests.md`.** The TDD reference doc is rebuilt as a positive catalog — six rules that lead with the GOOD example — and absorbs a falsifiability discipline: name the production change that would fail the test, derive expectations independently of the code under test, and a closing mutation check. It closes two holes by name: the string-presence trap (grep-style tests on scripts, skills, and prompts counterfeit falsifiability — the observable is behavior, never text) and the change-detector trap (a constant assertion can fail and still protect nothing), each with a hard stop in the gate function. Trivial code and human prose earn no test; the trigger broadens from "adding mocks" to any test writing.
- **TDD's "Why Order Matters" rebuttals survive as rationalization rows.** Deleting the section outright measurably degraded test-first behavior under "just write it, tests after" pressure (control 8/10 → treatment 5/10, corroborated on Claude and Codex), so each prose rebuttal now lives in its Common Rationalizations row — the section is gone but the arguments fire where an agent hits them mid-rationalization.
- **`finishing-a-development-branch` no longer offers to discard your work.** The completion menu dates from when throwing away branches was routine; "Discard this work" next to "Merge" advertised destroying finished, passing work. Discard survives as an explicit-request-only path with the same typed-confirmation ritual. The same pass made PR creation forge-agnostic (your forge's CLI or the URL printed on push, not a blessed list of tools) and fixed a real bug: the worktree path was recomputed after cleanup had already changed directory, so provenance checks never matched and cleanup silently no-oped.
- **Recap and persuasion prose removed across the library.** `brainstorming`, `systematic-debugging`, `dispatching-parallel-agents`, `verification-before-completion`, `executing-plans`, `subagent-driven-development`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `writing-plans`, and `writing-skills` all drop their Bottom Line / Key Principles / Real-World Impact / Advantages sections; `using-git-worktrees` and `finishing-a-development-branch` convert their guard sections to the house Excuse/Reality rationalization table.
### Windows
- **The SessionStart hook now dispatches via Git Bash.** The hook's command string starts with a quoted path, which broke both shells Claude Code might hand it to: PowerShell parsed the quoted string as an expression and died with a parser error (#1751), and cmd.exe's quote-stripping rule truncated the command when the profile path contained a metacharacter like `(` (#1918) — either way the bootstrap silently never loaded. The hook now declares `shell: "bash"`, which Claude Code ≥ 2.1.81 resolves to Git for Windows directly, and which surfaces an actionable install prompt when Git Bash is missing. Older Claude Code versions ignore the unknown key and behave as before. Verified end-to-end on Linux, Windows 11 with Git Bash under a hostile path, and Windows 11 without Git Bash.
### Harness Support
- **Gemini CLI support is restored.** The v6.1.0 removal (on the news that Google had EOLed the Gemini CLI) was premature; the install docs and the `gemini-tools.md` tool-mapping reference are back while permanent removal gets a proper evaluation. (#1959)
### Fixes
- **`find-polluter.sh` actually finds test files now.** `find .` emits `./`-prefixed paths, so the documented `-path "src/**/*.test.ts"` pattern matched nothing — and `wc -l` on empty input then reported "Found 1". Fixed the prefix mismatch (#2008, #2011), plus two follow-ups: a caller-supplied `./`-prefixed pattern no longer double-prefixes into a never-matching form, and `**/` is also matched collapsed so tests directly under the base directory (`src/top.test.ts` vs `src/**/*.test.ts`) aren't silently skipped. The script gains a deterministic test suite.
- **The Codex package script works beyond macOS.** Deterministic-metadata tar flags were bsdtar-only spellings, staged file modes depended on two umasks canceling out, and the test's timestamp assertion parsed bsdtar's column layout in a US timezone. GNU tar now gets equivalent flags producing byte-identical headers, modes are pinned canonical, and the test asserts mtime via `tarfile`.
- **SDD's skill test no longer flakes.** The file's worst case exceeded the runner's per-file ceiling (raised to 900s), and the assert helpers matched free-form model prose case-sensitively; matching is now case-insensitive and `assert_order` dumps output on failure so the next flake is diagnosable.
- **Docs and test cleanup after the v6.1.0 reference pruning.** Dead links to the deleted `claude-code-tools.md`/`copilot-tools.md` are replaced with the current architecture (#1969), a dangling `#subagent-support` anchor in the Antigravity reference is dropped (#2010), and the Antigravity/Pi mapping tests assert only the surviving harness-specific mappings — scoped to the table so they fail again if it's deleted.
## v6.1.1 (2026-07-02)
### Codex
+7 -5
View File
@@ -237,10 +237,12 @@ nesting differ per harness**.
- Manifests: `.cursor-plugin/plugin.json` is the Shape A manifest example that
points the harness at `./skills/` and the right `hooks-*.json`. Claude Code's
`.claude-plugin/plugin.json` sets neither field — it auto-discovers `skills/`
and `hooks/hooks.json` by convention. Do **not** copy Codex's
`.codex-plugin/plugin.json` for Shape A: it declares an empty `hooks` object
specifically to suppress Codex's `hooks/hooks.json` auto-discovery, because
Codex surfaces skills natively and runs no session-start hook.
and `hooks/hooks.json` by convention. Codex's `.codex-plugin/plugin.json`
points `hooks` at `./hooks/hooks-codex.json` — a compaction-only hook, not a
bootstrap injector: Codex surfaces skills natively at session start, so its
hook fires only on post-compaction re-starts. The explicit pointer also
suppresses Codex's `hooks/hooks.json` auto-discovery fallback, which would
otherwise run the Claude Code hook.
> **A hook *system* is not a session-start *event*.** A harness can have a
> `hooks.json` mechanism — and even contain the literal string `SessionStart` in
@@ -785,7 +787,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 |
|---|---|---|---|---|---|
| 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`) |
| Codex | `.codex-plugin/plugin.json` + `hooks/hooks-codex.json` | native skill discovery at startup; shell hook → `hooks/session-start-codex` re-injects after compaction only | `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 Codecompatible tool surface) | `tests/hooks/` | hand-authored |
| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | none needed (Claude Codecompatible tool surface) | `tests/hooks/` | — |
| Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
"version": "6.2.0",
"version": "6.1.1",
"contextFileName": "GEMINI.md"
}
+17
View File
@@ -0,0 +1,17 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{
"type": "command",
"command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-codex",
"async": false,
"timeout": 30
}
]
}
]
}
}
+56
View File
@@ -0,0 +1,56 @@
#!/usr/bin/env bash
# Codex SessionStart hook for the superpowers plugin.
#
# Codex re-fires SessionStart with source:"compact" after every context
# compaction (verified on codex-cli 0.145.0). Compaction replaces the live
# context with a summary, which sheds the using-superpowers bootstrap and any
# active skill's instructions — the measured cause of mid-session dispatch
# drift in long multi-agent runs. This hook re-injects the bootstrap at
# exactly that moment, restoring the same re-injection Claude Code performs
# via its "startup|clear|compact" SessionStart matcher.
#
# On source:"startup" it emits nothing: the native Codex plugin path owns
# session-start injection, and duplicating it here would recreate the
# redundancy that led to the original session-start-codex hook's removal.
#
# Codex injects raw hook stdout into the model's context (verified with
# sentinel probes), so output is plain text — not the JSON envelopes other
# harnesses require of hooks/session-start.
#
# A hook failure must never break a session: every path fails open to empty
# output and exit 0.
set -u
payload="$(cat 2>/dev/null || true)"
# Act only on post-compaction re-fires. Tolerate arbitrary whitespace around
# the JSON colon; anything unparseable falls through to a silent no-op.
if ! printf '%s' "$payload" | grep -qE '"source"[[:space:]]*:[[:space:]]*"compact"'; then
exit 0
fi
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
using_superpowers_content="$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>/dev/null)" || using_superpowers_content=""
if [ -z "$using_superpowers_content" ]; then
exit 0
fi
# printf instead of heredocs throughout: heredocs hang on bash 5.3+.
# See: https://github.com/obra/superpowers/issues/571
printf '%s\n' "<EXTREMELY_IMPORTANT>"
printf '%s\n\n' "You have superpowers."
printf '%s\n\n' "**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**"
printf '%s\n' "$using_superpowers_content"
printf '%s\n\n' "</EXTREMELY_IMPORTANT>"
printf '%s\n' "<CONTEXT_RESTORED>"
printf '%s\n' "Your context was just summarized (compacted). The summary preserves your progress but not your working instructions — the files are authoritative."
printf '%s\n' ""
printf '%s\n' "Before your next tool call:"
printf '%s\n' "- Re-read the SKILL.md of any skill you are mid-way through executing. If you are executing subagent-driven-development, re-read skills/subagent-driven-development/SKILL.md."
printf '%s\n' "- On Codex, also re-read skills/using-superpowers/references/codex-tools.md and follow its dispatch rules on every spawn_agent call."
printf '%s\n' "</CONTEXT_RESTORED>"
exit 0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "superpowers",
"version": "6.2.0",
"version": "6.1.1",
"description": "Superpowers skills and runtime bootstrap for coding agents",
"type": "module",
"main": ".opencode/plugins/superpowers.js",
+7 -3
View File
@@ -40,8 +40,9 @@ Options:
-h, --help Show this help.
The archive is rootless: .codex-plugin/, assets/, skills/, README.md, LICENSE,
and CODE_OF_CONDUCT.md sit at the archive root. Source-only repo files, hooks, tests,
docs, and other harness manifests are intentionally not shipped.
CODE_OF_CONDUCT.md, and the Codex SessionStart hook (hooks/hooks-codex.json plus
its two scripts) sit at the archive root. Source-only repo files, other-harness
hooks, tests, docs, and other harness manifests are intentionally not shipped.
EOF
}
@@ -238,6 +239,9 @@ git -C "$REPO_ROOT" -c tar.umask=0022 archive --format=tar "$REF" -- \
LICENSE \
README.md \
assets \
hooks/hooks-codex.json \
hooks/run-hook.cmd \
hooks/session-start-codex \
skills \
| tar -xpf - -C "$STAGE"
@@ -333,7 +337,7 @@ esac
unexpected_paths="$(
printf '%s\n' "$archive_paths" |
grep -E '(^superpowers/|^\.agents/|^hooks/|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)' || true
grep -E '(^superpowers/|^\.agents/|^hooks/hooks\.json$|^hooks/hooks-cursor\.json$|^hooks/session-start$|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)' || true
)"
if [[ -n "$unexpected_paths" ]]; then
printf '%s\n' "$unexpected_paths" | sed 's/^/ /' >&2
+40 -22
View File
@@ -59,7 +59,7 @@ digraph process {
"Finding conflicts with plan text?" [shape=diamond];
"Ask human partner which governs" [shape=box];
"Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
"Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
"Dispatch scoped fix review (./fix-review-prompt.md)" [shape=box];
"All findings addressed?" [shape=diamond];
"R = 5?" [shape=diamond];
"Adjudicate each open finding" [shape=box];
@@ -72,7 +72,7 @@ digraph process {
"Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
"More tasks remain?" [shape=diamond];
"Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
"Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
"Final findings? ONE fix dispatch, one scoped fix review, adjudicate residuals" [shape=box];
"Final review clean: delete this plan's workspace" [shape=box];
"Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
@@ -88,8 +88,8 @@ digraph process {
"Finding conflicts with plan text?" -> "Ask human partner which governs" [label="yes"];
"Ask human partner which governs" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
"Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
"Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
"Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
"Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped fix review (./fix-review-prompt.md)";
"Dispatch scoped fix review (./fix-review-prompt.md)" -> "All findings addressed?";
"All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
"All findings addressed?" -> "R = 5?" [label="no"];
"R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
@@ -101,8 +101,8 @@ digraph process {
"Append completion to ledger, mark todo complete" -> "More tasks remain?";
"More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
"More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
"Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
"Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
"Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped fix review, adjudicate residuals";
"Final findings? ONE fix dispatch, one scoped fix review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
"Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
}
```
@@ -158,6 +158,12 @@ conflicts that only emerge from implementation.
Use the least powerful model that can handle each role to conserve cost and increase speed.
When your platform's reference file (using-superpowers → Platform
Adaptation) defines a dispatch role table, that table IS this section's
mapping for your harness. Follow it over the tier language below — including
for the final review and fix-loop escalation — and follow the
`dispatch:` hint lines the task-brief and review-package scripts print.
**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
@@ -168,7 +174,7 @@ capable available model, not the session default.
**Review tasks**: choose the model with the same judgment, scaled to the
diff's size, complexity, and risk. A small mechanical diff does not need the
most capable model; a subtle concurrency change does. Scoped re-reviews of
most capable model; a subtle concurrency change does. Scoped fix reviews of
small fix diffs take a cheap-to-mid tier.
**Fix-loop escalation (rounds 4-5)**: use a model at least one tier above
@@ -317,7 +323,8 @@ Before the loop starts, two routes leave it immediately:
Do not dismiss the finding because the plan mandates it, and do not
dispatch a fix that contradicts the plan without asking.
Everything else enters the loop. A fix round is one fix dispatch plus one
scoped re-review. Five rounds maximum per task:
scoped fix review — a review of the fix diff, not a fresh review. Five
rounds maximum per task:
**Rounds 1-3 — resume the original implementer.** Send it the open findings
verbatim. Its context is intact: it knows the task, the code, and its own
@@ -336,14 +343,14 @@ own problem — fresh eyes and a capability bump in one move.
covering the amended code, appends its fix report to the same report file,
and returns the short contract. Before re-dispatching the reviewer, confirm
the fix report contains the covering tests, the command run, and the
output; dispatch the re-review once all three are present. Name the
output; dispatch the fix review once all three are present. Name the
covering test files in the fix message — a one-line fix does not need the
whole suite.
**The re-review is scoped.** Run `scripts/review-package PLAN_FILE FIX_BASE HEAD`
**The fix review is scoped.** Run `scripts/review-package --role fix-review PLAN_FILE FIX_BASE HEAD`
where FIX_BASE is the head the previous review saw, and dispatch
[re-review-prompt.md](re-review-prompt.md) with the findings list, the
brief, the report file, and the printed diff path. The re-reviewer verdicts
[fix-review-prompt.md](fix-review-prompt.md) with the findings list, the
brief, the report file, and the printed diff path. The fix reviewer verdicts
each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
diff only. New Critical/Important breakage in the fix diff joins the open
findings list. Out-of-scope observations go to the ledger as deferred
@@ -355,7 +362,7 @@ minors — they never extend the loop.
Never fix findings yourself in the controller session — your context stays
clean for coordination, and controller fixes skip review.
**The breaker.** When round 5's re-review still leaves findings open, stop
**The breaker.** When round 5's fix review still leaves findings open, stop
dispatching. Adjudicate each open finding yourself — you hold the plan and
the cross-task context the reviewer lacks:
@@ -391,7 +398,7 @@ parked-with-ruling at the cap.
## Final Review
The final whole-branch review gets a package too: run
`scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
`scripts/review-package --role final-review PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
branch started from, e.g. `git merge-base main HEAD`) and include the
printed path in the final review dispatch, so the final reviewer reads
one file instead of re-deriving the branch diff with git commands. Dispatch
@@ -405,14 +412,23 @@ If the final whole-branch review returns findings, dispatch ONE fix subagent
with the complete findings list — not one fixer per finding.
Per-finding fixers each rebuild context and re-run suites; a real
session's final-review fix wave cost more than all its tasks combined.
Then run exactly one scoped re-review of the fix wave
(`scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
[re-review-prompt.md](re-review-prompt.md)).
Then run exactly one scoped fix review of the fix wave
(`scripts/review-package --role fix-review PLAN_FILE FIX_BASE HEAD` over the fix range,
[fix-review-prompt.md](fix-review-prompt.md)).
Adjudicate any residual findings as in the task loop's breaker: park with
rulings, or stop on load-bearing ones. There is no second fix wave —
residual load-bearing findings surface to your human partner when
finishing-a-development-branch presents the options.
The wave closing is policy, not a verdict. A sufficiently strong reviewer
finds real defects indefinitely, so "review until one comes back clean"
never terminates — the completed wave is the exit, not a clean report.
New Critical/Important breakage in the final fix diff joins the residuals
for adjudication; it does not start a second wave. And review procedures
your human partner sets up for one review — competing reviewers, scoring,
extra seats — apply to that review only. Never adopt them as standing
procedure for reviews they didn't ask about.
## Finish
When the final whole-branch review is clean and its fixes are merged,
@@ -429,11 +445,13 @@ Use superpowers:finishing-a-development-branch.
| "Close enough on spec compliance" | Reviewer found spec gaps = not done. Fix or hit the cap and adjudicate — those are the only exits. |
| "I'll fix it myself, dispatching is overhead" | Controller fixes pollute your context and skip review. Resume the implementer. |
| "One more round will converge" | Past the cap, rounds don't converge — the failure is structural. Adjudicate and route. |
| "The reviewer will just find something new anyway" | Scoped re-reviews verify fixes; they cannot wander. New findings on untouched code go to the ledger, not the loop. |
| "The reviewer will just find something new anyway" | Scoped fix reviews verify fixes; they cannot wander. New findings on untouched code go to the ledger, not the loop. |
| "This finding is obviously wrong, I'll drop it" | You adjudicate only at the cap, and every ruling is a ledger entry. Silent discards are forbidden. |
| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. |
| "The fix was small, skip the fix review" | Unreviewed fixes are how regressions land. Every round ends with a scoped fix review. |
| "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
| "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
| "This new finding is real — one more wave" | Real findings are infinite under a strong reviewer. The completed wave is the exit; adjudicate and route. |
| "They liked competing reviewers earlier, I'll run them again" | One-off review procedures apply to the review they were given for. Re-adopting them unasked is scope creep in review clothing. |
## Example Workflow
@@ -483,8 +501,8 @@ Task reviewer: Spec ❌:
Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
[Run review-package --role fix-review PLAN_FILE FIX_BASE HEAD; dispatch scoped fix review]
Fix reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
Verdict: all findings addressed.
@@ -494,7 +512,7 @@ Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
...
[After all tasks]
[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
[Run review-package --role final-review PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
Final reviewer: All requirements met. Deferred minors triaged: none block merge.
[Delete this plan's workspace — the record now lives in git]
@@ -1,7 +1,7 @@
# Scoped Re-Review Prompt Template
# Scoped Fix Review Prompt Template
Use this template when dispatching a re-review after a fix round. The
re-reviewer verifies the findings were addressed and checks the fix diff for
Use this template when dispatching a fix review after a fix round. The
fix reviewer verifies the findings were addressed and checks the fix diff for
new breakage. It is not a fresh review — the full review already happened.
**Purpose:** Verify each finding from the previous review was addressed, and
@@ -9,11 +9,11 @@ that the fix itself broke nothing.
```
Subagent (general-purpose):
description: "Re-review Task N fix round R"
description: "Fix review Task N round R"
model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
model silently inherits the session's most expensive one]
prompt: |
You are re-reviewing one task's fix round. A previous review produced
You are reviewing one task's fix round. A previous review produced
findings; an implementer has attempted to fix them. Your job is to
verdict each finding and inspect the fix diff — nothing else.
@@ -47,7 +47,7 @@ Subagent (general-purpose):
Your scope is the findings list and the fix diff. Verdict every finding.
Inspect the fix diff for new problems the fix itself introduced. Do NOT
re-review code the fix did not touch: if you notice an issue entirely
review code the fix did not touch: if you notice an issue entirely
outside the fix diff, report it under Out-of-Scope Observations — it
does not block this task and does not extend the loop. A broad
whole-branch review happens after all tasks are complete.
@@ -93,14 +93,14 @@ Subagent (general-purpose):
**Placeholders:**
- `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection; scoped
re-reviews of small fix diffs take a cheap-to-mid tier
fix reviews of small fix diffs take a cheap-to-mid tier
- `[BRIEF_FILE]` — the task brief file (same file the implementer worked from)
- `[FINDINGS]` — the Critical/Important findings and spec gaps from the
previous review, copied verbatim, one per bullet
- `[REPORT_FILE]` — the implementer's report file (fix reports appended)
- `[FIX_BASE_SHA]` — the head the previous review saw
- `[HEAD_SHA]` — current commit
- `[DIFF_FILE]` — the path `scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
- `[DIFF_FILE]` — the path `scripts/review-package --role fix-review PLAN_FILE FIX_BASE HEAD` printed
**Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
**Fix reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
new breakage in the fix diff, out-of-scope observations, and a round verdict.
@@ -110,14 +110,21 @@ Subagent (general-purpose):
Fix them, re-run the tests that cover the amended code, and append a fix
report to your report file: what you changed, the covering tests you
ran, the command, and the output. Reviewers will not re-run tests for
you — your report is the test evidence. Then reply with the same short
status contract as your first report.
you — your report is the test evidence. If your fix report claims a
full-suite pass, that claim needs a fresh run after your last edit —
a suite run from before the findings arrived no longer counts. Then
reply with the same short status contract as your first report.
## Report Format
Write your full report to [REPORT_FILE]:
- What you implemented (or what you attempted, if blocked)
- What you tested and test results
- What you tested, and for every gate you claim — focused tests, full
suite, lint, build — the exact command and the tail of its fresh
output. Fresh means run after your final edit: if you edited anything
since your last full-suite run, that run is stale — rerun it or
report the suite as unverified. A gate claim without pasted fresh
output is itself a defect for the reviewer to flag.
- **TDD Evidence** (if TDD was required for this task):
- RED: command run, relevant failing output before implementation, and why the failure was expected
- GREEN: command run and relevant passing output after implementation
@@ -4,13 +4,31 @@
# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
# tasks intact.
#
# Usage: review-package PLAN_FILE BASE HEAD [OUTFILE]
# Usage: review-package [--role task-review|fix-review|final-review] PLAN_FILE BASE HEAD [OUTFILE]
# Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/review-<base7>..<head7>.diff
# (named per range, so a re-review after fixes gets a distinct fresh file).
# (named per range, so a fix review after fixes gets a distinct fresh file).
#
# The trailing dispatch hint rides this output because the controller reads it
# immediately before spawning the reviewer; skill text loaded at session start
# does not survive context compaction, but this line is reprinted every round.
set -euo pipefail
script_dir=$(cd "$(dirname "$0")" && pwd)
role=task-review
if [ "${1:-}" = "--role" ]; then
[ $# -ge 2 ] || { echo "usage: review-package [--role task-review|fix-review|final-review] PLAN_FILE BASE HEAD [OUTFILE]" >&2; exit 2; }
role=$2
shift 2
fi
case "$role" in
task-review|fix-review|final-review) hint_key=$role ;;
*) echo "bad --role: ${role} (task-review|fix-review|final-review)" >&2; exit 2 ;;
esac
if [ $# -lt 3 ] || [ $# -gt 4 ]; then
echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2
echo "usage: review-package [--role task-review|fix-review|final-review] PLAN_FILE BASE HEAD [OUTFILE]" >&2
exit 2
fi
@@ -25,7 +43,7 @@ git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&
if [ $# -eq 4 ]; then
out=$4
else
dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
dir=$("$script_dir/sdd-workspace" "$plan")
out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
fi
@@ -44,3 +62,20 @@ fi
commits=$(git rev-list --count "${base}..${head}")
echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"
# Platform dispatch hints ride this output because the controller reads it
# immediately before spawning; the lines themselves are owned by the platform
# reference layer (using-superpowers/references/*-dispatch.hints), not this
# script. Claude Code's dispatch templates carry model selection already, so
# the relay is suppressed there and on any harness without a hints file.
hints_file="$script_dir/../../using-superpowers/references/codex-dispatch.hints"
if [ -z "${CLAUDECODE:-}" ] && [ -f "$hints_file" ]; then
hint_line=$(grep "^${hint_key}:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
if [ -n "$hint_line" ]; then
echo "$hint_line"
footer_line=$(grep "^footer:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
if [ -n "$footer_line" ]; then
echo "$footer_line"
fi
fi
fi
@@ -18,10 +18,12 @@ plan=$1
n=$2
[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
script_dir=$(cd "$(dirname "$0")" && pwd)
if [ $# -eq 3 ]; then
out=$3
else
dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
dir=$("$script_dir/sdd-workspace" "$plan")
out="$dir/task-${n}-brief.md"
fi
@@ -39,3 +41,20 @@ if [ ! -s "$out" ]; then
fi
echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"
# Platform dispatch hints ride this output because the controller reads it
# immediately before spawning; the lines themselves are owned by the platform
# reference layer (using-superpowers/references/*-dispatch.hints), not this
# script. Claude Code's dispatch templates carry model selection already, so
# the relay is suppressed there and on any harness without a hints file.
hints_file="$script_dir/../../using-superpowers/references/codex-dispatch.hints"
if [ -z "${CLAUDECODE:-}" ] && [ -f "$hints_file" ]; then
hint_line=$(grep "^implementer:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
if [ -n "$hint_line" ]; then
echo "$hint_line"
footer_line=$(grep "^footer:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
if [ -n "$footer_line" ]; then
echo "$footer_line"
fi
fi
fi
+3 -12
View File
@@ -18,18 +18,9 @@ echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
echo "Test pattern: $TEST_PATTERN"
echo ""
# Get list of test files (find . emits ./-prefixed paths, so accept the
# pattern written with or without a leading ./)
TEST_PATTERN="${TEST_PATTERN#./}"
# find -path can't match '**/' against zero directory levels, so a pattern
# like src/**/*.test.ts would skip src/top.test.ts; also try the pattern
# with '**/' collapsed to cover files directly under the base directory.
TEST_FILES=$(find . \( -path "./$TEST_PATTERN" -o -path "./${TEST_PATTERN//\*\*\//}" \) | sort -u)
if [ -z "$TEST_FILES" ]; then
TOTAL=0
else
TOTAL=$(printf '%s\n' "$TEST_FILES" | wc -l | tr -d ' ')
fi
# Get list of test files
TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
echo "Found $TOTAL test files"
echo ""
@@ -4,7 +4,7 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file").
| Action skills request | Antigravity CLI equivalent |
|----------------------|----------------------|
| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName``self` for full-capability work, `research` for read-only |
| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName``self` for full-capability work, `research` for read-only (see [Subagent support](#subagent-support)) |
| Task tracking ("create a todo", "mark complete") | a **task artifact**`write_to_file` with `IsArtifact: true` and `ArtifactType: "task"` (see [Task tracking](#task-tracking)). **Not** `manage_task`, which manages background processes. |
## Task tracking
@@ -0,0 +1,15 @@
# Per-role dispatch lines for Codex spawn_agent, relayed by the
# subagent-driven-development task-brief and review-package scripts at the
# moment of dispatch (skill text loaded at session start does not survive
# context compaction; these lines reprint every round).
# Model names track Codex's spawn_agent allowlist (currently gpt-5.6-sol
# and gpt-5.6-terra) — update this file when the allowlist changes.
# Format: <role>: <line printed verbatim>
# The footer line prints after every role line: prevention alone does not
# cure drift — in instrumented runs, reprinted hints did not heal an
# already-broken dispatch pattern until the text named the drift directly.
footer: If any spawn this session omitted these params or used fork_turns "all", you have drifted — re-read references/codex-tools.md before dispatching again.
implementer: dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high
task-review: dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high
fix-review: dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=medium
final-review: dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high
@@ -9,6 +9,48 @@ multi_agent = true
This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. When using subagent-driven-development, close reviewer subagents when their review returns. Keep each implementer subagent open until its task's review passes — the fix loop resumes the implementer — then close it. If your harness cannot send another message to a spawned agent, dispatch each fix round as a fresh implementer carrying the brief, the report file, and the findings.
## SDD dispatch on Codex
Every SDD `spawn_agent` call sets `fork_turns: "none"` — the default
`"all"` forks your whole transcript into the child and refuses model
and effort overrides.
If your `spawn_agent` schema has `model` and `reasoning_effort`
parameters (Codex 0.145+), set both on every dispatch: task-brief and
review-package print a `dispatch:` hint line with the exact values —
copy it onto the call verbatim, every time, even late in a long
session. The hints print at those scripts' boundaries; every other
spawn — ad-hoc fan-outs included — follows the same table without a
printed reminder. Those hints are the Model Selection mapping on Codex:
reviewer tier never exceeds implementer tier, no fix round gets an
effort bump, and rounds 4-5's "more capable model" means a fresh
implementer at the same tier — needing more is a BLOCKED escalation
to your human partner. Inherited frontier-tier subagents are a
measured cause of runs spinning out for hours. (Values live in
`codex-dispatch.hints` beside this file; they track the spawn_agent
model allowlist.)
Without those parameters (Codex 0.144 and earlier), children inherit
your model and effort with no override — role files in
`~/.codex/agents/` do not attach to spawns either. Tell your human
partner before starting a plan of more than a few tasks, and offer a
lower-effort session instead.
## Compaction sheds these instructions
Context compaction replaces your transcript with a summary that keeps
your progress but not your working instructions — the first
post-compaction dispatch is where routing drift starts, and once one
bare spawn lands, the broken pattern becomes its own precedent. The
plugin ships a compaction re-injection hook (`hooks/hooks-codex.json`,
Codex 0.145+) that restores the bootstrap after every compaction; it
needs one-time trust approval, so if you never see a
`<CONTEXT_RESTORED>` block after a compaction, tell your human partner
the hook may be untrusted or unsupported on this version. Without it,
the printed `dispatch:` hints are your only re-grounding — treat every
one you see as authoritative, especially right after a summary appears
in your context.
## Environment Detection
Skills that create worktrees or finish branches should detect their
+64
View File
@@ -165,6 +165,70 @@ PLAN
echo " got: $rp_explicit"
fi
# --- platform dispatch hints ride the script output (suppressed on CC) ---
local brief_hint
brief_hint="$(cd "$repo" && env -u CLAUDECODE "$SDD_SCRIPTS/task-brief" plan-a.md 1)"
if [[ "$brief_hint" == *"dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high"* ]]; then
pass "task-brief relays the implementer dispatch hint off Claude Code"
else
fail "task-brief relays the implementer dispatch hint off Claude Code"
echo " got: $brief_hint"
fi
if [[ "$brief_hint" == *"you have drifted"* ]]; then
pass "task-brief prints the drift-cure footer after the hint"
else
fail "task-brief prints the drift-cure footer after the hint"
echo " got: $brief_hint"
fi
local rp_hint
rp_hint="$(cd "$repo" && env -u CLAUDECODE "$SDD_SCRIPTS/review-package" plan-a.md HEAD~1 HEAD)"
if [[ "$rp_hint" == *"dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high"* && "$rp_hint" == *"you have drifted"* ]]; then
pass "review-package relays the default-role hint off Claude Code"
else
fail "review-package relays the default-role hint off Claude Code"
echo " got: $rp_hint"
fi
local rp_fixreview
rp_fixreview="$(cd "$repo" && env -u CLAUDECODE "$SDD_SCRIPTS/review-package" --role fix-review plan-a.md HEAD~1 HEAD)"
if [[ "$rp_fixreview" == *"dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=medium"* ]]; then
pass "review-package --role fix-review relays the medium-effort hint"
else
fail "review-package --role fix-review relays the medium-effort hint"
echo " got: $rp_fixreview"
fi
local rp_final
rp_final="$(cd "$repo" && env -u CLAUDECODE "$SDD_SCRIPTS/review-package" --role final-review plan-a.md HEAD~1 HEAD)"
if [[ "$rp_final" == *"dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high"* ]]; then
pass "review-package --role final-review relays the high-effort hint"
else
fail "review-package --role final-review relays the high-effort hint"
echo " got: $rp_final"
fi
local brief_cc rp_cc
brief_cc="$(cd "$repo" && CLAUDECODE=1 "$SDD_SCRIPTS/task-brief" plan-a.md 1)"
rp_cc="$(cd "$repo" && CLAUDECODE=1 "$SDD_SCRIPTS/review-package" plan-a.md HEAD~1 HEAD)"
if [[ "$brief_cc" != *"dispatch (spawn_agent)"* && "$rp_cc" != *"dispatch (spawn_agent)"* ]]; then
pass "dispatch hints are suppressed under Claude Code (CLAUDECODE set)"
else
fail "dispatch hints are suppressed under Claude Code (CLAUDECODE set)"
echo " brief: $brief_cc"
echo " rp: $rp_cc"
fi
rc=0
(cd "$repo" && "$SDD_SCRIPTS/review-package" --role bogus plan-a.md HEAD~1 HEAD >/dev/null 2>&1) || rc=$?
if [[ "$rc" -eq 2 ]]; then
pass "review-package rejects an unknown --role with exit 2"
else
fail "review-package rejects an unknown --role with exit 2"
echo " exit: $rc"
fi
# --- Worktree isolation: a linked worktree resolves its own workspace ---
local wt="$TEST_ROOT/wt"
( cd "$repo" && git worktree add -q "$wt" -b wt-feature )
+24 -12
View File
@@ -52,25 +52,37 @@ if not plugin_manifest.exists():
manifest = json.loads(plugin_manifest.read_text(encoding="utf-8"))
assert_equal(manifest.get("name"), plugin.get("name"), "plugin manifest name")
# Codex auto-discovers a plugin's hooks/hooks.json whenever the Codex manifest
# has no `hooks` field: load_plugin_hooks falls back to a hardcoded
# DEFAULT_HOOKS_CONFIG_FILE = "hooks/hooks.json" and registers it. That file is
# the Claude Code SessionStart hook, it is tracked in this repo, and this
# marketplace installs the whole repo root (source url "./"), so on Codex the
# fallback re-registers the SessionStart hook and its install-time trust prompt.
# Declaring an empty inline hooks object ({}) parses as an empty inline hook set
# and suppresses the auto-discovery. An absent field, an empty array ([]), and
# an empty inline list all collapse back to the fallback, so the value must be
# exactly an empty object.
# The Codex manifest must declare its hooks explicitly. An absent field makes
# load_plugin_hooks fall back to a hardcoded DEFAULT_HOOKS_CONFIG_FILE =
# "hooks/hooks.json" — the Claude Code SessionStart hook, which injects the
# bootstrap at startup and must not run on Codex. The explicit pointer both
# registers the Codex compaction re-injection hook and overrides that fallback.
hooks_config = repo_root / "hooks" / "hooks.json"
if not hooks_config.exists():
raise AssertionError("hooks/hooks.json must exist (Claude Code SessionStart hook)")
assert_equal(
manifest.get("hooks"),
{},
"Codex manifest must declare empty hooks {} to suppress hooks/hooks.json auto-discovery",
"./hooks/hooks-codex.json",
"Codex manifest must point hooks at the Codex hook config (an absent field "
"falls back to auto-discovering the Claude Code hooks/hooks.json)",
)
codex_hooks_path = repo_root / "hooks" / "hooks-codex.json"
if not codex_hooks_path.exists():
raise AssertionError("hooks/hooks-codex.json must exist (Codex manifest points at it)")
codex_hooks = json.loads(codex_hooks_path.read_text(encoding="utf-8"))
session_start = codex_hooks["hooks"]["SessionStart"]
assert_equal(len(session_start), 1, "Codex SessionStart hook group count")
assert_equal(session_start[0].get("matcher"), "compact", "Codex hook matcher")
entry = session_start[0]["hooks"][0]
assert_equal(entry.get("type"), "command", "Codex hook type")
command = entry.get("command", "")
if "${PLUGIN_ROOT}" not in command or not command.endswith("session-start-codex"):
raise AssertionError(
f"Codex hook command must run session-start-codex via ${{PLUGIN_ROOT}}: {command!r}"
)
print("Codex marketplace manifest looks good")
PY
+5 -2
View File
@@ -141,7 +141,7 @@ tar_extracted="$TEST_ROOT/tar-extracted"
write_metadata_fixture "$metadata_source"
source_hooks="$(python3 -c 'import json; print(json.load(open("'"$REPO_ROOT"'/.codex-plugin/plugin.json")).get("hooks"))')"
assert_equals "$source_hooks" "{}" "source Codex manifest suppresses local hook auto-discovery"
assert_equals "$source_hooks" "./hooks/hooks-codex.json" "source Codex manifest declares the Codex hook config"
if output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_source" --output "$archive" 2>&1)"; then
pass "package script exits successfully"
@@ -163,10 +163,13 @@ assert_contains "$output" "SHA-256:" "reports archive checksum"
extract_archive "$archive" "$extracted"
archive_paths="$(list_archive "$archive" | normalize_archive_paths)"
unexpected_pattern='(^superpowers/|^\.agents/|^hooks/|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)'
unexpected_pattern='(^superpowers/|^\.agents/|^hooks/hooks\.json$|^hooks/hooks-cursor\.json$|^hooks/session-start$|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)'
assert_not_matches "$archive_paths" "$unexpected_pattern" "archive excludes source-only paths"
assert_contains "$archive_paths" ".codex-plugin/plugin.json" "archive includes Codex manifest"
assert_contains "$archive_paths" "skills/brainstorming/SKILL.md" "archive includes skills"
assert_contains "$archive_paths" "hooks/hooks-codex.json" "archive includes Codex hook config"
assert_contains "$archive_paths" "hooks/session-start-codex" "archive includes Codex hook script"
assert_contains "$archive_paths" "hooks/run-hook.cmd" "archive includes hook runner"
assert_contains "$archive_paths" "skills/brainstorming/agents/openai.yaml" "archive includes OpenAI skill metadata"
assert_contains "$archive_paths" "assets/app-icon.png" "archive includes app icon"
assert_contains "$archive_paths" "assets/superpowers-small.svg" "archive includes composer icon"
+115
View File
@@ -0,0 +1,115 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start-codex"
CONFIG_UNDER_TEST="$REPO_ROOT/hooks/hooks-codex.json"
FAILURES=0
pass() {
echo " [PASS] $1"
}
fail() {
echo " [FAIL] $1"
FAILURES=$((FAILURES + 1))
}
# run_hook <stdin-payload> — echoes hook stdout; fails the calling test on
# non-zero exit. env -i mirrors the codex hook executor's clean environment.
run_hook() {
printf '%s' "$1" | env -i PATH="${PATH:-}" bash "$HOOK_UNDER_TEST"
}
echo "Codex SessionStart hook tests"
startup_payload='{"session_id":"s","hook_event_name":"SessionStart","model":"gpt-5.6-terra","source":"startup"}'
if output="$(run_hook "$startup_payload")" && [ -z "$output" ]; then
pass "source=startup emits nothing and exits 0"
else
fail "source=startup emits nothing and exits 0"
printf '%s\n' "$output" | head -3 | sed 's/^/ /'
fi
compact_payload='{"session_id":"s","hook_event_name":"SessionStart","model":"gpt-5.6-terra","source":"compact"}'
if output="$(run_hook "$compact_payload")"; then
ok=1
for needle in \
"<EXTREMELY_IMPORTANT>" \
"You have superpowers." \
"name: using-superpowers" \
"<CONTEXT_RESTORED>" \
"subagent-driven-development/SKILL.md" \
"references/codex-tools.md"; do
if [[ "$output" != *"$needle"* ]]; then
ok=0
echo " missing: $needle"
fi
done
if [ "$ok" -eq 1 ]; then
pass "source=compact emits bootstrap plus re-read addendum"
else
fail "source=compact emits bootstrap plus re-read addendum"
fi
else
fail "source=compact emits bootstrap plus re-read addendum (hook exited non-zero)"
fi
# Whitespace-tolerant source matching (serializers vary).
spaced_payload='{"hook_event_name":"SessionStart", "source" : "compact"}'
if output="$(run_hook "$spaced_payload")" && [[ "$output" == *"<CONTEXT_RESTORED>"* ]]; then
pass "whitespace around the source key still triggers injection"
else
fail "whitespace around the source key still triggers injection"
fi
if output="$(printf '' | env -i PATH="${PATH:-}" bash "$HOOK_UNDER_TEST")" && [ -z "$output" ]; then
pass "empty stdin fails open to no output, exit 0"
else
fail "empty stdin fails open to no output, exit 0"
fi
if output="$(run_hook 'not json at all {{{')" && [ -z "$output" ]; then
pass "garbage stdin fails open to no output, exit 0"
else
fail "garbage stdin fails open to no output, exit 0"
fi
# A compact mention inside some other field must not trigger injection.
decoy_payload='{"hook_event_name":"SessionStart","source":"startup","cwd":"/tmp/compact"}'
if output="$(run_hook "$decoy_payload")" && [ -z "$output" ]; then
pass "compact appearing outside the source field does not trigger"
else
fail "compact appearing outside the source field does not trigger"
fi
if node -e '
const config = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
const group = config.hooks.SessionStart[0];
if (group.matcher !== "compact") {
console.error(`hook matcher is ${JSON.stringify(group.matcher)}, expected "compact"`);
process.exit(1);
}
const entry = group.hooks[0];
if (entry.type !== "command") {
console.error(`hook type is ${JSON.stringify(entry.type)}, expected "command"`);
process.exit(1);
}
if (!entry.command.includes("${PLUGIN_ROOT}") || !/run-hook\.cmd" session-start-codex$/.test(entry.command)) {
console.error(`unexpected command shape: ${entry.command}`);
process.exit(1);
}
' "$CONFIG_UNDER_TEST"; then
pass "hooks-codex.json runs session-start-codex via \${PLUGIN_ROOT} on compact"
else
fail "hooks-codex.json runs session-start-codex via \${PLUGIN_ROOT} on compact"
fi
if [[ "$FAILURES" -gt 0 ]]; then
echo "STATUS: FAILED ($FAILURES failure(s))"
exit 1
fi
echo "STATUS: PASSED"
@@ -1,90 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
SCRIPT_UNDER_TEST="$REPO_ROOT/skills/systematic-debugging/find-polluter.sh"
FAILURES=0
TEST_ROOT="$(mktemp -d)"
cleanup() {
rm -rf "$TEST_ROOT"
}
trap cleanup EXIT
pass() {
echo " [PASS] $1"
}
fail() {
echo " [FAIL] $1"
FAILURES=$((FAILURES + 1))
}
assert_contains() {
local haystack="$1"
local needle="$2"
local description="$3"
if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
pass "$description"
else
fail "$description (expected output to contain: $needle)"
fi
}
# Toy project: one top-level test, one nested test. A stubbed `npm` on PATH
# creates the pollution marker whenever any test runs, so the first test file
# executed is always identified as the polluter.
setup_project() {
PROJECT="$TEST_ROOT/project"
rm -rf "$PROJECT"
mkdir -p "$PROJECT/src/feature" "$PROJECT/bin"
echo "test('top')" > "$PROJECT/src/top.test.ts"
echo "test('nested')" > "$PROJECT/src/feature/nested.test.ts"
cat > "$PROJECT/bin/npm" <<'EOF'
#!/usr/bin/env bash
touch pollution.marker
EOF
chmod +x "$PROJECT/bin/npm"
}
# run_polluter <pattern> — runs the script in the toy project with the stub
# npm first on PATH; captures combined output, never aborts on exit code.
run_polluter() {
local pattern="$1"
rm -f "$PROJECT/pollution.marker"
(
cd "$PROJECT"
PATH="$PROJECT/bin:$PATH" "$SCRIPT_UNDER_TEST" 'pollution.marker' "$pattern" 2>&1
) || true
}
echo "Test: documented pattern finds nested test files (issue #2008)"
setup_project
OUTPUT="$(run_polluter 'src/**/*.test.ts')"
assert_contains "$OUTPUT" "FOUND POLLUTER" "documented pattern runs tests and detects pollution"
echo "Test: documented pattern also finds top-level test files"
setup_project
OUTPUT="$(run_polluter 'src/**/*.test.ts')"
assert_contains "$OUTPUT" "Found 2 test files" "src/**/*.test.ts matches src/top.test.ts and src/feature/nested.test.ts"
echo "Test: ./-prefixed pattern matches the same files"
setup_project
OUTPUT="$(run_polluter './src/**/*.test.ts')"
assert_contains "$OUTPUT" "Found 2 test files" "leading ./ on the pattern is accepted"
echo "Test: non-matching pattern reports an honest zero"
setup_project
OUTPUT="$(run_polluter 'nomatch/**/*.test.ts')"
assert_contains "$OUTPUT" "Found 0 test files" "empty result counts as 0, not 1"
assert_contains "$OUTPUT" "No polluter found" "empty result exits via the clean path"
echo ""
if [ "$FAILURES" -gt 0 ]; then
echo "$FAILURES test(s) failed"
exit 1
fi
echo "All tests passed"