mirror of
https://github.com/obra/superpowers.git
synced 2026-07-23 10:44:01 +08:00
c686bb947ab1469bd396e0b691f28f96a3c4ee0c
20 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
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 | ||
|
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. |