Superpowers Release Notes

v5.0.2 (2026-03-11)

Zero-Dependency Brainstorm Server

Removed all vendored node_modules — server.js is now fully self-contained

Replaced Express/Chokidar/WebSocket dependencies with zero-dependency Node.js server using built-in http, fs, and crypto modules
Removed ~1,200 lines of vendored node_modules/, package.json, and package-lock.json
Custom WebSocket protocol implementation (RFC 6455 framing, ping/pong, proper close handshake)
Native fs.watch() file watching replaces Chokidar
Full test suite: HTTP serving, WebSocket protocol, file watching, and integration tests

Brainstorm Server Reliability

Auto-exit after 30 minutes idle — server shuts down when no clients are connected, preventing orphaned processes
Owner process tracking — server monitors the parent harness PID and exits when the owning session dies
Liveness check — skill verifies server is responsive before reusing an existing instance
Encoding fix — proper <meta charset="utf-8"> on served HTML pages

Subagent Context Isolation

All delegation skills (brainstorming, dispatching-parallel-agents, requesting-code-review, subagent-driven-development, writing-plans) now include context isolation principle
Subagents receive only the context they need, preventing context window pollution

v5.0.1 (2026-03-10)

Agentskills Compliance

Brainstorm-server moved into skill directory

Moved lib/brainstorm-server/ → skills/brainstorming/scripts/ per the agentskills.io specification
All ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/ references replaced with relative scripts/ paths
Skills are now fully portable across platforms — no platform-specific env vars needed to locate scripts
lib/ directory removed (was the last remaining content)

New Features

Gemini CLI extension

Native Gemini CLI extension support via gemini-extension.json and GEMINI.md at repo root
GEMINI.md @imports using-superpowers skill and tool mapping table at session start
Gemini CLI tool mapping reference (skills/using-superpowers/references/gemini-tools.md) — translates Claude Code tool names (Read, Write, Edit, Bash, etc.) to Gemini CLI equivalents (read_file, write_file, replace, etc.)
Documents Gemini CLI limitations: no subagent support, skills fall back to executing-plans
Extension root at repo root for cross-platform compatibility (avoids Windows symlink issues)
Install instructions added to README

Improvements

Multi-platform brainstorm server launch

Per-platform launch instructions in visual-companion.md: Claude Code (default mode), Codex (auto-foreground via CODEX_CI), Gemini CLI (--foreground with is_background), and fallback for other environments
Server now writes startup JSON to $SCREEN_DIR/.server-info so agents can find the URL and port even when stdout is hidden by background execution

Brainstorm server dependencies bundled

node_modules vendored into the repo so the brainstorm server works immediately on fresh plugin installs without requiring npm at runtime
Removed fsevents from bundled deps (macOS-only native binary; chokidar falls back gracefully without it)
Fallback auto-install via npm install if node_modules is missing

OpenCode tool mapping fix

TodoWrite → todowrite (was incorrectly mapped to update_plan); verified against OpenCode source

Bug Fixes

Windows/Linux: single quotes break SessionStart hook (#577, #529, #644, PR #585)

Single quotes around ${CLAUDE_PLUGIN_ROOT} in hooks.json fail on Windows (cmd.exe doesn't recognize single quotes as path delimiters) and on Linux (single quotes prevent variable expansion)
Fix: replaced single quotes with escaped double quotes — works across macOS bash, Windows cmd.exe, Windows Git Bash, and Linux, with and without spaces in paths
Verified on Windows 11 (NT 10.0.26200.0) with Claude Code 2.1.72 and Git for Windows

Brainstorming spec review loop skipped (#677)

The spec review loop (dispatch spec-document-reviewer subagent, iterate until approved) existed in the prose "After the Design" section but was missing from the checklist and process flow diagram
Since agents follow the diagram and checklist more reliably than prose, the spec review step was being skipped entirely
Added step 7 (spec review loop) to the checklist and corresponding nodes to the dot graph
Tested with claude --plugin-dir and claude-session-driver: worker now correctly dispatches the reviewer

Cursor install command (PR #676)

Fixed Cursor install command in README: /plugin-add → /add-plugin (confirmed via Cursor 2.5 release announcement)

User review gate in brainstorming (#565)

Added explicit user review step between spec completion and writing-plans handoff
User must approve the spec before implementation planning begins
Checklist, process flow, and prose updated with the new gate

Session-start hook emits context only once per platform

Hook now detects whether it's running in Claude Code or another platform
Emits hookSpecificOutput for Claude Code, additional_context for others — prevents double context injection

Linting fix in token analysis script

except: → except Exception: in tests/claude-code/analyze-token-usage.py

Maintenance

Removed dead code

Deleted lib/skills-core.js and its test (tests/opencode/test-skills-core.js) — unused since February 2026
Removed skills-core existence check from tests/opencode/test-plugin-loading.sh

Community

@karuturi — Claude Code official marketplace install instructions (PR #610)
@mvanhorn — session-start hook dual-emit fix, OpenCode tool mapping fix
@daniel-graham — linting fix for bare except
PR #585 author — Windows/Linux hooks quoting fix

v5.0.0 (2026-03-09)

Breaking Changes

Specs and plans directory restructured

Specs (brainstorming output) now save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
Plans (writing-plans output) now save to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
User preferences for spec/plan locations override these defaults
All internal skill references, test files, and example paths updated to match
Migration: move existing files from docs/plans/ to new locations if desired

Subagent-driven development mandatory on capable harnesses

Writing-plans no longer offers a choice between subagent-driven and executing-plans. On harnesses with subagent support (Claude Code, Codex), subagent-driven-development is required. Executing-plans is reserved for harnesses without subagent capability, and now tells the user that Superpowers works better on a subagent-capable platform.

Executing-plans no longer batches

Removed the "execute 3 tasks then stop for review" pattern. Plans now execute continuously, stopping only for blockers.

Slash commands deprecated

/brainstorm, /write-plan, and /execute-plan now show deprecation notices pointing users to the corresponding skills. Commands will be removed in the next major release.

New Features

Visual brainstorming companion

Optional browser-based companion for brainstorming sessions. When a topic would benefit from visuals, the brainstorming skill offers to show mockups, diagrams, comparisons, and other content in a browser window alongside terminal conversation.

lib/brainstorm-server/ — WebSocket server with browser helper library, session management scripts, and dark/light themed frame template ("Superpowers Brainstorming" with GitHub link)
skills/brainstorming/visual-companion.md — Progressive disclosure guide for server workflow, screen authoring, and feedback collection
Brainstorming skill adds a visual companion decision point to its process flow: after exploring project context, the skill evaluates whether upcoming questions involve visual content and offers the companion in its own message
Per-question decision: even after accepting, each question is evaluated for whether browser or terminal is more appropriate
Integration tests in tests/brainstorm-server/

Document review system

Automated review loops for spec and plan documents using subagent dispatch:

skills/brainstorming/spec-document-reviewer-prompt.md — Reviewer checks completeness, consistency, architecture, and YAGNI
skills/writing-plans/plan-document-reviewer-prompt.md — Reviewer checks spec alignment, task decomposition, file structure, and file size
Brainstorming dispatches spec reviewer after writing the design doc
Writing-plans includes chunk-based plan review loop after each section
Review loops repeat until approved or escalate after 5 iterations
End-to-end tests in tests/claude-code/test-document-review-system.sh
Design spec and implementation plan in docs/superpowers/

Architecture guidance across the skill pipeline

Design-for-isolation and file-size-awareness guidance added to brainstorming, writing-plans, and subagent-driven-development:

Brainstorming — New sections: "Design for isolation and clarity" (clear boundaries, well-defined interfaces, independently testable units) and "Working in existing codebases" (follow existing patterns, targeted improvements only)
Writing-plans — New "File Structure" section: map out files and responsibilities before defining tasks. New "Scope Check" backstop: catch multi-subsystem specs that should have been decomposed during brainstorming
SDD implementer — New "Code Organization" section (follow plan's file structure, report concerns about growing files) and "When You're in Over Your Head" escalation guidance
SDD code quality reviewer — Now checks architecture, unit decomposition, plan conformance, and file growth
Spec/plan reviewers — Architecture and file size added to review criteria
Scope assessment — Brainstorming now assesses whether a project is too large for a single spec. Multi-subsystem requests are flagged early and decomposed into sub-projects, each with its own spec → plan → implementation cycle

Subagent-driven development improvements

Model selection — Guidance for choosing model capability by task type: cheap models for mechanical implementation, standard for integration, capable for architecture and review
Implementer status protocol — Subagents now report DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT. Controller handles each status appropriately: re-dispatching with more context, upgrading model capability, breaking tasks apart, or escalating to human

Improvements

Instruction priority hierarchy

Added explicit priority ordering to using-superpowers:

User's explicit instructions (CLAUDE.md, AGENTS.md, direct requests) — highest priority
Superpowers skills — override default system behavior
Default system prompt — lowest priority

If CLAUDE.md or AGENTS.md says "don't use TDD" and a skill says "always use TDD," the user's instructions win.

SUBAGENT-STOP gate

Added <SUBAGENT-STOP> block to using-superpowers. Subagents dispatched for specific tasks now skip the skill instead of activating the 1% rule and invoking full skill workflows.

Multi-platform improvements

Codex tool mapping moved to progressive disclosure reference file (references/codex-tools.md)
Platform Adaptation pointer added so non-Claude-Code platforms can find tool equivalents
Plan headers now address "agentic workers" instead of "Claude" specifically
Collab feature requirement documented in docs/README.codex.md

Writing-plans template updates

Plan steps now use checkbox syntax (- [ ] **Step N:**) for progress tracking
Plan header references both subagent-driven-development and executing-plans with platform-aware routing

v4.3.1 (2026-02-21)

Added

Cursor support

Superpowers now works with Cursor's plugin system. Includes a .cursor-plugin/plugin.json manifest and Cursor-specific installation instructions in the README. The SessionStart hook output now includes an additional_context field alongside the existing hookSpecificOutput.additionalContext for Cursor hook compatibility.

Fixed

Windows: Restored polyglot wrapper for reliable hook execution (#518, #504, #491, #487, #466, #440)

Claude Code's .sh auto-detection on Windows was prepending bash to the hook command, breaking execution. The fix:

Renamed session-start.sh to session-start (extensionless) so auto-detection doesn't interfere
Restored run-hook.cmd polyglot wrapper with multi-location bash discovery (standard Git for Windows paths, then PATH fallback)
Exits silently if no bash is found rather than erroring
On Unix, the wrapper runs the script directly via exec bash
Uses POSIX-safe dirname "$0" path resolution (works on dash/sh, not just bash)

This fixes SessionStart failures on Windows with spaces in paths, missing WSL, set -euo pipefail fragility on MSYS, and backslash mangling.

v4.3.0 (2026-02-12)

This fix should dramatically improve superpowers skills compliance and should reduce the chances of Claude entering its native plan mode unintentionally.

Changed

Brainstorming skill now enforces its workflow instead of describing it

Models were skipping the design phase and jumping straight to implementation skills like frontend-design, or collapsing the entire brainstorming process into a single text block. The skill now uses hard gates, a mandatory checklist, and a graphviz process flow to enforce compliance:

<HARD-GATE>: no implementation skills, code, or scaffolding until design is presented and user approves
Explicit checklist (6 items) that must be created as tasks and completed in order
Graphviz process flow with writing-plans as the only valid terminal state
Anti-pattern callout for "this is too simple to need a design" — the exact rationalization models use to skip the process
Design section sizing based on section complexity, not project complexity

Using-superpowers workflow graph intercepts EnterPlanMode

Added an EnterPlanMode intercept to the skill flow graph. When the model is about to enter Claude's native plan mode, it checks whether brainstorming has happened and routes through the brainstorming skill instead. Plan mode is never entered.

Fixed

SessionStart hook now runs synchronously

Changed async: true to async: false in hooks.json. When async, the hook could fail to complete before the model's first turn, meaning using-superpowers instructions weren't in context for the first message.

v4.2.0 (2026-02-05)

Breaking Changes

Codex: Replaced bootstrap CLI with native skill discovery

The superpowers-codex bootstrap CLI, Windows .cmd wrapper, and related bootstrap content file have been removed. Codex now uses native skill discovery via ~/.agents/skills/superpowers/ symlink, so the old use_skill/find_skills CLI tools are no longer needed.

Installation is now just clone + symlink (documented in INSTALL.md). No Node.js dependency required. The old ~/.codex/skills/ path is deprecated.

Fixes

Windows: Fixed Claude Code 2.1.x hook execution (#331)

Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects .sh files in commands and prepends bash. This broke the polyglot wrapper pattern because bash "run-hook.cmd" session-start.sh tries to execute the .cmd file as a bash script.

Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).

Windows: SessionStart hook runs async to prevent terminal freeze (#404, #413, #414, #419)

The synchronous SessionStart hook blocked the TUI from entering raw mode on Windows, freezing all keyboard input. Running the hook async prevents the freeze while still injecting superpowers context.

Windows: Fixed O(n^2) escape_for_json performance

The character-by-character loop using ${input:$i:1} was O(n^2) in bash due to substring copy overhead. On Windows Git Bash this took 60+ seconds. Replaced with bash parameter substitution (${s//old/new}) which runs each pattern as a single C-level pass — 7x faster on macOS, dramatically faster on Windows.

Codex: Fixed Windows/PowerShell invocation (#285, #243)

Windows doesn't respect shebangs, so directly invoking the extensionless superpowers-codex script triggered an "Open with" dialog. All invocations now prefixed with node.
Fixed ~/ path expansion on Windows — PowerShell doesn't expand ~ when passed as an argument to node. Changed to $HOME which expands correctly in both bash and PowerShell.

Codex: Fixed path resolution in installer

Used fileURLToPath() instead of manual URL pathname parsing to correctly handle paths with spaces and special characters on all platforms.

Codex: Fixed stale skills path in writing-skills

Updated ~/.codex/skills/ reference (deprecated) to ~/.agents/skills/ for native discovery.

Improvements

Worktree isolation now required before implementation

Added using-git-worktrees as a required skill for both subagent-driven-development and executing-plans. Implementation workflows now explicitly require setting up an isolated worktree before starting work, preventing accidental work directly on main.

Main branch protection softened to require explicit consent

Instead of prohibiting main branch work entirely, the skills now allow it with explicit user consent. More flexible while still ensuring users are aware of the implications.

Simplified installation verification

Removed /help command check and specific slash command list from verification steps. Skills are primarily invoked by describing what you want to do, not by running specific commands.

Codex: Clarified subagent tool mapping in bootstrap

Improved documentation of how Codex tools map to Claude Code equivalents for subagent workflows.

Tests

Added worktree requirement test for subagent-driven-development
Added main branch red flag warning test
Fixed case sensitivity in skill recognition test assertions

v4.1.1 (2026-01-23)

Fixes

OpenCode: Standardized on plugins/ directory per official docs (#343)

OpenCode's official documentation uses ~/.config/opencode/plugins/ (plural). Our docs previously used plugin/ (singular). While OpenCode accepts both forms, we've standardized on the official convention to avoid confusion.

Changes:

Renamed .opencode/plugin/ to .opencode/plugins/ in repo structure
Updated all installation docs (INSTALL.md, README.opencode.md) across all platforms
Updated test scripts to match

OpenCode: Fixed symlink instructions (#339, #342)

Added explicit rm before ln -s (fixes "file already exists" errors on reinstall)
Added missing skills symlink step that was absent from INSTALL.md
Updated from deprecated use_skill/find_skills to native skill tool references

v4.1.0 (2026-01-23)

Breaking Changes

OpenCode: Switched to native skills system

Superpowers for OpenCode now uses OpenCode's native skill tool instead of custom use_skill/find_skills tools. This is a cleaner integration that works with OpenCode's built-in skill discovery.

Migration required: Skills must be symlinked to ~/.config/opencode/skills/superpowers/ (see updated installation docs).

Fixes

OpenCode: Fixed agent reset on session start (#226)

The previous bootstrap injection method using session.prompt({ noReply: true }) caused OpenCode to reset the selected agent to "build" on first message. Now uses experimental.chat.system.transform hook which modifies the system prompt directly without side effects.

OpenCode: Fixed Windows installation (#232)

Removed dependency on skills-core.js (eliminates broken relative imports when file is copied instead of symlinked)
Added comprehensive Windows installation docs for cmd.exe, PowerShell, and Git Bash
Documented proper symlink vs junction usage for each platform

Claude Code: Fixed Windows hook execution for Claude Code 2.1.x

Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects .sh files in commands and prepends bash . This broke the polyglot wrapper pattern because bash "run-hook.cmd" session-start.sh tries to execute the .cmd file as a bash script.

v4.0.3 (2025-12-26)

Improvements

Strengthened using-superpowers skill for explicit skill requests

Addressed a failure mode where Claude would skip invoking a skill even when the user explicitly requested it by name (e.g., "subagent-driven-development, please"). Claude would think "I know what that means" and start working directly instead of loading the skill.

Changes:

Updated "The Rule" to say "Invoke relevant or requested skills" instead of "Check for skills" - emphasizing active invocation over passive checking
Added "BEFORE any response or action" - the original wording only mentioned "response" but Claude would sometimes take action without responding first
Added reassurance that invoking a wrong skill is okay - reduces hesitation
Added new red flag: "I know what that means" → Knowing the concept ≠ using the skill

Added explicit skill request tests

New test suite in tests/explicit-skill-requests/ that verifies Claude correctly invokes skills when users request them by name. Includes single-turn and multi-turn test scenarios.

v4.0.2 (2025-12-23)

Fixes

Slash commands now user-only

Added disable-model-invocation: true to all three slash commands (/brainstorm, /execute-plan, /write-plan). Claude can no longer invoke these commands via the Skill tool—they're restricted to manual user invocation only.

The underlying skills (superpowers:brainstorming, superpowers:executing-plans, superpowers:writing-plans) remain available for Claude to invoke autonomously. This change prevents confusion when Claude would invoke a command that just redirects to a skill anyway.

v4.0.1 (2025-12-23)

Fixes

Clarified how to access skills in Claude Code

Fixed a confusing pattern where Claude would invoke a skill via the Skill tool, then try to Read the skill file separately. The using-superpowers skill now explicitly states that the Skill tool loads skill content directly—no need to read files.

Added "How to Access Skills" section to using-superpowers
Changed "read the skill" → "invoke the skill" in instructions
Updated slash commands to use fully qualified skill names (e.g., superpowers:brainstorming)

Added GitHub thread reply guidance to receiving-code-review (h/t @ralphbean)

Added a note about replying to inline review comments in the original thread rather than as top-level PR comments.

Added automation-over-documentation guidance to writing-skills (h/t @EthanJStark)

Added guidance that mechanical constraints should be automated, not documented—save skills for judgment calls.

v4.0.0 (2025-12-17)

New Features

Two-stage code review in subagent-driven-development

Subagent workflows now use two separate review stages after each task:

Spec compliance review - Skeptical reviewer verifies implementation matches spec exactly. Catches missing requirements AND over-building. Won't trust implementer's report—reads actual code.
Code quality review - Only runs after spec compliance passes. Reviews for clean code, test coverage, maintainability.

This catches the common failure mode where code is well-written but doesn't match what was requested. Reviews are loops, not one-shot: if reviewer finds issues, implementer fixes them, then reviewer checks again.

Other subagent workflow improvements:

Controller provides full task text to workers (not file references)
Workers can ask clarifying questions before AND during work
Self-review checklist before reporting completion
Plan read once at start, extracted to TodoWrite

New prompt templates in skills/subagent-driven-development/:

implementer-prompt.md - Includes self-review checklist, encourages questions
spec-reviewer-prompt.md - Skeptical verification against requirements
code-quality-reviewer-prompt.md - Standard code review

Debugging techniques consolidated with tools

systematic-debugging now bundles supporting techniques and tools:

root-cause-tracing.md - Trace bugs backward through call stack
defense-in-depth.md - Add validation at multiple layers
condition-based-waiting.md - Replace arbitrary timeouts with condition polling
find-polluter.sh - Bisection script to find which test creates pollution
condition-based-waiting-example.ts - Complete implementation from real debugging session

Testing anti-patterns reference

test-driven-development now includes testing-anti-patterns.md covering:

Testing mock behavior instead of real behavior
Adding test-only methods to production classes
Mocking without understanding dependencies
Incomplete mocks that hide structural assumptions

Skill test infrastructure

Three new test frameworks for validating skill behavior:

tests/skill-triggering/ - Validates skills trigger from naive prompts without explicit naming. Tests 6 skills to ensure descriptions alone are sufficient.

tests/claude-code/ - Integration tests using claude -p for headless testing. Verifies skill usage via session transcript (JSONL) analysis. Includes analyze-token-usage.py for cost tracking.

tests/subagent-driven-dev/ - End-to-end workflow validation with two complete test projects:

go-fractals/ - CLI tool with Sierpinski/Mandelbrot (10 tasks)
svelte-todo/ - CRUD app with localStorage and Playwright (12 tasks)

Major Changes

DOT flowcharts as executable specifications

Rewrote key skills using DOT/GraphViz flowcharts as the authoritative process definition. Prose becomes supporting content.

The Description Trap (documented in writing-skills): Discovered that skill descriptions override flowchart content when descriptions contain workflow summaries. Claude follows the short description instead of reading the detailed flowchart. Fix: descriptions must be trigger-only ("Use when X") with no process details.

Skill priority in using-superpowers

When multiple skills apply, process skills (brainstorming, debugging) now explicitly come before implementation skills. "Build X" triggers brainstorming first, then domain skills.

brainstorming trigger strengthened

Description changed to imperative: "You MUST use this before any creative work—creating features, building components, adding functionality, or modifying behavior."

Breaking Changes

Skill consolidation - Six standalone skills merged:

root-cause-tracing, defense-in-depth, condition-based-waiting → bundled in systematic-debugging/
testing-skills-with-subagents → bundled in writing-skills/
testing-anti-patterns → bundled in test-driven-development/
sharing-skills removed (obsolete)

Other Improvements

render-graphs.js - Tool to extract DOT diagrams from skills and render to SVG
Rationalizations table in using-superpowers - Scannable format including new entries: "I need more context first", "Let me explore first", "This feels productive"
docs/testing.md - Guide to testing skills with Claude Code integration tests

v3.6.2 (2025-12-03)

Fixed

Linux Compatibility: Fixed polyglot hook wrapper (run-hook.cmd) to use POSIX-compliant syntax
- Replaced bash-specific ${BASH_SOURCE[0]:-$0} with standard $0 on line 16
- Resolves "Bad substitution" error on Ubuntu/Debian systems where /bin/sh is dash
- Fixes #141

v3.5.1 (2025-11-24)

Changed

OpenCode Bootstrap Refactor: Switched from chat.message hook to session.created event for bootstrap injection
- Bootstrap now injects at session creation via session.prompt() with noReply: true
- Explicitly tells the model that using-superpowers is already loaded to prevent redundant skill loading
- Consolidated bootstrap content generation into shared getBootstrapContent() helper
- Cleaner single-implementation approach (removed fallback pattern)

v3.5.0 (2025-11-23)

Added

OpenCode Support: Native JavaScript plugin for OpenCode.ai
- Custom tools: use_skill and find_skills
- Message insertion pattern for skill persistence across context compaction
- Automatic context injection via chat.message hook
- Auto re-injection on session.compacted events
- Three-tier skill priority: project > personal > superpowers
- Project-local skills support (.opencode/skills/)
- Shared core module (lib/skills-core.js) for code reuse with Codex
- Automated test suite with proper isolation (tests/opencode/)
- Platform-specific documentation (docs/README.opencode.md, docs/README.codex.md)

Changed

Refactored Codex Implementation: Now uses shared lib/skills-core.js ES module
- Eliminates code duplication between Codex and OpenCode
- Single source of truth for skill discovery and parsing
- Codex successfully loads ES modules via Node.js interop
Improved Documentation: Rewrote README to explain problem/solution clearly
- Removed duplicate sections and conflicting information
- Added complete workflow description (brainstorm → plan → execute → finish)
- Simplified platform installation instructions
- Emphasized skill-checking protocol over automatic activation claims

v3.4.1 (2025-10-31)

Improvements

Optimized superpowers bootstrap to eliminate redundant skill execution. The using-superpowers skill content is now provided directly in session context, with clear guidance to use the Skill tool only for other skills. This reduces overhead and prevents the confusing loop where agents would execute using-superpowers manually despite already having the content from session start.

v3.4.0 (2025-10-30)

Improvements

Simplified brainstorming skill to return to original conversational vision. Removed heavyweight 6-phase process with formal checklists in favor of natural dialogue: ask questions one at a time, then present design in 200-300 word sections with validation. Keeps documentation and implementation handoff features.

v3.3.1 (2025-10-28)

Improvements

Updated brainstorming skill to require autonomous recon before questioning, encourage recommendation-driven decisions, and prevent agents from delegating prioritization back to humans.
Applied writing clarity improvements to brainstorming skill following Strunk's "Elements of Style" principles (omitted needless words, converted negative to positive form, improved parallel construction).

Bug Fixes

Clarified writing-skills guidance so it points to the correct agent-specific personal skill directories (~/.claude/skills for Claude Code, ~/.codex/skills for Codex).

v3.3.0 (2025-10-28)

New Features

Experimental Codex Support

Added unified superpowers-codex script with bootstrap/use-skill/find-skills commands
Cross-platform Node.js implementation (works on Windows, macOS, Linux)
Namespaced skills: superpowers:skill-name for superpowers skills, skill-name for personal
Personal skills override superpowers skills when names match
Clean skill display: shows name/description without raw frontmatter
Helpful context: shows supporting files directory for each skill
Tool mapping for Codex: TodoWrite→update_plan, subagents→manual fallback, etc.
Bootstrap integration with minimal AGENTS.md for automatic startup
Complete installation guide and bootstrap instructions specific to Codex

Key differences from Claude Code integration:

Single unified script instead of separate tools
Tool substitution system for Codex-specific equivalents
Simplified subagent handling (manual work instead of delegation)
Updated terminology: "Superpowers skills" instead of "Core skills"

Files Added

.codex/INSTALL.md - Installation guide for Codex users
.codex/superpowers-bootstrap.md - Bootstrap instructions with Codex adaptations
.codex/superpowers-codex - Unified Node.js executable with all functionality

Note: Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback.

v3.2.3 (2025-10-23)

Improvements

Updated using-superpowers skill to use Skill tool instead of Read tool

Changed skill invocation instructions from Read tool to Skill tool
Updated description: "using Read tool" → "using Skill tool"
Updated step 3: "Use the Read tool" → "Use the Skill tool to read and run"
Updated rationalization list: "Read the current version" → "Run the current version"

The Skill tool is the proper mechanism for invoking skills in Claude Code. This update corrects the bootstrap instructions to guide agents toward the correct tool.

Files Changed

Updated: skills/using-superpowers/SKILL.md - Changed tool references from Read to Skill

v3.2.2 (2025-10-21)

Improvements

Strengthened using-superpowers skill against agent rationalization

Added EXTREMELY-IMPORTANT block with absolute language about mandatory skill checking
- "If even 1% chance a skill applies, you MUST read it"
- "You do not have a choice. You cannot rationalize your way out."
Added MANDATORY FIRST RESPONSE PROTOCOL checklist
- 5-step process agents must complete before any response
- Explicit "responding without this = failure" consequence
Added Common Rationalizations section with 8 specific evasion patterns
- "This is just a simple question" → WRONG
- "I can check files quickly" → WRONG
- "Let me gather information first" → WRONG
- Plus 5 more common patterns observed in agent behavior

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 non-compliance harder.

Files Changed

Updated: skills/using-superpowers/SKILL.md - Added three layers of enforcement to prevent skill-skipping rationalization

v3.2.1 (2025-10-20)

New Features

Code reviewer agent now included in plugin

Added superpowers:code-reviewer agent to plugin's agents/ directory
Agent provides systematic code review against plans and coding standards
Previously required users to have personal agent configuration
All skill references updated to use namespaced superpowers:code-reviewer
Fixes #55

Files Changed

New: agents/code-reviewer.md - Agent definition with review checklist and output format
Updated: skills/requesting-code-review/SKILL.md - References to superpowers:code-reviewer
Updated: skills/subagent-driven-development/SKILL.md - References to superpowers:code-reviewer

v3.2.0 (2025-10-18)

New Features

Design documentation in brainstorming workflow

Added Phase 4: Design Documentation to brainstorming skill
Design documents now written to docs/plans/YYYY-MM-DD-<topic>-design.md before implementation
Restores functionality from original brainstorming command that was lost during skill conversion
Documents written before worktree setup and implementation planning
Tested with subagent to verify compliance under time pressure

Breaking Changes

Skill reference namespace standardization

All internal skill references now use superpowers: namespace prefix
Updated format: superpowers:test-driven-development (previously just test-driven-development)
Affects all REQUIRED SUB-SKILL, RECOMMENDED SUB-SKILL, and REQUIRED BACKGROUND references
Aligns with how skills are invoked using the Skill tool
Files updated: brainstorming, executing-plans, subagent-driven-development, systematic-debugging, testing-skills-with-subagents, writing-plans, writing-skills

Improvements

Design vs implementation plan naming

Design documents use -design.md suffix to prevent filename collisions
Implementation plans continue using existing YYYY-MM-DD-<feature-name>.md format
Both stored in docs/plans/ directory with clear naming distinction

v3.1.1 (2025-10-17)

Bug Fixes

Fixed command syntax in README (#44) - Updated all command references to use correct namespaced syntax (/superpowers:brainstorm instead of /brainstorm). Plugin-provided commands are automatically namespaced by Claude Code to avoid conflicts between plugins.

v3.1.0 (2025-10-17)

Breaking Changes

Skill names standardized to lowercase

All skill frontmatter name: fields now use lowercase kebab-case matching directory names
Examples: brainstorming, test-driven-development, using-git-worktrees
All skill announcements and cross-references updated to lowercase format
This ensures consistent naming across directory names, frontmatter, and documentation

New Features

Enhanced brainstorming skill

Added Quick Reference table showing phases, activities, and tool usage
Added copyable workflow checklist for tracking progress
Added decision flowchart for when to revisit earlier phases
Added comprehensive AskUserQuestion tool guidance with concrete examples
Added "Question Patterns" section explaining when to use structured vs open-ended questions
Restructured Key Principles as scannable table

Anthropic best practices integration

Added skills/writing-skills/anthropic-best-practices.md - Official Anthropic skill authoring guide
Referenced in writing-skills SKILL.md for comprehensive guidance
Provides patterns for progressive disclosure, workflows, and evaluation

Improvements

Skill cross-reference clarity

All skill references now use explicit requirement markers:
- **REQUIRED BACKGROUND:** - Prerequisites you must understand
- **REQUIRED SUB-SKILL:** - Skills that must be used in workflow
- **Complementary skills:** - Optional but helpful related skills
Removed old path format (skills/collaboration/X → just X)
Updated Integration sections with categorized relationships (Required vs Complementary)
Updated cross-reference documentation with best practices

Alignment with Anthropic best practices

Fixed description grammar and voice (fully third-person)
Added Quick Reference tables for scanning
Added workflow checklists Claude can copy and track
Appropriate use of flowcharts for non-obvious decision points
Improved scannable table formats
All skills well under 500-line recommendation

Bug Fixes

Re-added missing command redirects - Restored commands/brainstorm.md and commands/write-plan.md that were accidentally removed in v3.0 migration
Fixed defense-in-depth name mismatch (was Defense-in-Depth-Validation)
Fixed receiving-code-review name mismatch (was Code-Review-Reception)
Fixed commands/brainstorm.md reference to correct skill name
Removed references to non-existent related skills

Documentation

writing-skills improvements

Updated cross-referencing guidance with explicit requirement markers
Added reference to Anthropic's official best practices
Improved examples showing proper skill reference format

v3.0.1 (2025-10-16)

Changes

We now use Anthropic's first-party skills system!

v2.0.2 (2025-10-12)

Bug Fixes

Fixed false warning when local skills repo is ahead of upstream - The initialization script was incorrectly warning "New skills available from upstream" when the local repository had commits ahead of upstream. The logic now correctly distinguishes between three git states: local behind (should update), local ahead (no warning), and diverged (should warn).

v2.0.1 (2025-10-12)

Bug Fixes

Fixed session-start hook execution in plugin context (#8, PR #9) - The hook was failing silently with "Plugin hook error" preventing skills context from loading. Fixed by:
- Using ${BASH_SOURCE[0]:-$0} fallback when BASH_SOURCE is unbound in Claude Code's execution context
- Adding || true to handle empty grep results gracefully when filtering status flags

Superpowers v2.0.0 Release Notes

Overview

Superpowers v2.0 makes skills more accessible, maintainable, and community-driven through a major architectural shift.

The headline change is skills repository separation: all skills, scripts, and documentation have moved from the plugin into a dedicated repository (obra/superpowers-skills). This transforms superpowers from a monolithic plugin into a lightweight shim that manages a local clone of the skills repository. Skills auto-update on session start. Users fork and contribute improvements via standard git workflows. The skills library versions independently from the plugin.

Beyond infrastructure, this release adds nine new skills focused on problem-solving, research, and architecture. We rewrote the core using-skills documentation with imperative tone and clearer structure, making it easier for Claude to understand when and how to use skills. find-skills now outputs paths you can paste directly into the Read tool, eliminating friction in the skills discovery workflow.

Users experience seamless operation: the plugin handles cloning, forking, and updating automatically. Contributors find the new architecture makes improving and sharing skills trivial. This release lays the foundation for skills to evolve rapidly as a community resource.

Breaking Changes

Skills Repository Separation

The biggest change: Skills no longer live in the plugin. They've been moved to a separate repository at obra/superpowers-skills.

What this means for you:

First install: Plugin automatically clones skills to ~/.config/superpowers/skills/
Forking: During setup, you'll be offered the option to fork the skills repo (if gh is installed)
Updates: Skills auto-update on session start (fast-forward when possible)
Contributing: Work on branches, commit locally, submit PRs to upstream
No more shadowing: Old two-tier system (personal/core) replaced with single-repo branch workflow

Migration:

If you have an existing installation:

Your old ~/.config/superpowers/.git will be backed up to ~/.config/superpowers/.git.bak
Old skills will be backed up to ~/.config/superpowers/skills.bak
Fresh clone of obra/superpowers-skills will be created at ~/.config/superpowers/skills/

Removed Features

Personal superpowers overlay system - Replaced with git branch workflow
setup-personal-superpowers hook - Replaced by initialize-skills.sh

New Features

Skills Repository Infrastructure

Automatic Clone & Setup (lib/initialize-skills.sh)

Clones obra/superpowers-skills on first run
Offers fork creation if GitHub CLI is installed
Sets up upstream/origin remotes correctly
Handles migration from old installation

Auto-Update

Fetches from tracking remote on every session start
Auto-merges with fast-forward when possible
Notifies when manual sync needed (branch diverged)
Uses pulling-updates-from-skills-repository skill for manual sync

New Skills

Problem-Solving Skills (skills/problem-solving/)

collision-zone-thinking - Force unrelated concepts together for emergent insights
inversion-exercise - Flip assumptions to reveal hidden constraints
meta-pattern-recognition - Spot universal principles across domains
scale-game - Test at extremes to expose fundamental truths
simplification-cascades - Find insights that eliminate multiple components
when-stuck - Dispatch to right problem-solving technique

Research Skills (skills/research/)

tracing-knowledge-lineages - Understand how ideas evolved over time

Architecture Skills (skills/architecture/)

preserving-productive-tensions - Keep multiple valid approaches instead of forcing premature resolution

Skills Improvements

using-skills (formerly getting-started)

Renamed from getting-started to using-skills
Complete rewrite with imperative tone (v4.0.0)
Front-loaded critical rules
Added "Why" explanations for all workflows
Always includes /SKILL.md suffix in references
Clearer distinction between rigid rules and flexible patterns

writing-skills

Cross-referencing guidance moved from using-skills
Added token efficiency section (word count targets)
Improved CSO (Claude Search Optimization) guidance

sharing-skills

Updated for new branch-and-PR workflow (v2.0.0)
Removed personal/core split references

pulling-updates-from-skills-repository (new)

Complete workflow for syncing with upstream
Replaces old "updating-skills" skill

Tools Improvements

find-skills

Now outputs full paths with /SKILL.md suffix
Makes paths directly usable with Read tool
Updated help text

skill-run

Moved from scripts/ to skills/using-skills/
Improved documentation

Plugin Infrastructure

Session Start Hook

Now loads from skills repository location
Shows full skills list at session start
Prints skills location info
Shows update status (updated successfully / behind upstream)
Moved "skills behind" warning to end of output

Environment Variables

SUPERPOWERS_SKILLS_ROOT set to ~/.config/superpowers/skills
Used consistently throughout all paths

Bug Fixes

Fixed duplicate upstream remote addition when forking
Fixed find-skills double "skills/" prefix in output
Removed obsolete setup-personal-superpowers call from session-start
Fixed path references throughout hooks and commands

Documentation

README

Updated for new skills repository architecture
Prominent link to superpowers-skills repo
Updated auto-update description
Fixed skill names and references
Updated Meta skills list

Testing Documentation

Added comprehensive testing checklist (docs/TESTING-CHECKLIST.md)
Created local marketplace config for testing
Documented manual testing scenarios

Technical Details

File Changes

Added:

lib/initialize-skills.sh - Skills repo initialization and auto-update
docs/TESTING-CHECKLIST.md - Manual testing scenarios
.claude-plugin/marketplace.json - Local testing config

Removed:

skills/ directory (82 files) - Now in obra/superpowers-skills
scripts/ directory - Now in obra/superpowers-skills/skills/using-skills/
hooks/setup-personal-superpowers.sh - Obsolete

Modified:

hooks/session-start.sh - Use skills from ~/.config/superpowers/skills
commands/brainstorm.md - Updated paths to SUPERPOWERS_SKILLS_ROOT
commands/write-plan.md - Updated paths to SUPERPOWERS_SKILLS_ROOT
commands/execute-plan.md - Updated paths to SUPERPOWERS_SKILLS_ROOT
README.md - Complete rewrite for new architecture

Commit History

This release includes:

20+ commits for skills repository separation
PR #1: Amplifier-inspired problem-solving and research skills
PR #2: Personal superpowers overlay system (later replaced)
Multiple skill refinements and documentation improvements

Upgrade Instructions

Fresh Install

# In Claude Code
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

The plugin handles everything automatically.

Upgrading from v1.x

Backup your personal skills (if you have any):

cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup

Update the plugin:
```
/plugin update superpowers
```
On next session start:
- Old installation will be backed up automatically
- Fresh skills repo will be cloned
- If you have GitHub CLI, you'll be offered the option to fork
Migrate personal skills (if you had any):
- Create a branch in your local skills repo
- Copy your personal skills from backup
- Commit and push to your fork
- Consider contributing back via PR

What's Next

For Users

Explore the new problem-solving skills
Try the branch-based workflow for skill improvements
Contribute skills back to the community

For Contributors

Skills repository is now at https://github.com/obra/superpowers-skills
Fork → Branch → PR workflow
See skills/meta/writing-skills/SKILL.md for TDD approach to documentation

Known Issues

None at this time.

Credits

Problem-solving skills inspired by Amplifier patterns
Community contributions and feedback
Extensive testing and iteration on skill effectiveness

Full Changelog: https://github.com/obra/superpowers/compare/dd013f6...main Skills Repository: https://github.com/obra/superpowers-skills Issues: https://github.com/obra/superpowers/issues

Uh oh!

FilesExpand file tree

RELEASE-NOTES.md

Latest commit

History

RELEASE-NOTES.md

File metadata and controls

Superpowers Release Notes

v5.0.2 (2026-03-11)

Zero-Dependency Brainstorm Server

Brainstorm Server Reliability

Subagent Context Isolation

v5.0.1 (2026-03-10)

Agentskills Compliance

New Features

Improvements

Bug Fixes

Maintenance

Community

v5.0.0 (2026-03-09)

Breaking Changes

New Features

Improvements

v4.3.1 (2026-02-21)

Added

Fixed

v4.3.0 (2026-02-12)

Changed

Fixed

v4.2.0 (2026-02-05)

Breaking Changes

Fixes

Improvements

Tests

v4.1.1 (2026-01-23)

Fixes

v4.1.0 (2026-01-23)

Breaking Changes

Fixes

v4.0.3 (2025-12-26)

Improvements

v4.0.2 (2025-12-23)

Fixes

v4.0.1 (2025-12-23)

Fixes

v4.0.0 (2025-12-17)

New Features

Major Changes

Breaking Changes

Other Improvements

v3.6.2 (2025-12-03)

Fixed

v3.5.1 (2025-11-24)

Changed

v3.5.0 (2025-11-23)

Added

Changed

v3.4.1 (2025-10-31)

Improvements

v3.4.0 (2025-10-30)

Improvements

v3.3.1 (2025-10-28)

Improvements

Bug Fixes

v3.3.0 (2025-10-28)

New Features

Files Added

v3.2.3 (2025-10-23)

Improvements

Files Changed

v3.2.2 (2025-10-21)

Improvements

Files Changed

v3.2.1 (2025-10-20)

New Features

Files Changed

v3.2.0 (2025-10-18)

New Features

Breaking Changes

Improvements