From 4c3e7e5e8a5324786fa56827406489a900699aed Mon Sep 17 00:00:00 2001 From: Drew Ritter Date: Thu, 23 Jul 2026 12:23:17 -0700 Subject: [PATCH] docs(codex): wire the compaction hook into README and codex-tools, add drift-cure footer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 35 +++++++++++++++++++ .../scripts/review-package | 4 +++ .../scripts/task-brief | 4 +++ .../references/codex-dispatch.hints | 4 +++ .../references/codex-tools.md | 17 ++++++++- tests/claude-code/test-sdd-workspace.sh | 9 ++++- 6 files changed, 71 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bb398c6b..bd97c2c5 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,41 @@ Superpowers is available via the [official Codex plugin marketplace](https://git - Select `Install Plugin`. +#### Codex: compaction re-injection hook (recommended) + +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; this hook +restores the same behavior on Codex (0.145+). + +Merge `hooks/hooks-codex.json.example` from your Superpowers install into +`~/.codex/hooks.json`, replacing the placeholder with the absolute path to +your install: + +```json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "bash \"/path/to/superpowers/hooks/session-start-codex\"", + "timeout": 30 + } + ] + } + ] + } +} +``` + +Codex asks you to trust the hook once, the first time it runs in the app. +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: diff --git a/skills/subagent-driven-development/scripts/review-package b/skills/subagent-driven-development/scripts/review-package index b45dc255..d2798d7d 100755 --- a/skills/subagent-driven-development/scripts/review-package +++ b/skills/subagent-driven-development/scripts/review-package @@ -73,5 +73,9 @@ 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 diff --git a/skills/subagent-driven-development/scripts/task-brief b/skills/subagent-driven-development/scripts/task-brief index 269939c6..eb061f62 100755 --- a/skills/subagent-driven-development/scripts/task-brief +++ b/skills/subagent-driven-development/scripts/task-brief @@ -52,5 +52,9 @@ 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 diff --git a/skills/using-superpowers/references/codex-dispatch.hints b/skills/using-superpowers/references/codex-dispatch.hints index e2a6008b..14e25d3f 100644 --- a/skills/using-superpowers/references/codex-dispatch.hints +++ b/skills/using-superpowers/references/codex-dispatch.hints @@ -5,6 +5,10 @@ # 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: : +# 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 diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index 1b4d907e..7b4e0a25 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/skills/using-superpowers/references/codex-tools.md @@ -19,7 +19,9 @@ 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. Those hints are the Model Selection mapping on Codex: +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 @@ -34,6 +36,19 @@ your model and effort with no override — role files in 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 +compaction re-injection hook (README, "Codex: compaction re-injection +hook") restores the bootstrap after every compaction; recommend it to +your human partner if it is not installed. 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 diff --git a/tests/claude-code/test-sdd-workspace.sh b/tests/claude-code/test-sdd-workspace.sh index 406638ab..34ca9f27 100755 --- a/tests/claude-code/test-sdd-workspace.sh +++ b/tests/claude-code/test-sdd-workspace.sh @@ -175,9 +175,16 @@ PLAN 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"* ]]; then + 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"