mirror of
https://github.com/obra/superpowers.git
synced 2026-07-25 11:44:01 +08:00
34d4f64f91cc6d3200bbbc86a0f0d34daf26ad13
13 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" ( |
||
|
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> |
||
|
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> |
||
|
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> |
||
|
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> |
||
|
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>
|
||
|
Jesse Vincent
|
7ce7620d44 | feat(sdd): align templates and codex reference with resume-based fix rounds | ||
|
Jesse Vincent
|
e7ddc25e51 |
Prune per-harness tool-mapping boilerplate
The verbose action-to-tool tables and skill-loading explainers in the per-harness reference files restated guidance modern agents already follow. Trim each file to the harness-specific notes that still carry weight (subagent dispatch, task tracking, instructions-file paths), and delete claude-code-tools.md and copilot-tools.md, which had nothing left that wasn't generic. |
||
|
Jesse Vincent
|
6b9f1b214a |
Phase B: config-file refs + per-platform tool refs + spec
Two structural changes:
1. Generalize CLAUDE.md-specific guidance:
- "Project-specific conventions (put in CLAUDE.md)" → "(put in
your instructions file)" in writing-skills/SKILL.md
- "(explicit CLAUDE.md violation)" → "(explicit instruction-file
violation)" in receiving-code-review/SKILL.md
- The instruction-priority list in using-superpowers/SKILL.md
stays inclusive (CLAUDE.md, GEMINI.md, AGENTS.md) — that's
load-bearing, not a substitution opportunity.
2. Per-platform tool reference files at skills/using-superpowers/
references/{claude-code,codex,copilot,gemini}-tools.md. Each ref
documents:
- The runtime's preferred instructions file (CLAUDE.md, AGENTS.md,
GEMINI.md, etc.) and how it loads
- The runtime's personal-skills directory + cross-runtime
~/.agents/skills/ path where applicable
- Action-language → tool-name mapping table
Tool names and table content reflect the source-verified state from
direct inspection of openai/codex, google-gemini/gemini-cli,
sst/opencode, and the installed @github/copilot package. Filenames
and behaviors are sourced from each runtime's official docs.
Files in this commit also pick up later-phase changes that
accumulated on the same files (using-superpowers/SKILL.md "How to
Access Skills" overhaul, action-language flowchart, refs' final
table content). The bundled spec records original scope.
|
||
|
Jesse Vincent
|
f2cbfbefeb |
Release v5.1.0 (#1468)
* docs: add Codex App compatibility design spec (PRI-823) Design for making using-git-worktrees, finishing-a-development-branch, and subagent-driven-development skills work in the Codex App's sandboxed worktree environment. Read-only environment detection via git-dir vs git-common-dir comparison, ~48 lines across 4 files, zero breaking changes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: address spec review feedback for PRI-823 Fix three Important issues from spec review: - Clarify Step 1.5 placement relative to existing Steps 2/3 - Re-derive environment state at cleanup time instead of relying on earlier skill output - Acknowledge pre-existing Step 5 cleanup inconsistency Also: precise step references, exact codex-tools.md content, clearer Integration section update instructions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: address team review feedback for PRI-823 spec - Add commit SHA + data loss warning to handoff payload (HIGH) - Add explicit commit step before handoff (HIGH) - Remove misleading "mark as externally managed" from Path B - Add executing-plans 1-line edit (was missing) - Add branch name derivation rules - Add conditional UI language for non-App environments - Add sandbox fallback for permission errors - Add STOP directive after Step 0 reporting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: clarify executing-plans in What Does NOT Change section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add cleanup guard test (#5) and sandbox fallback test (#10) to spec Both tests address real risk scenarios: - #5: cleanup guard bug would delete Codex App's own worktree (data loss) - #10: Local thread sandbox fallback needs manual Codex App validation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add implementation plan for Codex App compatibility (PRI-823) 8 tasks covering: environment detection in using-git-worktrees, Step 1.5 + cleanup guard in finishing-a-development-branch, Integration line updates, codex-tools.md docs, automated tests, and final verification. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(codex-tools): add named agent dispatch mapping for Codex (#647) * fix(writing-skills): correct false 'only two fields' frontmatter claim (#882) * Replace subagent review loops with lightweight inline self-review The subagent review loop (dispatching a fresh agent to review plans/specs) doubled execution time (~25 min overhead) without measurably improving plan quality. Regression testing across 5 versions (v3.6.0 through v5.0.4) with 5 trials each showed identical plan sizes, task counts, and quality scores regardless of whether the review loop ran. Changes: - writing-plans: Replace subagent Plan Review Loop with inline Self-Review checklist (spec coverage, placeholder scan, type consistency) - writing-plans: Add explicit "No Placeholders" section listing plan failures (TBD, vague descriptions, undefined references, "similar to Task N") - brainstorming: Replace subagent Spec Review Loop with inline Spec Self-Review (placeholder scan, internal consistency, scope check, ambiguity check) - Both skills now use "look at it with fresh eyes" framing Testing: 5 trials with the new skill show self-review catches 3-5 real bugs per run (spawn positions, API mismatches, seed bugs, grid indexing) in ~30s instead of ~25 min. Remaining defects are comparable to the subagent approach. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Revert "Replace subagent review loops with lightweight inline self-review" This reverts commit |
||
|
Drew Ritter
|
2b1bfe5db6 | docs(codex-tools): add named agent dispatch mapping for Codex (#647) | ||
|
ynyyn
|
687a66183d | Fix deprecated collab flag in Codex docs | ||
|
Drew Ritter
|
a26cbaab2e |
Move Codex tool mapping to progressive disclosure reference file
Move inline routing table from using-superpowers to references/codex-tools.md, leveraging native progressive disclosure for companion files. Add Platform Adaptation pointer so non-CC platforms can find tool equivalents. |