This page documents the release history of the obra/superpowers plugin repository, covering version milestones, breaking changes, platform additions, and bug fixes. It covers the plugin infrastructure and core skill mechanics. For detail on how individual skills work, see the Key Skills Reference. For platform-specific integration internals, see Platform-Specific Features.
| Version | Date | Highlights |
|---|---|---|
| v4.3.1 | 2026-02-21 | Cursor support; Windows polyglot wrapper restored |
| v4.3.0 | 2026-02-12 | Brainstorming hard gates; EnterPlanMode intercept; synchronous SessionStart |
| v4.2.0 | 2026-02-05 | Codex native skill discovery; escape_for_json O(n²) fix; worktree isolation required |
| v4.1.1 | 2026-01-23 | OpenCode plugins/ directory standardized |
| v4.1.0 | 2026-01-23 | OpenCode native skill tool; experimental.chat.system.transform hook |
| v4.0.3 | 2025-12-26 | using-superpowers invocation strengthened |
| v4.0.2 | 2025-12-23 | Slash commands restricted to user-only invocation |
| v4.0.1 | 2025-12-23 | Skill access via Skill tool clarified |
| v4.0.0 | 2025-12-17 | Two-stage code review; DOT flowcharts; skill consolidation; test infrastructure |
| v3.6.2 | 2025-12-03 | Linux POSIX compatibility fix in polyglot wrapper |
| v3.5.1 | 2025-11-24 | OpenCode bootstrap via session.created |
| v3.5.0 | 2025-11-23 | OpenCode support; lib/skills-core.js shared module |
| v3.4.x | 2025-10-30 | Bootstrap optimization; brainstorming simplified |
| v3.3.0 | 2025-10-28 | Experimental Codex support |
| v3.2.x | 2025-10-18 | superpowers: namespace; code-reviewer agent; writing-skills improvements |
| v3.1.0 | 2025-10-17 | Skill names lowercased; Anthropic best practices |
| v3.0.1 | 2025-10-16 | Anthropic first-party skills system |
| v2.0.0 | — | Skills repository separation (obra/superpowers-skills) |
Sources: RELEASE-NOTES.md1-115
Platform Integration Manifest Files by Version
Sources: RELEASE-NOTES.md6-11 RELEASE-NOTES.md56-59 RELEASE-NOTES.md143-145 .claude-plugin/plugin.json1-13
One of the more complex histories in the codebase is how the SessionStart hook executes, especially on Windows. The mechanism changed several times across versions.
Hook Execution Path Changes
Sources: RELEASE-NOTES.md13-23 RELEASE-NOTES.md46-49 RELEASE-NOTES.md63-68
Added: Cursor integration
A .cursor-plugin/plugin.json manifest was added. The SessionStart hook output now emits both additional_context and hookSpecificOutput.additionalContext fields to satisfy both the Cursor and Claude Code hook contracts.
Fixed: Windows polyglot wrapper (#518, #504, #491, #487, #466, #440)
Claude Code's .sh auto-detection on Windows was prepending bash to the hook command path, which broke the run-hook.cmd polyglot wrapper. Changes made:
session-start.sh renamed to session-start (extensionless) to suppress auto-detectionrun-hook.cmd polyglot wrapper restored with multi-location bash discoverydirname "$0" path resolution (compatible with dash/sh, not just bash)Sources: RELEASE-NOTES.md3-23
Changed: Brainstorming skill
The brainstorming SKILL.md was updated from a descriptive to an enforcement model:
<HARD-GATE> block added — no implementation, code, or scaffolding until design is approvedwriting-plans as the only valid terminal stateEnterPlanMode intercept added to the using-superpowers skill flow graph — Claude's native plan mode is never entered directlyFixed: SessionStart hook now runs synchronously
hooks.json changed from async: true to async: false. With async execution, the hook could complete after the first model turn, meaning using-superpowers instructions were absent from the initial context.
Sources: RELEASE-NOTES.md25-49
Breaking: Codex bootstrap CLI removed
The superpowers-codex CLI, its Windows .cmd wrapper, and the bootstrap content file were removed. Codex now uses native skill discovery via the ~/.agents/skills/superpowers/ symlink. The old ~/.codex/skills/ path is deprecated.
Fixed: escape_for_json O(n²) performance
The character-by-character loop in the session-start script using ${input:$i:1} was O(n²) in bash due to substring copy overhead (60+ seconds on Windows Git Bash). Replaced with bash parameter substitution patterns (${s//old/new}) — a single C-level pass per pattern.
Improved: Worktree isolation now required
using-git-worktrees was added as a required dependency in both subagent-driven-development and executing-plans skills. Main branch work is allowed only with explicit user consent.
| Fix | Issue(s) | Notes |
|---|---|---|
| Codex native skill discovery | — | Removes Node.js dependency |
| Windows hook execution | #331 | session-start.sh called directly |
| Windows async hook | #404, #413, #414, #419 | async:true prevents TUI freeze |
escape_for_json performance | — | Bash substitution replaces loop |
| Codex PowerShell path expansion | #285, #243 | $HOME instead of ~/ |
| Codex path resolution in installer | — | fileURLToPath() for spaces/special chars |
Sources: RELEASE-NOTES.md52-113
Breaking (v4.1.0): OpenCode switched to native skill tool
The custom use_skill and find_skills tools were removed. Skills must now be symlinked to ~/.config/opencode/skills/superpowers/. Bootstrap injection moved from session.prompt({ noReply: true }) to the experimental.chat.system.transform hook, eliminating the side-effect where the selected agent reset to "build" on first message.
Fixed (v4.1.1): OpenCode directory name standardized
OpenCode's official documentation uses ~/.config/opencode/plugins/ (plural). All references updated from plugin/ to plugins/. Symlink instructions corrected to include rm before ln -s and a missing skills symlink step was added.
Sources: RELEASE-NOTES.md116-164
v4.0.0 was a major feature release with several structural changes.
Two-stage code review in subagent-driven-development
Two separate reviewer subagents now run after each task:
| Stage | Agent | Concern |
|---|---|---|
| 1 | spec-reviewer | Compliance with spec — reads actual code, does not trust implementer's report |
| 2 | code-quality-reviewer | Code quality, test coverage, maintainability — runs only after spec review passes |
New prompt templates added in skills/subagent-driven-development/:
implementer-prompt.mdspec-reviewer-prompt.mdcode-quality-reviewer-prompt.mdDOT flowcharts as process specifications
Key skills were rewritten using DOT/GraphViz flowcharts as the authoritative process definition rather than prose. The "Description Trap" was documented in writing-skills: if a skill description contains workflow summaries, Claude follows the short description instead of reading the flowchart. Fix: descriptions must be trigger-only ("Use when...").
Skill consolidation (breaking)
| Removed skill | Moved to |
|---|---|
root-cause-tracing | bundled in systematic-debugging/ |
defense-in-depth | bundled in systematic-debugging/ |
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) |
Test infrastructure added
Three test frameworks introduced:
| Suite | Location | Purpose |
|---|---|---|
| Skill triggering | tests/skill-triggering/ | Validates 6 skills trigger from naive prompts |
| Claude Code integration | tests/claude-code/ | JSONL transcript analysis via claude -p |
| Subagent end-to-end | tests/subagent-driven-dev/ | go-fractals/ and svelte-todo/ projects |
v4.0.2: Slash commands restricted
disable-model-invocation: true added to all three command files (commands/brainstorm.md, commands/write-plan.md, commands/execute-plan.md). Claude can no longer invoke slash commands via the Skill tool — they are restricted to manual user invocation. The underlying skills (superpowers:brainstorming, etc.) remain available for autonomous invocation.
Sources: RELEASE-NOTES.md167-298
run-hook.cmd used ${BASH_SOURCE[0]:-$0} (bash-specific syntax). On Ubuntu/Debian where /bin/sh is dash, this caused a "Bad substitution" error. Replaced with POSIX-standard $0.
Sources: RELEASE-NOTES.md301-309
v3.5.0 introduced OpenCode as the second supported platform:
use_skill and find_skills tools implemented in .opencode/plugins/superpowers.jslib/skills-core.js shared ES module created — used by both OpenCode and Codex to avoid duplicationchat.message hook with re-injection on session.compacted eventstests/opencode/v3.5.1 changed injection point from chat.message hook to session.created → session.prompt({ noReply: true }).
Sources: RELEASE-NOTES.md312-352
The superpowers-codex Node.js script was added with three sub-commands: bootstrap, use-skill, and find-skills. Skills used the superpowers:skill-name namespace. Personal skills could override superpowers skills when names matched. Bootstrap was wired via a minimal AGENTS.md entry.
This CLI was later replaced entirely in v4.2.0 by native Codex skill discovery.
Sources: RELEASE-NOTES.md378-403
v3.2.0 introduced two significant changes:
superpowers: prefix (e.g., superpowers:test-driven-development). Files updated: brainstorming, executing-plans, subagent-driven-development, systematic-debugging, testing-skills-with-subagents, writing-plans, writing-skills.docs/plans/YYYY-MM-DD-<topic>-design.md before implementation.v3.2.1 added the superpowers:code-reviewer agent definition to agents/code-reviewer.md. All skill cross-references updated to use the namespaced form.
v3.2.2 added enforcement language to using-superpowers: the "1% rule", the "MANDATORY FIRST RESPONSE PROTOCOL" checklist, and 8 documented rationalization patterns with counter-arguments.
v3.2.3 corrected skill invocation instructions from "Use the Read tool" to "Use the Skill tool."
Sources: RELEASE-NOTES.md405-455
All skill name: fields in frontmatter changed to lowercase kebab-case matching their directory names. Examples: brainstorming, test-driven-development, using-git-worktrees. Anthropic best practices document (skills/writing-skills/anthropic-best-practices.md) added.
Cross-reference markers standardized across all skills:
**REQUIRED BACKGROUND:****REQUIRED SUB-SKILL:****Complementary skills:**Sources: RELEASE-NOTES.md491-548
This was the foundational architectural change. All skills moved from the plugin into a dedicated repository (obra/superpowers-skills), making the plugin a lightweight management shim.
Key infrastructure added
| File | Role |
|---|---|
lib/initialize-skills.sh | Clones obra/superpowers-skills; offers fork creation if gh is installed; handles migration from old install |
docs/TESTING-CHECKLIST.md | Manual testing scenarios |
.claude-plugin/marketplace.json | Local testing config |
Migration behavior (from v1.x)
~/.config/superpowers/.git backed up to .git.bakskills.bakobra/superpowers-skills created at ~/.config/superpowers/skills/Auto-update on session start
hooks/session-start.sh was updated to fetch from the tracking remote each session. If the local branch could fast-forward, it merged automatically. If diverged, it notified the user. The SUPERPOWERS_SKILLS_ROOT environment variable (~/.config/superpowers/skills) was established as the canonical path used throughout hooks and commands.
Removed in v2.0.0
hooks/setup-personal-superpowers.shscripts/ directory (moved to obra/superpowers-skills)Sources: RELEASE-NOTES.md572-800
using-superpowers Enforcement Progression
Sources: RELEASE-NOTES.md167-181 RELEASE-NOTES.md405-416 RELEASE-NOTES.md421-441
| Version | Breaking Change | Migration |
|---|---|---|
| v4.2.0 | Codex superpowers-codex CLI removed | Use ~/.agents/skills/superpowers/ symlink |
| v4.1.0 | OpenCode use_skill/find_skills tools removed | Symlink to ~/.config/opencode/skills/superpowers/ |
| v4.0.0 | 6 standalone skills merged into parent skills | No user action; skills accessed via parent |
| v3.2.0 | All skill cross-references require superpowers: prefix | Update any custom skills referencing superpowers skills |
| v3.1.0 | Skill name: fields changed to lowercase | Update any hardcoded skill name references |
| v2.0.0 | Skills moved to obra/superpowers-skills repo | Auto-migrated on first session start; backup created |
Sources: RELEASE-NOTES.md52-59 RELEASE-NOTES.md139-143 RELEASE-NOTES.md283-291 RELEASE-NOTES.md469-476 RELEASE-NOTES.md492-499 RELEASE-NOTES.md583-609
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.