superpowers

superpowers is the operating system for agent work: it turns a request into a deliberate workflow of discovery, design, implementation, verification, and handoff. an agent selects and reads an applicable skill before it acts; it does not improvise a process an existing skill already owns.

an agent that improvises process pays twice: once inventing a pattern an existing skill owns, and forever after maintaining the undocumented paths it produced. reading the skill first converts accumulated method into reusable local advantage — the next agent inherits a designed rule instead of archaeology. invariant: no durable workflow decision is made by an agent who never checked for its owner.

routing to the narrowest owner before acting:

request: "add a second export format to the weekly report"
  1. check for an owning skill/standard: report-export owns format addition.
  2. read that owner in full before exploring or editing.
  3. apply its rule: extend the existing export boundary.
  4. do not invent a parallel generator "because it was faster to start".

without routing:
  1. skip the owner, copy a similar generator, fork its logic.
  2. two undocumented export paths now exist; neither is the rule.

1. identify the outcome, owner, constraints, and evidence of done.
2. route the work to the narrowest applicable skill before exploring or editing.
3. use brainstorming before a new design or behavior; write an implementation plan when uncertainty or blast radius warrants one.
4. update the owning specification and slice before code.
5. execute the approved slice, following its change ledgers and boundaries.
6. use systematic debugging for an unexpected result; do not patch a symptom.
7. verify with evidence before a completion claim.

skill selection follows uncertainty and consequence, not file count:

• routine cleanup, bounded documentation, ordinary implementation, reversible refactoring → proceed inline after reading the applicable owner.
• new behavior → design first.
• unexpected failure → causal debugging.
• broad or high-risk change → written plan and stronger verification.

invoking a skill does not authorize an external reviewer, subagent, branch change, deployment, account mutation, or other consequential action; those keep their own authority boundary.

do not stall because an option is imperfect, a reviewer is unavailable, a dependency is inconvenient, or a specification has a non-material gap. choose the safest bounded direction, record uncertainty, continue every reversible action that preserves the approved outcome.

withhold only the exact action needing unavailable credentials, a physical observation, external authority, a user decision between materially different outcomes, or an irreversible external consequence. inspection, preparation, implementation around the boundary, verification, and handoff continue.

use one independent review when a wrong decision could cause material harm or be expensive to reverse:

• security or privacy boundaries
• destructive data or infrastructure changes
• legal or financial consequences
• production-wide architecture
• a high-blast-radius migration whose safety cannot be proven from current source and local evidence

routine cleanup, inventory, ordinary plans, reversible implementation, and normal debugging do not justify a separate reviewer.

reviewer protocol:

• starts fresh with the decision question, scope, and necessary raw evidence — not inherited conversation or a preferred answer.
• read-only; strongest available model.
• must return alternatives, risks, safest recommendation, uncertainty, remaining blockers.
• result is evidence: reconcile against live source, specifications, privacy, safety, and user authority; record tool, model, date, evidence, disagreement, selected decision.
• one review is sufficient; a reviewer never recursively launches another reviewer.
• an unavailable reviewer does not block reversible progress — record the tooling limit, use the safest locally supported recommendation.

plugins are distribution bundles, not runtime dependencies for agent work. do not enable, install, refresh, or route through a plugin unless the active task explicitly authorizes it. migrate durable behavior into the local system:

• standards → this corpus
• repeatable procedures → local skills
• tool connections → configuration

remove the plugin dependency once its useful behavior has a local owner; never maintain parallel plugin and local paths.

the upstream implementation is private reference material under references/superpowers/; its separately maintained skill corpus belongs in references/superpowers-skills/. neither is a project runtime dependency, source of product behavior, or replacement for this catalog's owner decisions. read upstream guidance to learn a repeatable method, then record the chosen local rule in Curly Guru when it becomes a stable project convention.

• explore, design, or edit before checking for an applicable skill.
• treat a plan as implementation evidence.
• use a skill to bypass a stale slice, a protected file, or a user decision.
• install an upstream plugin as an unexamined runtime dependency.
• dispatch a reviewer for routine work merely because the task spans several files.
• stop all work when only one consequential action is blocked.

bad

# agent transcript (no skill consulted)

request: "add stripe to the weekly report export"
agent response: copying export from braintree implementation, merging into shared file, adjusting routes.

result: three undocumented export paths, no canonical rule.

the agent skips the applicable domain or plan file, guesses a pattern, copies three similar report generators into one shared file with conditional logic, adjusts two other report-fetching routes, and runs the build. it compiles, but:

• three completely different code paths for slightly different data shapes, none documented.
• a later agent adding a fourth source cannot find the canonical rule (never defined).
• a bug in the shared pattern breaks all three sources equally; commit history hides which change caused the regression.

cycles spent inventing a pattern; the codebase pays ongoing cost of three undocumented paths that could have been one designed rule.

good

# agent transcript (skill consulted first)

request: "add stripe to the weekly report export"
agent action: read report-export skill → learn extension boundary rule → implement named adapter.

result: one documented path, clear owner for future sources.

the agent reads the owning plan or standard covering "when to introduce extension points" (future-proofing) and "how to structure shared report generation" (source organization). extension points need at least two real independent implementations or an approved contract; this is the first data source, so a simple adapter for the current provider is the right shape.

it implements one named, specific report generator for this source, clear boundaries, one test or probe. the pattern stays explicit and local. when a second approved data source arrives, the agent has a concrete boundary to extract an extension point — not a generic framework built for the first thing.

slices · specification-first · change visibility · verification evidence