mirror of
https://github.com/obra/superpowers
synced 2026-07-10 20:54:29 +00:00
d4d99117f2fa3c59052563efe9248a597a5f78f1
23 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Drew Ritter
|
d4d99117f2 | Tighten cross-platform tool references | ||
|
Jesse Vincent
|
5c0402736e |
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
|
715e18e448 |
Load Gemini tool mapping via GEMINI.md @import instead of skill reference
The tool mapping table is now @referenced directly in GEMINI.md so Gemini CLI always has it in context when processing skills, rather than requiring Gemini to find and read a reference file from within the skill. |
||
|
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. |
||
|
Jesse Vincent
|
245d50ec37 | Add v5.0.0 release notes and include AGENTS.md in instruction priority | ||
|
Drew Ritter
|
1c53f5deb6 |
Add SUBAGENT-STOP gate to prevent subagent skill leakage
Codex subagents inherit filesystem access and can discover superpowers skills via native discovery. Without guidance, they activate the 1% rule and invoke full skill workflows instead of executing their assigned task. - Add SUBAGENT-STOP block to using-superpowers that tells subagents to skip the skill and execute their dispatch prompt instead - Document collab feature requirement for Codex subagent skills |
||
|
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. |
||
|
Jesse Vincent
|
b23c084070 |
Add instruction priority hierarchy to using-superpowers skill
Clarifies that user instructions (CLAUDE.md, direct requests) always take precedence over Superpowers skills, which in turn override default system prompt behavior. Ensures users remain in control. Also updates RELEASE-NOTES.md with unreleased changes including the visual companion feature. |
||
|
Jesse Vincent
|
7f2ee614b6 |
Enforce brainstorming workflow with hard gates and process flow
The brainstorming skill described a process but didn't enforce it. Models would skip the design phase and jump straight to implementation skills like frontend-design, or collapse the entire brainstorming process into a single text block. Changes to brainstorming skill: - Add HARD-GATE: no implementation until design is approved - Add explicit checklist that maps to task items - Add graphviz process flow with writing-plans as terminal state - Add anti-pattern callout for "too simple to need a design" - Scale design sections by section complexity, not project complexity - Make writing-plans the only valid next skill after brainstorming Changes to using-superpowers skill: - Add EnterPlanMode intercept to workflow graph - Route plan mode attempts through brainstorming skill instead Tested with claude -p --plugin-dir across three variants (no skill, original skill, updated skill) to verify behavioral compliance. |
||
|
Jesse Vincent
|
3dac35e0b3 |
Strengthen using-superpowers for explicit skill requests
Addresses failure mode where Claude skips skill invocation even when user explicitly requests it by name (e.g., "subagent-driven-development, please"). Skill changes: - "Check for skills" → "Invoke relevant or requested skills" - "BEFORE ANY RESPONSE" → "BEFORE any response or action" - Added reassurance that wrong skill invocations are okay - New red flag: "I know what that means" Tests: - New test suite for explicit skill requests - Single-turn and multi-turn scenarios with --continue - Tests with haiku model and user CLAUDE.md |
||
|
Jesse Vincent
|
a7a8c08c02 |
Clarify that Skill tool loads skill content directly
Fixes pattern where Claude would invoke a skill then try to Read the file separately. The Skill tool already provides the content. - Add "How to Access Skills" section to using-superpowers - Change "read the skill" → "invoke the skill" - Commands now use fully qualified names (superpowers:brainstorming etc) |
||
|
Jesse Vincent
|
3f725ff0d4 |
Strengthen brainstorming skill trigger and add skill priority guidance
- Update brainstorming description to use imperative "You MUST use this" - Clarify trigger: "before any creative work - creating features, building components, adding functionality, or modifying behavior" - Add Skill Priority section to using-superpowers to ensure process skills (brainstorming, debugging) are invoked before implementation skills |
||
|
Jesse Vincent
|
2d7408d0c6 |
Improve using-superpowers skill to prevent rationalization failures
Tested against claude -p with multiple scenarios. Key fixes: - Clarify skill check comes BEFORE ANY response including clarifications - Add rationalizations: "I need more context first", "Let me explore first", "This feels productive" - Flowchart entry point now "User message received" → clearer blocking gate - Shorter, more scannable format (flowchart + table) Verified: "Fix login bug" now triggers systematic-debugging first |
||
|
Jesse Vincent
|
c88b0d674f |
Update using-superpowers skill to use Skill tool instead of Read tool
The Skill tool is the proper mechanism for invoking skills, not the Read tool. Updated the bootstrap instructions and anti-rationalization guidance to reflect this. |
||
|
Jesse Vincent
|
f6ee98a41a |
Strengthen using-superpowers skill against agent rationalization
Add three layers of enforcement to prevent agents from skipping skill usage: 1. EXTREMELY-IMPORTANT block with absolute language - "If even 1% chance a skill applies, you MUST read it" - "You do not have a choice. You cannot rationalize your way out." 2. MANDATORY FIRST RESPONSE PROTOCOL checklist - 5-step process agents must complete before any response - Explicit "responding without this = failure" consequence 3. Common Rationalizations section with 8 specific patterns - "This is just a simple question" → WRONG - "I can check files quickly" → WRONG - "Let me gather information first" → WRONG - Plus 5 more common evasion patterns These changes address observed agent behavior where they rationalize around skill usage despite clear instructions. The forceful language and pre-emptive counter-arguments aim to make rationalization harder. |
||
|
Jesse Vincent
|
48410c7f19 |
Standardize skill frontmatter names to lowercase and kebab-case
- Update all 20 skill frontmatter names to match their directory names in lowercase - Fix defense-in-depth name (was Defense-in-Depth-Validation) - Fix receiving-code-review name (was Code-Review-Reception) - Update all skill announcements and cross-references to use lowercase names - Update commands redirects to reference lowercase skill names Ensures consistent naming: skill directory names, frontmatter names, and documentation references all use lowercase kebab-case format (e.g., brainstorming, test-driven-development) |
||
|
Jesse Vincent
|
10afd4eacc | Now that the "Skill" tool is public, use that | ||
|
Jesse Vincent
|
451db491b8 | Update our bootstrap for first-party claude skills | ||
|
Jesse Vincent
|
deb45f5cad | Adding back our old getting-started skill since the claude code bootstrap does not seem to trigger our skills quite as effectively yet |