mirror of
https://github.com/obra/superpowers.git
synced 2026-07-23 18:54:07 +08:00
c97988d8d1aff45ea9bf4bd2294a22086e414d5e
19 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
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 | ||
|
Ada Sen
|
096e15aa73 |
Revert "Remove Gemini CLI support"
This reverts commit
|
||
|
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
|
711d895ce7 |
Remove Gemini CLI support
Google EOLed the Gemini CLI on 2026-06-18; the extension can no longer be installed or updated. Remove Gemini from the install docs, the subagent-capable platform lists, and the eval-harness description, and delete its tool-mapping reference. |
||
|
Jesse Vincent
|
e08ad0660a |
Merge per-task reviews into one task reviewer (iteration 2)
Iteration-1 profiling: implementers and per-dispatch overhead dominate (429 of 686 subagent turns; controller coordination is half the dollars and scales with dispatch count), reviewers are individually lean, and the controller pasted the diff in only 2 of 22 review dispatches when the guidance was phrased as optional. Changes: spec-reviewer-prompt.md + code-quality-reviewer-prompt.md replaced by task-reviewer-prompt.md (one reviewer, one reading of a pasted diff, two verdicts: spec compliance ✅/❌/⚠️ and task quality); one fix dispatch can address both kinds of findings; controller now runs git diff itself and pastes it (imperative, not optional); implementers run focused tests while iterating and the full suite once before committing; flowchart, example, Red Flags, tool tables updated. The broad final whole-branch review is unchanged. |
||
|
Jesse Vincent
|
36ce0a21e4 |
feat: add Antigravity CLI (agy) support
Antigravity (Google's `agy` CLI) installs the existing Superpowers plugin
directly:
agy plugin install https://github.com/obra/superpowers
agy imports the bundled skills and runs the plugin's SessionStart hook, so
using-superpowers bootstraps from the first message — verified on agy 1.0.3:
a fresh session given "Let's make a react todo list" auto-triggers the
brainstorming skill instead of writing code. agy discovers skills natively
and, having no Skill tool, loads them by reading SKILL.md with view_file.
No scaffold, installer, or generated context file is needed. This adds only:
- README.md: an Antigravity install section + Quickstart link
- skills/using-superpowers/SKILL.md: reference to the agy tool mapping
- skills/using-superpowers/references/antigravity-tools.md: action->tool
mapping for agy (view_file, write_to_file, invoke_subagent, manage_task,
and skill loading via view_file on SKILL.md)
- tests/antigravity/: structural test for the tool mapping, mirroring
tests/pi/
|
||
|
Drew Ritter
|
295219a6fa | Align Pi mapping with action vocabulary | ||
|
Jesse Vincent
|
71ac601627 | feat: add pi superpowers package extension | ||
|
Drew Ritter
|
f030d6ef88 | Tighten cross-platform tool references | ||
|
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 |
||
|
Jesse Vincent
|
8b1669269c |
feat: add Copilot CLI tool mapping, docs, and install instructions
- Add references/copilot-tools.md with full tool equivalence table - Add Copilot CLI to using-superpowers skill platform instructions - Add marketplace install instructions to README - Add changelog entry crediting @culinablaz for the hook fix |
||
|
Drew Ritter
|
2b1bfe5db6 | docs(codex-tools): add named agent dispatch mapping for Codex (#647) | ||
|
ynyyn
|
687a66183d | Fix deprecated collab flag in Codex docs | ||
|
Jesse Vincent
|
21a774e95c |
Add Gemini CLI tool mapping and update using-superpowers references
Maps all Claude Code tool names to Gemini CLI equivalents (read_file, write_file, replace, run_shell_command, grep_search, glob, write_todos, activate_skill, etc.). Notes that Gemini CLI has no subagent support. Updates using-superpowers to reference GEMINI.md in instruction priority and link to the new gemini-tools.md reference alongside codex-tools.md. |
||
|
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. |