A personal Claude Code-only fork of obra/superpowers.
Upstream Superpowers is a cross-platform toolkit, so features unique to Claude Code fall outside its scope. This fork is Claude Code-only — it drops the cross-harness machinery and builds directly on Claude Code's native capabilities, tuned for Opus/Fable-class models.
This fork integrates Claude Code-native features into the Superpowers workflow.
- Leverage Claude Code-native features as they're released
- Personal fork — maintained for one workflow, not as a community project
| Feature | Claude Code Version | Description |
|---|---|---|
| Native Task Management | v2.1.16+ | Dependency tracking, real-time progress visibility |
| Structured Task Metadata | v2.1.16+ | Goal/Files/AC/Verify structure with embedded json:metadata |
| Pre-commit Task Gate | v2.1.16+ | Opt-in hook blocks git commit while a native task other than the current one is in progress |
| User-Thrown Gate Enforcement | v2.1.16+ | userGate / user-gate tag + opt-in hooks force re-validation when Claude closes a user-ordered verification task (see Recommended Configuration) |
| Configurable Commit Strategy | v2.1.16+ | Opt-in workflow.json switches plan execution from per-task commits to a single commit at plan end (see Commit Strategy) |
| Superpowers (Vanilla) | Superpowers CC |
|---|---|
|
|
|
# Register marketplace
/plugin marketplace add Rascal/superpowers-cc
# Install plugin
/plugin install superpowers-cc@superpowers-cc-marketplace/plugin install --source url https://github.com/Rascal/superpowers-cc.gitThird-party marketplaces don't auto-update by default — installs stay frozen on the original version until you refresh. To get future fixes and new optional hooks automatically:
- Run
/plugin - Open the Marketplaces tab
- Toggle Enable auto-update on
superpowers-cc-marketplace
Or refresh manually any time:
/plugin marketplace update superpowers-cc-marketplace
Check that the skills appear in the slash-command palette:
# Should see (among others):
# /superpowers-cc:brainstorming
# /superpowers-cc:writing-plans
# /superpowers-cc:executing-plans
# /superpowers-cc:onboard
-
brainstorming - Activates before any creative work and classifies the request: spike (feasibility probe → recommendation), bounded (short in-chat design → approval → implement directly), or architectural (full pipeline below). Ceremony scales with the task; the approval gate never does.
-
writing-plans - Architectural path only. Breaks the approved spec into bite-sized tasks — exact file paths, complete code, verification — with a Global Constraints section every task inherits. Creates native tasks with dependencies; a reviewer subagent checks the plan against the spec.
-
using-git-worktrees - Activates at execution time. Creates or verifies an isolated workspace before implementation starts.
-
subagent-driven-development or executing-plans - Executes the plan. SDD dispatches a fresh implementer per task with file-based briefs and reports, one merged review (spec + quality) per task, a capped fix loop that resumes the implementer via SendMessage, and a compaction-proof ledger; executing-plans works the plan's tasks in order in its own session with per-task verification.
-
test-driven-development - Activates during implementation. RED-GREEN-REFACTOR; deletes code written before tests.
-
requesting-code-review - Final whole-branch review against the plan, fed a review package and the ledger's deferred/parked findings.
-
finishing-a-development-branch - Verifies tests, presents merge/push/keep/discard, cleans up the worktree.
The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.
When writing-plans creates tasks, each task carries structured metadata that survives across sessions and subagent dispatch:
TaskCreate:
subject: "Task 1: Add price validation to optimizer"
description: |
**Goal:** Validate input prices before optimization runs.
**Files:**
- Modify: `src/optimizer.py:45-60`
- Create: `tests/test_price_validation.py`
**Acceptance Criteria:**
- [ ] Negative prices raise ValueError
- [ ] Empty price list raises ValueError
- [ ] Valid prices pass through unchanged
**Verify:** `pytest tests/test_price_validation.py -v`
```json:metadata
{"files": ["src/optimizer.py", "tests/test_price_validation.py"],
"verifyCommand": "pytest tests/test_price_validation.py -v",
"acceptanceCriteria": ["Negative prices raise ValueError",
"Empty price list raises ValueError",
"Valid prices pass through unchanged"]}
```The json:metadata block is embedded in the description because TaskGet returns the description but not the metadata parameter. This ensures metadata is always available — for executing-plans verification, subagent-driven-development dispatch, and .tasks.json cross-session resume.
Canonical design doc: docs/user-gate-flow.md. The section below is a reader-facing summary.
This flow addresses a recurring failure: the user says "add a gate" or "verify it works" without specifying how, the agent invents a verification method, then finds it expensive at execution time and walks around it — closing the gate with an inline shortcut. The fix is a three-layer architecture that never bothers the user during planning and only surfaces a forced question when the agent genuinely can't proceed without one.
The whole flow is opt-in. It activates only when you register the hooks below in .claude/settings.json. The gate skills sit dormant without the hook — installing the plugin alone does nothing.
Users who want questions will say "brainstorm". Users who ask for a gate during planning just want the work done, they don't want a four-question interrogation. So writing-plans is silent here: it applies the stricter definition of a gate and tags liberally. Better to over-tag and let the execution-time hook filter than to over-question the user mid-plan.
| Layer | When | What it does |
|---|---|---|
| Write-plan (silent tagging) | Plan authoring | Detects gate-language in the brief ("verify", "prove", "a gate" (noun use), "first on one then all", "make sure", "don't proceed until"). Tags the resulting task with userGate: true + tags: ["user-gate"]. No user questions. Uses the stricter definition: strict user gates AND strict agent gates AND gray-in-between all get tagged. |
| Execute-plan (hard trigger via hook) | Task close / stop | The PostToolUse + Stop hooks fire when a tagged task is closed. The agent must then assess each criterion and choose one of two paths (below). |
specifying-gates skill (dormant unless hook active) |
Execute-plan, only when the agent cannot proceed | Asks 4 structured questions to the user (a fifth when the gate dispatches a subagent) that lock down the HOW: observable outcome, proof mechanism, scope, failure policy. Produces a structured verify spec the agent consumes. |
When a tagged task comes up, the agent asks itself: do I know how to verify this?
- "Verify the
/healthendpoint returns 200" → the HOW is self-evident. Agent just hits the endpoint, captures the output, postsAC: <criterion> — PROVEN BY <evidence>. No slash command needed. The hook sees the proof and passes. - "Check it works" → the HOW is vague. Agent invokes
specifying-gates, which asks the user the four minimal questions, then uses the answers to execute real verification. No silent invention, no inline shortcut. - Write-plan explicitly flagged
requiresUserSpecification: true→ same path: invokespecifying-gates, ask the user.
The user is only interrupted at execute time, and only when the alternative is the agent making something up.
Register both hooks in .claude/settings.json (see "Recommended Configuration" below for the exact JSON). Without them:
writing-plansstill tags gates (harmless extra metadata).specifying-gatesstill exists but is never triggered automatically.- Nothing enforces evidence at close — behavior is identical to vanilla.
Install one hook or both. The PostToolUse hook catches per-task closures; the Stop hook catches end-of-plan "everything done" claims. They compose — both firing on the same session is fine.
Both hooks fail-open on errors and have env-var kill switches (SUPERPOWERS_USERGATE_GUARD=0, SUPERPOWERS_USERGATE_STOP_GUARD=0) for one-off session bypasses without editing settings.
Tail the hook trace log while a tagged gate task is closing: tail -F /tmp/claude-hooks/user-gate-trace.log. See Hook Trace Logging for the full schema.
Canonical design doc: docs/workflow-config-flow.md. The section below is a reader-facing summary.
By default, plan execution commits per task: every plan task ends with its own Commit step, and implementer subagents commit their work before review. That default is unchanged and recommended — frequent commits give fine-grained history and per-task rollback. Projects that prefer a single reviewable commit per plan can opt in to an at-end strategy.
The whole flow is opt-in, with a single switch: docs/superpowers/workflow.json in your project. Without that file (or without the key), behavior is byte-identical to the default.
{"commitStrategy": "at-end"}When at-end is set, a notice injected at session start instructs the agent to:
- write plans without per-task Commit steps;
- end every plan with one final task — "Commit the full implementation" — blocked by all implementation tasks, staging the implementation but omitting design docs/specs under
docs/superpowers/unless you explicitly ask to commit them; - tell implementer subagents not to commit (the coordinator runs that final task, making the single commit), with reviewers reading the uncommitted working-tree diff.
Setup notes:
- Prefer a guided setup? Run
/superpowers-cc:onboard— it covers this feature alongside the other optional flows. - Valid values are
"per-task"(the default) and"at-end"; anything else falls back to per-task. - User-level default: the file may instead live at
~/.claude/superpowers/workflow.json, applying to every project that has no project-level file. Lookup is project first, then user — the first file found wins entirely (no merging). A project file of{"commitStrategy": "per-task"}restores per-task commits for that project while a user-level default exists. - This flow has no enforcement gates — the session-start notice is the only delivery mechanism, so it takes effect from the next session on and relies on plan-time compliance (see the design doc for this boundary).
- Undo: delete the file or remove the
commitStrategykey — per-task commits resume at the next session start.
Testing
- test-driven-development - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)
Debugging
- systematic-debugging - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
- verification-before-completion - Ensure it's actually fixed
Collaboration
- brainstorming - Three-path router (spike / bounded / architectural): Socratic design refinement with ceremony scaled to the task
- writing-plans - Detailed implementation plans + native task dependencies
- executing-plans - Sequential in-session execution with per-task verification
- dispatching-parallel-agents - Concurrent subagent workflows
- requesting-code-review - Pre-review checklist
- receiving-code-review - Responding to feedback
- using-git-worktrees - Parallel development branches
- finishing-a-development-branch - Merge/push/cleanup decision workflow
- subagent-driven-development - Fast iteration with per-task merged review (spec + quality in one verdict), a capped SendMessage fix loop, and a per-plan workspace ledger
User-Thrown Gates (optional flow, see "User-Thrown Gate Enforcement" above)
- checking-gates - Do-I-know-HOW self-check for user-gate tasks; runs verify + posts
AC:…PROVEN BYevidence, or hands off to specifying-gates - specifying-gates - Interactive 4-question AskUserQuestion flow that locks down the HOW for a vague user-gate
Meta
- using-superpowers - Introduction to the skills system
- Test-Driven Development - Write tests first, always
- Systematic over ad-hoc - Process over guessing
- Complexity reduction - Simplicity as primary goal
- Evidence over claims - Verify before declaring success
Read more: Superpowers for Claude Code
This is a personal fork. To add or modify a skill, follow the writing-skills maintainer skill — it covers creating and pressure-testing skill content. It lives at .claude/skills/writing-skills/ in this repo as a project skill and is not shipped in the plugin. See .claude/skills/writing-skills/SKILL.md for the complete guide, and CLAUDE.md for the maintainer notes.
Claude Code may automatically enter Plan mode during planning tasks, which conflicts with the structured skill workflows in this plugin. To prevent this, add EnterPlanMode to your permission deny list.
In your project's .claude/settings.json:
{
"permissions": {
"deny": ["EnterPlanMode"]
}
}This blocks the model from calling EnterPlanMode, ensuring the brainstorming and writing-plans skills operate correctly in normal mode. See upstream discussion for context.
Optional PreToolUse hook that blocks git commit while a native task other than the one you are working on is in_progress. The most recently started task is exempt, because the documented per-task flows (executing-plans, and the Step 5: Commit step inside every writing-plans task) commit while that task is still open — blocking it would block every task, every time. What the hook catches is leaving task A open, moving on to task B, and committing. Known limitation: the gate inspects Bash tool calls only — a git commit issued through another shell-capable tool (e.g. PowerShell) passes unguarded.
Pending tasks never block. Commits made inside a subagent are always allowed: a hook fired in a subagent is handed the coordinator's transcript, so it would otherwise block the subagent over tasks it neither opened nor can close.
Opt in via .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/plugins/marketplaces/superpowers-cc-marketplace/hooks/examples/pre-commit-check-tasks.sh"
}
]
}
]
}
}See the header of hooks/examples/pre-commit-check-tasks.sh for how it parses the session transcript, which task is treated as the current one, and the one flow it is known to over-block (a coordinator holding several tasks in_progress for parallel dispatch cannot commit from the main thread).
Optional PostToolUse hook that guards every task close — most strictly when Claude closes a user-thrown gate task without capturing concrete evidence for every acceptance criterion. A user-thrown gate is any task that carries "userGate": true or a "user-gate" entry in tags inside its json:metadata fence — set by writing-plans when the user explicitly asked for a verification step ("make sure to verify X", "add a gate", "prove it on one, then all").
The hook fires on every TaskUpdate that sets status to completed. User-gate tasks must show AC: … — PROVEN BY … evidence in the task's window (or a direct user message there) to pass. Ordinary tasks get a lighter check: any assessment signal — a user message, assessment language in the agent's output or tool results, or explicit evidence — lets the close through; only fully silent closes are challenged ("TASK CLOSED WITHOUT ASSESSMENT"). On either path, a task that declares evidence axes (requireEvidenceTokens / requireABCompare in its metadata) additionally requires at least one token per axis in the close window.
Opt in via .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "TaskUpdate",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/plugins/marketplaces/superpowers-cc-marketplace/hooks/examples/post-task-complete-revalidate.sh"
}
]
}
]
}
}See the header of hooks/examples/post-task-complete-revalidate.sh for how it parses json:metadata and the USER-ORDERED GATE banner, and how the SUPERPOWERS_USERGATE_GUARD=0 escape hatch works.
Optional Stop hook that complements the PostToolUse hook above. It fires when Claude signals plan completion ("plan complete", "both gates passed", "implementation complete", etc.) but the transcript shows user-thrown gate tasks were closed without subsequent per-criterion proof. Requires Claude to post evidence in the form AC: <criterion> — PROVEN BY <evidence> before it can stop.
Opt in via .claude/settings.json:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/plugins/marketplaces/superpowers-cc-marketplace/hooks/examples/stop-revalidate-user-gates.sh"
}
]
}
]
}
}See the header of hooks/examples/stop-revalidate-user-gates.sh for the full list of completion keywords and the SUPERPOWERS_USERGATE_STOP_GUARD=0 escape hatch.
Optional PreToolUse hook on TaskUpdate that refuses to move a task into status=in_progress while its blockedBy list still points at tasks that are not yet completed. Motivation: observed failure mode — a coordinator jumps to a later task ("this one is simpler, zero setup") even though its declared prerequisites feed it. The plan meant V0.x to catalog state before V1.x replays consume it; without the catalog, the replay runs blind.
The hook does not silently refuse. Its stderr invites self-assessment first ("is this a hallucination — did you already do this work informally?"), offers three escalation paths (do the blocker, cancel it if truly obsolete, or raise the ordering to the user with AskUserQuestion), and explicitly warns against the bypass move of closing the blocker with status=completed without doing the work.
Opt in via .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "TaskUpdate",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/plugins/marketplaces/superpowers-cc-marketplace/hooks/examples/pre-task-blockedby-enforce.sh"
}
]
}
]
}
}See the header of hooks/examples/pre-task-blockedby-enforce.sh for the transcript-walking logic and the SUPERPOWERS_BLOCKEDBY_GUARD=0 escape hatch.
Optional PostToolUse hook on Agent that fires the moment a subagent's tool_result arrives — before the coordinator absorbs it and reports upward. If the in_progress task carries requireEvidenceTokens (multi-axis evidence requirement) or the requireABCompare: true shortcut, the hook checks that the subagent's report contains at least one token from each axis. Missing axes → block with stderr naming them, forcing immediate re-dispatch rather than "looks good" at close time.
When the task has no evidence requirement in metadata, the hook passes silently.
Opt in via .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Agent",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/plugins/marketplaces/superpowers-cc-marketplace/hooks/examples/post-agent-return-validate.sh"
}
]
}
]
}
}See the header of hooks/examples/post-agent-return-validate.sh for the metadata schema and the SUPERPOWERS_AGENT_RETURN_GUARD=0 escape hatch.
All four user-gate hooks (post-complete revalidate, stop revalidate, pre-blockedby enforce, post-agent return validate) write one-line decision traces to /tmp/claude-hooks/user-gate-trace.log (override via SUPERPOWERS_USERGATE_TRACE_LOG). Tail during development with:
tail -F /tmp/claude-hooks/user-gate-trace.log
Each line is pipe-separated: TIMESTAMP | hook-name | task=N | event | reason (the Stop-event hook writes session=<hash> in the third field instead of task=N). Events include enter, skip, parsed, scanned, pass, block, error. Skip reasons identify the short-circuit (e.g. tool=Bash, status=pending, guard=0). This is the fastest way to see why a hook did or did not fire on a specific task.
Optional Stop-event hook that blocks "fresh session later" / "context is full" deflections when real context usage is below 50%.
Opt in via .claude/settings.json:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/plugins/marketplaces/superpowers-cc-marketplace/hooks/examples/stop-deflection-guard.sh"
}
]
}
]
}
}See the header of hooks/examples/stop-deflection-guard.sh for the full list of blocked phrases, configuration environment variables, and fail-open behavior.
Every example hook needs jq and a Python interpreter — python3, falling back to python. Each hook probes both by running them rather than by command -v, because a command can sit on PATH, be executable, and still fail to run (the Windows Store python3 stub does exactly that).
When a dependency is missing the hook prints a one-line warning to stderr naming itself, then allows the action — it never fails closed, because a missing interpreter must not block every commit and every task update. Claude Code records that stderr in the session transcript alongside the allow decision, so an inert hook shows up in transcript mode instead of passing for one that ran and approved.
The example hooks are executable code that refuses tool calls, so they get tests:
bash scripts/test-hooks.sh # every suite (~1 min)
bash scripts/test-hooks.sh -f stoprevalidate # one hook, by suite-name substring
# suite names: fixtures, agentreturn, blockedby,
# deflection, postcomplete, precommit, stoprevalidate —
# a substring that matches none runs zero cases and exits green
bash scripts/test-hooks.sh --mutate # also verify the tests can fail
Each case builds a synthetic stdin payload plus a synthetic transcript in a temp tree — no live session, no network, nothing but bash, jq and python3 — and asserts the decision (exit code, allow-JSON on stdout) plus the specific claim the message makes (which task id, which status, which axis, which percentage). Both directions are covered per hook: the case it must block, and the cases it must let through.
--mutate breaks each hook in a known way, in a copy, and requires the suite to
notice. A surviving mutant means nothing asserts that behavior. Cases live in
scripts/test-hooks/cases-*.sh; mutants in scripts/test-hooks/mutants.txt.
Run it before shipping a change to anything in hooks/examples/.
Skills update automatically when you update the plugin:
/plugin update superpowers-cc@superpowers-cc-marketplaceThis fork diverged from obra/superpowers at v5.x. Cross-harness support was removed on purpose and upstream is no longer tracked; the core skill philosophy is inherited, the Claude Code-native integrations are this fork's own.
MIT License - see LICENSE file for details