superpowers-optimized — Claude Code plugin: what it does

<div align="center">

[![AI Coding Agents](https://img.shields.io/badge/USE_WITH-Claude_Code_%7C_Codex_%7C_OpenCode_%7C_Gemini_CLI_%7C_Antigravity-white?style=for-the-badge)]()

[![GitHub stars](https://img.shields.io/github/stars/REPOZY/superpowers-optimized?style=for-the-badge&color=white)](https://github.com/REPOZY/superpowers-optimized/stargazers)
[![Version](https://img.shields.io/github/v/release/REPOZY/superpowers-optimized?style=for-the-badge&color=white)](https://github.com/REPOZY/superpowers-optimized/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-white?style=for-the-badge)](LICENSE)
[![Install](https://img.shields.io/badge/install-now-white?style=for-the-badge&logo=claude)](https://github.com/REPOZY/superpowers-optimized#installation)

</div>

![](media/Superpowers-Optimized-Header.gif)

# Superpowers Optimized

**The production-grade fork of obra/superpowers** — same trusted workflow, dramatically leaner, safer, and more intelligent.

Built on the trusted obra/superpowers workflow and refined through research into LLM agent behavior, it adds automatic 3-tier workflow routing, proactive safety hooks, self-consistency verification at critical decision points, cross-session memory, and adversarial red-teaming — everything the original does, plus the discipline layer it was missing.

Cross-session memory changes the experience fundamentally. Without it, every session starts blind: the AI re-explores structure it already mapped, re-proposes approaches that were already rejected, re-debugs errors that were already solved. With the memory stack, it arrives knowing what was tried, what was decided, and why — and with a pre-computed snapshot of what was committed since the last session — and builds forward instead of sideways.

Five research-backed principles run throughout: *less is more* (minimal always-on instructions), *fresh context beats accumulated context* (subagents get clean scoped prompts, not polluted history), *compliance ≠ competence* (instructions must be carefully engineered, not just comprehensive), *verify your own reasoning* (multi-path self-consistency catches confident-but-wrong failures before they become expensive), and *accountability drives accuracy* (agents that know their output has real downstream consequences perform better).

### Why developers switch
| Feature                  | Original Superpowers          | Superpowers Optimized                          | Real-world impact                  |
|--------------------------|-------------------------------|------------------------------------------------|------------------------------------|
| Workflow selection       | Manual                        | Automatic 3-tier (micro / lightweight / full)  | Zero overhead on simple tasks      |
| Safety & hooks           | None                          | 10 proactive hooks overall, with platform-specific subsets on Codex/OpenCode | Strongest safety on Claude; partial hook parity on Codex/OpenCode |
| Security review          | None                          | Built into code review with OWASP checklist    | Security catches before merge      |
| Adversarial red team     | None                          | Red team agent + auto-fix pipeline             | Finds bugs checklists miss, fixes them with TDD |
| Error recovery           | None                          | Project-specific known-issues.md               | No rediscovering the same bug      |
| Token efficiency         | Standard                      | Always-on context hygiene + exploration tracking + automatic Bash output compression (76% savings on mixed sessions) | Less re-discovery, fewer wasted iterations    |
| Discipline enforcement   | Instructional tone             | Rationalization tables, red flags, iron laws   | Fewer LLM shortcuts                |
| Progress visibility      | None                          | Session stats (skills used, duration, actions)  | See what the plugin did for you    |
| Cross-session memory     | None                          | Four-file memory stack: `project-map.md` (structure cache) + `session-log.md` (decision history) + `state.md` (task snapshot) + `known-issues.md` (error map) + automatic `context-snapshot.json` (git blast radius, written every session start) | The AI starts every session with full project context — no re-exploring, no re-explaining, no re-debugging |

### Try it in 30 seconds
In any supported agent IDE, start a new chat and paste:

```
Activate Superpowers Optimized and plan a secure user-authentication endpoint with full TDD and security review.
```

The agent will automatically route to the correct workflow, apply safety guards, and run an integrated security review during code review — no manual skill selection required.

See [Installation](#installation) for install, update, and uninstall commands on all platforms.

> [!NOTE]
> **Codex parity boundary:** Claude Code gets the full 11-hook lifecycle. Codex now has verified live support for `SessionStart`, `UserPromptSubmit`, and `PreToolUse(Bash)` on macOS/Linux with `codex_hooks = true` and `codex-cli 0.118.0+` (tested on `0.118.0`). This repo now also ships a Codex-specific `PostToolUse(Bash)` smart-compress hook that can replace noisy Bash output after execution using the existing compression rules. `Stop` is implemented for Codex, but visible reminder surfacing should still be revalidated after install/update. Codex still does **not** expose Claude's `PostToolUse(Edit|Write|Skill)`, `PreToolUse(Skill)`, `SubagentStop`, `Read/Edit/Write` interception, or Claude's pre-execution Bash rewrite path, so full Claude parity is not possible today.

---

> [!IMPORTANT]
> **Compatibility Note:** This plugin includes a comprehensive workflow router and 24 specialized skills covering debugging, planning, code review, TDD, execution, and more.
>
> Other plugins or custom skills/agents in your `.claude/skills/` and `.claude/agents/` folders may interfere if they cover overlapping domains. Duplicate or competing skills can cause trigger conflicts, contradictory instructions, and unnecessary **context bloat/rot**, which will degrade the model's performance.
>
> **For the best experience and peak AI reasoning, we recommend disabling or removing all other plugins and existing `SKILL.md` or `AGENTS.md` files.** This ensures a clean environment with zero risk of conflicting instructions.


---

Upon initiating a session with your coding agent, the plugin immediately pauses to establish a precise understanding of your objective rather than proceeding directly to code. It collaborates with you through a structured dialogue to refine a clear, complete specification, presenting each element in concise, easily digestible segments for your review and approval.

Once the design is approved, the agent constructs a detailed implementation plan that enforces genuine red/green TDD cycles, strict adherence to YAGNI and DRY principles, and token-efficient instructions that eliminate unnecessary verbosity.

When you confirm to proceed, the plugin automatically routes the task to the appropriate workflow—either *subagent-driven-development* or *executing-plans*—and executes it through mandatory review gates: *subagent-driven-development* reviews every task with a single reviewer that must return both a specification-compliance verdict and a code-quality verdict, both workflows close with a whole-branch review on the most capable model available, and security analysis (per OWASP guidelines) is integrated on any sensitive changes. For complex logic, the *red-team* agent conducts adversarial testing to surface concrete failure scenarios. Each critical finding is automatically converted by the auto-fix pipeline into a failing test, followed by a targeted fix and regression verification.

**The agent evaluates relevant skills before every task.** These workflows are enforced as mandatory processes, never optional suggestions. Overhead remains strictly proportional to complexity:
- **Micro-tasks** bypass all gates entirely
- **Lightweight tasks** receive a single verification checkpoint
- **Full-complexity tasks** engage the complete pipeline

---

## How It Works

```
Session starts
        │
        ▼
┌─ SessionStart Hooks (run before your first message) ──────┐
│  context-engine.js →                                      │
│    git diff HEAD~1..HEAD → changed files                  │
│    git grep per changed file → blast radius               │
│    git log --oneline -5 → recent commits                  │
│    Writes context-snapshot.json to project root           │
│    (silent no-op if not a git repo)                       │
│                                                           │
│  session-start →                                          │
│    Injects using-superpowers routing instructions         │
│    Checks for available plugin update                     │
│                                                           │
│  session-memory.js →                                      │
│    Injects state.md, project-map.md, known-issues.md,     │
│    the last saved session-log entries, the snapshot —     │
│    in priority order, under a size budget                 │
└───────────────────────────────────────────────────────────┘
        │
        ▼
User sends a prompt
        │
        ▼
┌─ skill-activator.js (UserPromptSubmit hook) ──────────────┐
│  Is this a micro-task? ("fix typo on line 42")            │
│    YES → {} (no routing, zero overhead)                   │
│    NO  → Score against 22 skill rules                     │
│          Score < 2? → {} (weak match, skip)               │
│          Score ≥ 2? → Inject skill suggestions            │
└───────────────────────────────────────────────────────────┘
        │
        ▼
┌─ using-superpowers (always loaded at SessionStart) ───────┐
│  Entry sequence:                                          │
│    1. token-efficiency (always)                           │
│    2. Use the injected memory; read a file only when its  │
│       block says it was shortened or left out             │
│    3. Map stale? → re-read only the files it names        │
│                                                           │
│  Classify: micro / lightweight / full                     │
│                                                           │
│  MICRO → just do it                                       │
│  LIGHTWEIGHT → implement → verification-before-completion │
│  FULL → route to appropriate pipeline:                    │
│    Unclear decision → deliberation → brainstorm → plan    │
│    New feature → brainstorming → writing-plans → execute  │
│    Bug/error  → systematic-debugging → TDD → verify       │
│    Review     → requesting-code-review (w/ security)      │
│                 + red-team → auto-fix pipeline            │
│    Done?      → verification-before-completion            │
│    Merge?     → finishing-a-development-branch            │
└───────────────────────────────────────────────────────────┘
        │
        ▼  (meanwhile, running on every tool call)
┌─ Safety & Optimization Hooks (PreToolUse) ────────────────┐
│  block-dangerous-commands.js → 30+ patterns (rm -rf, etc) │
│  protect-secrets.js → 50+ file patterns + 14 content      │
│    patterns (blocks hardcoded API keys, tokens, PEM blocks │
│    in source code — instructs agent to use env vars)       │
│  bash-compress-hook.js → rewrites noisy Bash commands      │
│    to run through optimizer; never compresses diffs,       │
│    file reads, or failed commands; ~76% token savings      │
│    on mixed sessions; transparency markers always shown    │
└───────────────────────────────────────────────────────────┘
        │
        ▼  (after every Edit/Write and Skill call)
┌─ Tracking Hooks (PostToolUse) ────────────────────────────┐
│  track-edits.js → logs file changes for TDD reminders     │
│  track-session-stats.js → logs skill invocations          │
└───────────────────────────────────────────────────────────┘
        │
        ▼  (subagent Skill call, and when a subagent stops)
┌─ Subagent Guard (PreToolUse: Skill + SubagentStop) ───────┐
│  subagent-guard.js →                                      │
│    Denies plugin skills inside subagents before they run  │
│    On stop: blocks + forces redo only if one actually ran │
│      (transcript check; text match only as fallback)      │
│    Logs violations for visibility                         │
└───────────────────────────────────────────────────────────┘
        │
        ▼  (when Claude stops responding)
┌─ Stop Hook ───────────────────────────────────────────────┐
│  stop-reminders.js →                                      │
│    Then (if activity warrants):                           │
│    "5 source files modified without tests"                │
│    "12 files changed, consider committing"                │
│    "Session: 45min, 8 skill invocations [debugging 3x]"   │
└───────────────────────────────────────────────────────────┘


```

## Research-Informed Design

The design decisions in this fork are informed by three research papers on LLM agent behavior and by published experiments from 2389 Research. They motivated the approach; they were run on settings that differ from this plugin (SWE-bench-style tasks, chat logs, arithmetic and commonsense benchmarks, essay questions), so they are reasons for the design, not measurements of it.

### Context files cost more than they help

**Paper:** [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/abs/2602.11988) (v3, Sep 2026: CTXbench — 138 tasks, 12 repos — plus SWE-bench Lite; 4 agents. v1 called the benchmark AGENTbench.)

Key findings that shaped this fork:
- **Context files did not improve task success.** LLM-generated files changed success by −0.5% (SWE-bench) and −2% (CTXbench); developer-written files by +2.4%. None of these is statistically significant, though developer-written files did significantly beat LLM-generated ones.
- **They raised cost by 20–23%** (and 2.4–3.9 extra steps per task), because agents follow them: tools named in a context file were used 1.6–2.5x more often. Compliance did not translate into better outcomes.
- **Repository overviews and directory listings did not help agents reach the relevant files any sooner.** LLM-generated files mostly duplicated existing documentation — with the docs removed, they helped (+2.7%).
- **Following them takes more thinking**: reasoning tokens rose up to 22% (GPT-5.2), suggesting the extra instructions make tasks harder. File length itself showed no clear effect — what costs is the instructions being followed.

**What we changed:** Skills load on demand instead of living in always-on context, and the 3-tier complexity classification (micro/lightweight/full) skips skill loading for simple tasks. The `CLAUDE.md` contains only what an agent cannot discover (specific tooling, critical constraints, conventions), and `claude-md-creator` writes context files the same way. The always-on router drops sections that cannot apply to the current project — the fresh-project gate where a `project-map.md` exists, the map-staleness procedure where none does — and no longer asks the agent to re-read memory files the session-start hook has already injected.

### Prior assistant responses can degrade performance

**Paper:** [Do LLMs Benefit from Their Own Words?](https://arxiv.org/abs/2602.24287) (4 models, real-world multi-turn chat conversations from WildChat and ShareLM)

Key findings that shaped this fork:
- **Much less history often works as well.** Replacing prior assistant turns with one-sentence summaries, or keeping only the last exchange, often matched full context while using roughly 8x less of it. Summaries were the best configuration — often *better* than full history. Dropping assistant turns entirely cost some quality.
- **Context pollution is real:** in ~14% of turns, earlier assistant output leaked into later answers — an earlier task structure overriding a new instruction (the most common case), wrong code parameters carried over, hallucinated facts repeated. Replacing that history with neutral filler of the same length removed every flagged case, so it is the *content* of past answers, not context length, that misleads.
- **36.4% of mid-conversation prompts are self-contained "new asks"** that need no assistant history.
- **Filter by relevance, not recency.** The authors recommend keeping what is relevant to the current turn rather than compacting once a length threshold is hit.

**What we changed:** Subagents are built from scratch with only their task brief, the interfaces they touch, and global constraints — never the conversation, prior reasoning, or "state after task N" summaries. Cross-session memory is stored as short summaries (`[saved]` entries capped at 250 words) and recalled per prompt by relevance (session start also injects the two most recent entries when the memory budget allows). The `context-management` skill writes durable state to `state.md` so a fresh session can replace an accumulated one; it cannot remove turns from a live conversation. Injected memory is gated against stale instructions: a `state.md` older than the latest commit is framed as possibly stale rather than "resume from here".

*Caveat:* the paper studied chat conversations, not agentic tool loops. Applying it here is an extrapolation.

### Single reasoning chains fail on hard problems

**Paper:** [Self-Consistency Improves Chain of Thought Reasoning in Language Models](https://arxiv.org/abs/2203.11171) (Wang et al., ICLR 2023)

Key findings that shaped this fork:
- **A single chain-of-thought can be confident but wrong** — the model picks one reasoning path and commits, even when that path contains an arithmetic slip, wrong assumption, or incorrect causal direction.
- **Sampling several independent reasoning paths and taking a majority vote significantly improves accuracy** across arithmetic and commonsense benchmarks (e.g. +17.9% on GSM8K). More samples kept helping up to 40; 5–10 capture most of the gain.
- **Consistency correlates with accuracy** — low agreement signals the model does not know, which is itself useful.
- **Diversity of reasoning paths is what drives the gain.**

**What we changed:** `systematic-debugging` (Phase 3) and `verification-before-completion` apply an in-context version of the technique: before committing to a root cause or a completion verdict, the agent reaches an answer from 3–5 deliberately different starting points and votes. No majority means a hard stop — gather more evidence before touching code. This is an *approximation*: the paper's paths are separate samples, while these are written in one response and share the agent's blind spots. So the skills treat disagreement as strong evidence and agreement as weak, and the test or command — never the vote — proves the answer. The technique lives in `self-consistency-reasoner` and fires only at these high-stakes moments, keeping the token cost targeted.

### Social accountability, one-at-a-time fixing, and deliberation

**Sources (2389 Research):** [Team Spirit Matters](https://2389.ai/research/writing/team-spirit-matters/), the [Simmer](https://2389.ai/research/products/simmer/) refinement loop, [Deliberation: Perspectives, Not Answers](https://2389.ai/research/writing/deliberation-perspectives-not-answers/), and their [claude-plugins repository](https://github.com/2389-research/claude-plugins). These are small practitioner experiments and design write-ups, not controlled studies — treat them as directional.

Key ideas that shaped this fork:
- **Social accountability framing.** Adding one sentence — "other team members are relying on you and the quality of your work" — to multi-agent prompts won 24 of 33 LLM-judged comparisons against the same prompts without it (11 open-ended questions, GPT-4o-mini, three judges). Judges cited thoroughness, evidence and structure. The experiment did not measure accuracy, and was not run on code.
- **One directive per iteration.** Simmer refines an artifact by having a judge name the single most important fix (ASI, "Actionable Side Information") each round, keeping the best version so far so regressions do not carry forward. Applying fixes one at a time with re-assessment in between is this fork's adaptation for code review findings that share code; the speed and collision benefits are a design rationale, not a measured result.
- **Deliberation before deciding.** For half-formed decisions, hearing named stakeholder perspectives — each speaking once, without debate — can surface a reframing that a premature list of options would hide. The source is one practitioner's account.

**What we changed:** Accountability framing tells the `code-reviewer`, `red-team`, and implementer prompts what depends on their output (the red team is also told that accuracy matters more than volume, since a thoroughness nudge can inflate false positives). The auto-fix pipeline in `requesting-code-review` fixes one finding at a time: fix → targeted re-check of the touched files → re-assess the remaining findings → repeat. The `deliberation` skill handles decisions whose framing is still unclear.

### Combined principles

These sources motivate five principles throughout the fork:
1. **Less is more** — on-demand skills, minimal always-on instructions, and no injected instructions that cannot apply
2. **Fresh context beats accumulated context** — subagents get clean, task-scoped prompts instead of inheriting polluted history
3. **Compliance != competence** — agents follow instructions reliably, so the instructions themselves must be carefully engineered (rationalization tables, red flags, forbidden phrases) rather than simply comprehensive
4. **Check your own reasoning, and know its limits** — multi-path checks at critical decision points catch some confident-but-wrong chains; disagreement stops work, agreement still needs proof
5. **Accountability and iteration** — tell agents what depends on their output, and fix findings one at a time with re-assessment in between

None of these effects has been measured on this plugin yet. Changes motivated by them are checked for regressions by the test suites, not proven to improve outcomes.


---


## Session Memory: The AI That Remembers

The plugin builds a memory stack at your project root. Together they eliminate the most expensive form of session overhead: re-discovering things the AI already knew.

```
context-snapshot.json  ← git blast radius + changed files (written automatically every session)
project-map.md         ← structure + key files + critical constraints (never re-explore)
session-log.md         ← decision history + approach rejections (never re-explain)
known-issues.md        ← error→solution map (never re-debug the same thing)
state.md               ← current task snapshot (never lose mid-work progress)
```

### project-map.md — What exists and what it does

Generate once with "map this project". After that, the session-memory hook injects its content directly into every session — no instruction-following required. The AI has the map before your first message arrives.

**Memory is injected under a size budget.** Claude Code caps each hook's injected context at 10,000 characters; past that, the model receives a file path and a 2,000-character preview it is not told to read. The router and the memory therefore run as two hooks with a field each, and the memory hook fills its ~9,500-character budget in priority order: `state.md` → map staleness → the map's Critical Constraints → open known issues → the two latest session-log entries → the rest of the map → the snapshot. Whatever does not fit is named in the output (*"omitted: Directory Structure, Key Files…"*, *"Not shown for size — read when relevant: session-log.md…"*), so the model knows to open the file instead of assuming it saw everything. Keep Critical Constraints short — it is the map section that always gets in.

```markdown
# Project Map
_Generated: 2026-03-20 14:32 | Git: a4b9c2d_

## Directory Structure
skills/ — 24 skills, each in skills/<name>/SKILL.md
hooks/ — 10 hooks (JS) + hooks.json registry + skill-rules.json

## Key Files
hooks/skill-activator.js — UserPromptSubmit: context pressure gate (blocks plan execution at ≥60% context, reads session JSONL); skill hints via skill-rules.json; memory recall from session-log.md + known-issues.md. Micro-task detection skips all enrichment.
hooks/skill-rules.json — 22 rules: skill name, keywords, intentPatterns, priority.

## Critical Constraints
- hooks.json uses \" not ' around ${CLAUDE_PLUGIN_ROOT} (single quotes break Linux)
- plugin.json + marketplace.json must always have identical version strings

## Hot Files
hooks/stop-reminders.js, hooks/skill-activator.js, skills/using-superpowers/SKILL.md
```

**Staleness is automatic and bounded.** At every session start the hook compares the map's recorded commit to HEAD, intersects the diff with the paths the map actually documents, and names them: *"project-map.md is stale in 3 place(s): hooks/session-start, skills/using-superpowers/SKILL.md, ..."* — so refreshing the map is a short work list rather than an open-ended re-read. If the commit moved but nothing the map documents changed, it says that too, and the map stays trusted instead of being flagged for nothing.

Works on any project — git or non-git. If no git is detected during map generation, the AI offers to run `git init` (creates a `.git` folder, touches none of your files). If you decline, it falls back to timestamp comparison instead.

**First-build prompt.** You don't need to remember to generate a map. When you type any creation-intent request ("build me X", "create X", "implement X") in a directory with no `project-map.md`, the AI pauses before starting and explains exactly what it will lose without the memory stack. It offers to set everything up in ~30 seconds. Say yes once — every future session on that project starts with full context.

### context-snapshot.json — What changed right before this session

Written automatically by the `context-engine` hook on every session start. No setup, no action required — it exists before your first message arrives.

```json
{
  "git_hash": "9636c5c",
  "changed_files": ["hooks/context-engine.js", "hooks/hooks.json"],
  "changed_files_since": "last-session",
  "change_stat": "2 files changed, 140 insertions(+)",
  "recent_commits": ["9636c5c Check context-snapshot.json in Phase 1", "..."],
  "blast_radius": {
    "hooks/context-engine.js": ["hooks/hooks.json", "docs/plans/..."]
  }
}
```

`changed_files` are committed changes, never uncommitted work: everything committed since the previous session started (`changed_files_since: "last-session"`), or the last commit on a first session (`"last-commit"`). Systematic debugging reads it to answer "what changed since it last worked?" without running `git log`. Code review does not take its scope from here — the review range is always `BASE..HEAD` — but uses `blast_radius` to add callers of the files in that range when the snapshot is fresh (git hash matches HEAD).

`blast_radius` lists a file only when it contains a reference that **resolves** to the changed file's path — a relative import, or the repo path written out. References that can't be resolved (package-style imports, aliases, dynamic paths) are dropped rather than guessed, so the list is deliberately incomplete: an empty list means "nothing proven," not "no dependents." That trade is intentional. A half-right impact list is worse than none, because the agent learns to ignore it.

Automatically added to `.gitignore` — it's a tooling artifact, not project code.

### session-log.md — What happened

An optional, manually-maintained record of decisions, rejected approaches, and key facts. Write an entry when something is worth preserving — an architectural choice, a constraint discovered the hard way, an approach that was tried and failed. Skip it when there's nothing durable to record.

| Written by | Contains |
|---|---|
| You, via `context-management` | Goal, decisions, rejected approaches, key facts |

```markdown
## 2026-03-15 10:04 [saved]
Goal: Add cross-session memory to the plugin
Decisions:
- project-map.md injected by the session-start hook directly — makes it unconditional, not dependent on Claude following instructions
- session-log.md is manual-only; auto-entries were low-signal noise, all derivable from git log
Approaches rejected: Auto-appending a [auto] entry on every Stop event — produced 30 near-identical entries per session with no decisions or reasoning, just file lists
Key facts: hooks.json requires \" not ' around ${CLAUDE_PLUGIN_ROOT} — single quotes break variable expansion on Linux
Open: Monitor whether [saved] entries get used in practice; if not, consider folding key facts into project-map.md Critical Constraints instead
```

Write an entry by invoking `context-management`. The two most recent live entries are injected at session start when the memory budget has room for them (state, constraints, and open issues come first); entries marked `[superseded by ...]` are never injected, because an overturned decision reads as current and is worse than no decision at all.

Older entries surface automatically as you work. On every prompt the activator ranks the log by IDF-weighted relevance — a distinctive term outweighs a common one — and injects only entries that clear both a relevance and a coverage gate, with recency acting as a tiebreak rather than the deciding factor. Each entry is injected **at most once per session**, so a long conversation never pays for the same history twice.

**Entry size directly affects your per-session token cost** — the stop-hook monitors this and warns when entries exceed budget. Keep entries under 115 words.

### known-issues.md — Error memory

Maintained by the `error-recove...