Conversation
…s 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>
… docs hooks/session-start-codex has had no caller since "Remove Codex hooks" (obra#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 obra#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>
…x portal packaging
This reverts commit 711d895.
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.
… 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.
…pment-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.
…lopment-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.
…onalization 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.
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.
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.
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.
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.
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.
…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.
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.
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.
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 obra#1932 owns that).
…ompletion 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.
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 obra#1932 owns it).
…pment 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 obra#1932 owns it).
…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.
…nalization 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.
fix(writing-skills): make render-graphs ESM-compatible and shell-free
`git status --porcelain` collapses a wholly-untracked directory to a single `?? docs/` line. In the shape of the incident this step exists for (obra#2016 — an uncommitted plan document under an untracked `docs/` tree), the file list we show the human partner therefore names no file at all: $ git -C "$WORKTREE_PATH" status --porcelain ?? docs/ $ git -C "$WORKTREE_PATH" status --porcelain -uall ?? docs/superpowers/plans/2026-08-04-csv-export-rollout.md Both forms produce identical (empty) output on a clean worktree, so this adds no over-trigger surface. Found while running this PR's behavioral micro-tests. Every treatment agent dug past `?? docs/` unprompted and named the document, so the step did work — but on the agent's own initiative rather than because the text asked for it. That initiative is not reliable one tier down: Claude Haiku 4.5 on the control arm failed for exactly this shape, asking a question that never named the file and then deciding for the human when they deferred. Nothing in the prior wording stopped a treatment agent from relaying `?? docs/` verbatim and satisfying the letter of the instruction. Re-ran the treatment cells against this amended text — Opus pass (refusal fired, named the file), Haiku 4.5 pass (named the file) — no regression. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…-checkin fix(finishing): check in with human partner when worktree removal hits untracked files
fix(planning): the spec travels with the plan
fix(sdd): reviewers re-read illegible evidence instead of re-running to regenerate it
Document the agreed follow-up to PR obra#2025 on a branch based on its merged dev commit. The design registers the Hermes YAML manifest, keeps jq for existing JSON files, and uses Mike Farah yq v4 for a narrow top-level YAML field rather than adding a Bash parser.\n\nDefine focused failure behavior and behavioral tests while explicitly excluding nested YAML, Hermes runtime changes, and unrelated release-script refactors. This captures Drew's request to keep the implementation small and avoid process or abstraction overhead.
Incorporate the adversarial design review without turning the Hermes wiring follow-up into a general release-script refactor. Keep the existing jq path, add Mike Farah yq v4 only for .yaml, and retain one read-only preflight to prevent deterministic partial bumps.\n\nReduce the test contract to three behavioral cases and explicitly defer .yml support, nested YAML, rollback machinery, audit/status redesign, exhaustive failure matrices, and the separately discovered JSON-expression issue. This follows Drew's direction to avoid ceremony and overengineering.
Record Drew's approved reduced design after the second staff review. Limit preflight to the mutating bump path, cover audit's independent read path, and require byte-for-byte proof that deterministic YAML failures cannot partially update earlier JSON manifests. Provide one TDD implementation task for the Hermes registry entry, jq/yq dispatch, focused preflight, and three behavioral checks. Explicitly defer rollback, audit-status changes, nested YAML, runtime changes, and broader release-tool refactoring.
Register the Hermes YAML manifest alongside the existing JSON manifests. Route manifest reads and writes by extension through jq or Mike Farah yq v4, with field names and values passed as data. Preflight every present manifest before the mutating bump loop so a deterministic YAML read failure cannot leave earlier JSON manifests partially updated. Cover check, audit, bump, registry wiring, and byte-for-byte no-partial-write behavior with one focused fixture test.
feat(brainstorming): three-path router — ceremony scales, approval never does
…o-readme Docs/add grok build cli to readme
…ndows docs(brainstorming): correct Copilot CLI backgrounding guidance for Windows
Devin CLI's `devin plugins install obra/superpowers` fails today because the
repo has no `.devin-plugin/plugin.json` manifest. Add the manifest (skills are
auto-discovered from the co-located skills/ directory), a Devin tool mapping
linked from using-superpowers' Platform Adaptation section, a README install
section, version tracking in .version-bump.json, a Codex-sync exclude for the
new dotdir, and a CI-safe test mirroring the kimi/antigravity test style.
Bootstrap rides Devin's native skill surfacing: every installed skill's
name + description is injected into the system prompt at session start with a
standing instruction to invoke matching skills via the native skill tool.
Acceptance test ("Let's make a react todo list") passes in a clean session:
using-superpowers and brainstorming auto-trigger before any code is written.
Re-ran the clean-session acceptance test with the mapping file and the SKILL.md Platform Adaptation pointer removed: using-superpowers and brainstorming still auto-trigger first, and the full workflow chain (writing-plans, executing-plans, TDD, verification) resolves every action to Devin's native tools. Devin CLI's own system prompt already documents its tools (skill invocation, subagent profiles, todo tracking, question prompts), so the mapping was redundant. Test now validates the manifest only.
feat: add Devin CLI support
Remove the redundant Quickstart entry and section now that the README has a table of contents. Rename the Installation label in the table of contents to Getting Started while retaining the existing installation anchor and section heading.
Add Hermes Agent to the installation entries in the table of contents. The removed Quickstart section was the README's only direct link to that existing installation section, so preserving the link avoids a navigation regression.
…v's README rework # Conflicts: # README.md
Remove non-Claude-Code harness support: Antigravity, Codex, Cursor, Devin, Gemini, Hermes, Kimi, OpenCode, Pi plugin manifests and their test suites. - delete .agents, .codex-plugin, .cursor-plugin, .devin-plugin, .hermes-plugin, .kimi-plugin, .opencode, .pi, gemini-extension.json, GEMINI.md, hooks/hooks-cursor.json - delete skills/using-superpowers/references/ and the Platform Adaptation section that pointed at it - rewrite the dangling per-harness notes in executing-plans and writing-skills for Claude Code - trim README install sections and ToC to Claude Code - drop the .opencode/.pi entrypoints from package.json
- AGENTS.md symlink (Claude Code reads CLAUDE.md) - .github/ issue and PR templates, FUNDING (upstream's) - assets/ (only referenced by the Codex packaging scripts) - docs/ including docs/superpowers/, which collides with the path brainstorming and writing-plans write specs and plans to - scripts/package-codex-plugin.sh, scripts/sync-to-codex-plugin.sh Fix the references these left dangling in CLAUDE.md and using-superpowers/SKILL.md.
scripts/bump-version.sh existed to sync one version string across nine plugin manifests; this fork ships one. Drops its config (.version-bump.json, which still listed the deleted manifests) and its test suite. scripts/lint-shell.sh stays.
tests/claude-code and tests/explicit-skill-requests drive `claude -p` and assert on upstream's exact skill prose — they burn tokens and fail as soon as a skill is customized. tests/brainstorm-server needs npm, tests/writing-skills needs graphviz. Keeps tests/hooks (verifies the SessionStart hook emits valid JSON) and tests/shell-lint.
* Add /superpowers-setup to redirect spec and plan locations Adds a deterministic config resolver plus a slash command that asks for an absolute path and stores it, and teaches the SessionStart hook to inject the configured locations as an explicit instruction. Skills are not rewritten: brainstorming and writing-plans already defer to a stated user preference over their default path, so the injected directive is enough. The three lines that restated a path with no override clause are adjusted to point at the declared location instead. Only specs and plans are affected. The SDD scratch workspace (.superpowers/sdd/), worktree locations, and brainstorm visual sessions are deliberately left alone. * Replace hardcoded plan paths in examples with placeholders The worked-example transcripts in subagent-driven-development and requesting-code-review echoed a literal docs/superpowers/plans path. Nothing resolves those lines, but few-shot examples steer behaviour harder than prose rules, so a model could copy the old path and ignore the configured location. Both now use the <plan file path> placeholder that brainstorming already uses. Adds 'superpowers-config check', which fails when a skill names a default spec/plan path with no adjacent clause saying a configured location wins. /superpowers-setup runs it as a final step and reports rather than edits, so the same regression cannot land unnoticed again. * Fix config lookup failing when a key is absent read_key filtered blank lines with 'grep -v', which exits 1 when it matches nothing. Under pipefail that failed the whole lookup, so 'get' printed nothing and exited 1 whenever a config file existed without the requested key - the normal state after configuring only one of the two paths. 'show' and the SessionStart hook both masked it (printf swallowed the status, the hook has '|| echo ""'), so it degraded silently to the default rather than erroring. awk 'NF' filters blanks and exits 0 when there is no match. * Drop the SessionStart hook; apply paths via the optional command Reverts hooks/session-start to its original content. The hook ran on every session to inject configured paths; it earned that cost only for per-project paths or surviving a plugin reinstall, and neither is wanted here. /superpowers-setup is now fully optional and does the work once: 'set' records the choice, 'apply' rewrites the skill files, 'check' verifies, 'revert' restores the shipped defaults. Tracking the applied value in the config makes apply idempotent and re-targetable, and lets a post-update re-apply run without asking for the path again. Also reverts the two override clauses added to brainstorming; they existed only to be consumed by the injected directive and reference nothing now. The example-transcript placeholders stay - those guard against a model copying a literal path out of a worked example, which is independent of the mechanism.
The skill told the agent how to post replies to inline review comments on GitHub. Responding to review comments is the human partner's job; the agent addresses feedback in the code and reports back in session. Removing the section takes the instruction out of the skill.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Who is submitting this PR? (required)
What problem are you trying to solve?
What does this PR change?
Is this change appropriate for the core library?
What alternatives did you consider?
Does this PR contain multiple unrelated changes?
Existing PRs
Environment tested
New harness support (required if this PR adds a new harness)
Clean-session transcript for "Let's make a react todo list"
Evaluation
the session that led to this change?
Rigor
superpowers:writing-skillsandcompleted adversarial pressure testing (paste results below)
rationalizations, "human partner" language) without extensive evals
showing the change is an improvement
Human review