Superpowers Deep Dive: Connect Agent Design, Tests, and Code Review

In one line

Superpowers is a development methodology and skills framework that helps coding agents understand requirements, agree on a design, and connect small implementation tasks with tests and review.

Repository: obra/superpowers

An agent can produce code quickly while missing the behavior you wanted. Explaining the requirement again can take longer than editing the code. Superpowers is worth exploring at that point: it connects questions about the goal with planning, workspace preparation, testing, and review.

Our earlier look at mattpocock/skills focused on choosing practices for questions, terminology, and specifications. With Superpowers, pay attention to how the stages connect. Start with the earlier collection when you need a particular requirement practice; explore Superpowers when context keeps getting lost between design, implementation, and review.

We suggest a small feature with meaningful decisions, such as adding a list filter while preserving ordering and handling empty results. Follow the agreed conditions into the plan and tests. That gives you more useful adoption evidence than learning every skill name.

What can you do with it?

The README connects brainstorming, using-git-worktrees, writing-plans, implementation, code review, and branch completion. After design approval, the agent breaks down the work. During implementation, test-driven-development guides a failing test and the code needed to pass it. verification-before-completion asks for actual validation evidence before a completion claim.

Each stage leaves something concrete to review: behavior and design decisions, file paths and task order, then changes and tests. These artifacts give a new reviewer a starting point for understanding why a condition exists.

The README also distinguishes execution approaches. subagent-driven-development uses a fresh agent and review for each task. executing-plans performs the plan in the current session and uses a fresh review at the end. Review timing and cost differ, so choose according to the work and budget. A human still needs to assess the final changes and acceptance conditions.

You can also start with a focused practice such as systematic-debugging. If a recurring failure is the immediate problem, reproducing it and narrowing its cause may be a better first trial than adding a feature. Compare the official skill list with your team's current bottleneck.

Installation and the first conversation

In Claude Code, enter the official marketplace installation command in the conversation. The README installation section documents:

/plugin install superpowers@claude-plugins-official

Prepare the existing Claude Code environment and model connection first. For another coding tool, use its specific README section. The project instructs people using multiple tools to install separately for each one. Record the installation channel and version so teammates can compare behavior.

Start a fresh conversation and describe a small feature. The README uses a React todo list request as an example for seeing whether brainstorming starts. Here is a request adapted to a list filter:

I want to add a status filter to the customer list.
Inspect how the list and statuses work in the current code,
then ask about the user behavior and unresolved decisions.
We will agree on the design before moving to an implementation plan.

Read the questions themselves. Do they expose a product decision, or ask you to repeat something already present in the repository? The brainstorming guidance distinguishes clear small requests from changes needing design work. Size the discussion to the decision you need to make.

Scenario 1: Turn a feature request into a reviewable plan

A status filter raises choices about URLs, pagination, search, and ordering. Use brainstorming to settle the behavior, then move the approved design into planning:

Apply search and status filtering together and preserve current ordering.
Changing the filter returns to page one. Show an empty state for no results.
Make sure the design includes each condition.
Use the approved design to plan file changes and validation steps.

The planning skill asks for precise file paths, interfaces, and validation steps. Tasks should have independently testable deliverables worth reviewing. Look for a coherent task connecting a behavior change with the test that proves it.

Trace each condition through the plan. Combined search and filtering might appear in implementation but disappear from validation. A small feature might also acquire an unrelated data restructuring task. Resolve those gaps before the agent starts changing files.

The worktree workflow prepares a separate branch and checks the project's starting state. Keep your repository's branch rules and baseline tests in view. A worktree separates working files; host permissions and access to external services still belong to the surrounding execution environment.

Scenario 2: Investigate a recurring bug before changing code

Suppose changing a filter unexpectedly clears a search term. The debugging skill proceeds through investigation, comparison, hypothesis testing, and implementation. Start with reliable reproduction and follow the state through the system:

After entering a search term, changing the status filter clears the search.
Write down reproduction steps and expected behavior first.
Follow the input state through URL updates and query construction.
Test one supported hypothesis at a time before proposing a fix.

The debugging guidance describes gathering evidence at component boundaries. For this scenario, compare input state, URL updates, and query conditions. If you add logs, use reproduction data and include only the state you need.

Change one condition at a time while testing a hypothesis. Combining search preservation with an unrelated UI cleanup makes it harder to tell what fixed the problem. Ask for both the observed result and the explanation, then repeat the original reproduction steps.

Once the cause is understood, the TDD skill guides a failing test followed by a minimal change. Read whether the test demonstrates the user behavior that matters. A test showing search and filtering together gives a reviewer a clearer acceptance boundary than an assertion about an internal function name.

Scenario 3: Read completion claims alongside validation evidence

When implementation finishes, review scope and tests together. The review workflow considers specification compliance and code quality. Keep the design and plan beside the result so the reviewer can trace requirements:

Connect each condition in the approved design to changed files and validation.
Separate commands run, their success or failure, and remaining checks.
Identify edits outside the plan and paths that could affect existing behavior.

The completion verification skill requires reading full command output and exit status before claiming success. Lint, functional tests, and requirement coverage support different conclusions. Use the repository's existing checks and ask which evidence supports each condition.

Branch completion presents choices such as a PR or merge. Connect those choices to your organization's actual approval process. For the first pilot, spend time reading one small task's design, diff, and validation evidence together.

Which teams should explore it?

Useful capability: Superpowers exposes decisions before implementation and carries them into plans and tests. It is worth exploring for handovers and maintenance tasks where a brief request hides several edge cases. Assess the documents between design review and code review as part of the pilot.

Operating burden: Questions, plans, and reviews take time and model calls. A clear copy edit may need little discussion. Record which questions helped and where the process repeated existing work. Assign someone to review plugin updates that can change instructions.

Execution environment: Skills guide agent behavior. File permissions, command execution, and code sent to models need controls in the coding tool and surrounding environment. The README also documents a version-bearing logo request in the optional visual companion, which teams with network policies should review.

License: The repository uses MIT. Review LICENSE for modification and redistribution, and assess the connected coding tool and model service terms separately. Start with the stages your team actually needs.

Original sources and further reading

Wrapping up

The Hypemarc Builder Community will keep sharing the AI news and open source projects we explore each week. We'll continue gathering useful resources to share with fellow builders.

Open chat: AI Builders
Adoption advice and inquiries: Contact form
Get the next post: Blog RSS · AI resource library