The plugin had a single named agent (`agents/code-reviewer.md`) used by
two skills, while every other reviewer/implementer subagent in the repo
is dispatched as `general-purpose` with the prompt template living
alongside its skill. That asymmetry had no upside and several costs:
- Two sources of truth for the code review checklist (the agent file
and `requesting-code-review/code-reviewer.md`), both drifting
independently.
- `Codex` users could not use the named agent directly; the codex-tools
reference doc had a workaround section explaining how to flatten the
named agent into a `worker` dispatch.
- No third-party reliance on `superpowers:code-reviewer` inside this
repo.
Changes:
- Merge `agents/code-reviewer.md` (persona + checklist) and
`skills/requesting-code-review/code-reviewer.md` (placeholder
template) into a single self-contained Task-dispatch template,
matching the shape of `implementer-prompt.md`,
`spec-reviewer-prompt.md`, etc.
- Update `skills/requesting-code-review/SKILL.md` and
`skills/subagent-driven-development/code-quality-reviewer-prompt.md`
to dispatch `Task (general-purpose)` instead of the named agent.
- Drop the now-obsolete "Named agent dispatch" workaround sections from
`codex-tools.md` and `copilot-tools.md` — superpowers no longer ships
any named agents, so those instructions documented nothing.
- Delete `agents/code-reviewer.md` and the empty `agents/` directory.
Tier 3 coverage for the change: a new behavioral test
`tests/claude-code/test-requesting-code-review.sh` plants real bugs
(SQL injection, plaintext password handling, credential logging) into
a tiny project, runs the actual `requesting-code-review` skill against
the working tree, and asserts the dispatched reviewer flags every
planted issue at Critical/Important severity and refuses to approve
the diff.
Verified end-to-end on this branch:
- The new test passes (5/5 assertions; reviewer caught all planted
bugs and several others).
- The existing SDD integration test still passes (7/7 subagents
dispatched, all as `general-purpose`; spec compliance still
rejects extra features; produced code is correct).
- Session JSONLs confirm zero remaining `superpowers:code-reviewer`
dispatches anywhere in the SDD pipeline.
Update the Codex tool mapping so Claude Code 'Task returns result' maps to the current Codex spawned-agent result tool, wait_agent. Also clarify that older Codex builds exposed spawned-agent waiting as wait, while current bare wait is the code-mode exec/wait surface for yielded exec cells.
Verified with Drill:
- codex-tool-mapping-comprehension fails against dev with task_returns_result=wait
- codex-tool-mapping-comprehension passes against this PR with task_returns_result=wait_agent and exec/wait scoped correctly
- codex-subagent-wait-mapping passes against this PR with spawn_agent -> wait_agent -> close_agent and PR963_OK returned
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.
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.
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
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.
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.
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
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)
- 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
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
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.
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.
- 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)
