Superpowers: An Open-Source Framework That Teaches AI Coding Agents to Think Like Engineers

AI coding agents write code fast, but their engineering discipline is poor—this is a pain point shared by virtually every developer using Claude Code, Cursor, Devin, or GitHub Copilot. Superpowers is aimed squarely at this problem: it's not yet another prompt template, but a methodology that forces AI agents through the complete workflow of "brainstorming → design → planning → test-driven development → code review." According to the project's introduction video on YouTube, it gained over 308,000 stars in a single week, with nearly 5,000 added in a single day—the market has voted with its feet at a remarkable pace.

The Problem: AI Agents' "Write First, Ask Never" Habit

The typical behavior pattern of existing coding agents is: the moment you speak, they start writing code. Requirements are guessed, features are embellished on their own initiative, and tests are skipped entirely. When bugs appear, there's no systematic debugging path—just randomly changing a few lines and hoping for the best. Code review doesn't exist at all, and testing is treated as an afterthought. When multiple agents push a project forward simultaneously, the lack of coordination mechanisms leads to conflicts, ultimately burning through massive amounts of tokens and leaving behind a pile of hard-to-maintain code.

The author of Superpowers summarizes this behavior as "code first, questions never." To understand the value of Superpowers, you first have to acknowledge that this situation cannot be solved by a prompt like "please think before you act"—when models are given a choice, they will almost always take the shortcut.

Superpowers' Solution: Turning Process into Enforced Skills

The core design of Superpowers is a set of composable "skills" that activate automatically in sequence and that the agent must follow. The entire workflow begins with brainstorming: the agent repeatedly asks clarifying questions until you truly articulate what you want to do and why. Once consensus is reached, it produces a design document short enough to actually read.

Then comes the planning phase: Git Worktrees are used to create isolated development branches, and the test baseline is verified to be clean. When writing plans, work is broken down into tasks of 2-to-5-minute granularity, each with exact file paths and complete code. Next, there are two execution modes—subagent-driven development dispatches a fresh, context-independent subagent for each task, with review immediately after each task completes; or inline execution of the plan, with a single review at the end.

Test-Driven Development: Reversing the Agent's Coding Order

Test-driven development is the most disruptive part of Superpowers. The agent must first write a failing test, watch it fail with its own eyes, then write the minimum code to make it pass, and only after it passes is refactoring allowed. This completely inverts the coding habits of most agents—they write implementation first, and tests are either never written or written in a way that verifies nothing.

The skill also includes a built-in reference checklist of common testing anti-patterns: mocking the code under test, testing implementation details rather than behavior, and writing tests that always pass. The agent learns what a bad test looks like before writing tests, thereby actively avoiding them.

Skill in the context of AI coding agents refers to a reusable module that encapsulates a specific workflow, instructions, and verification steps. Unlike traditional prompt templates, skills are typically stored as structured files (such as Markdown) that contain trigger conditions, execution steps, and success criteria, and can be automatically recognized and invoked by the agent. Superpowers' skill design emphasizes "composability" and "forced activation": multiple skills can be chained into a complete workflow according to dependencies, and the agent cannot skip skills that have been activated—thus converting soft best practices into hard execution constraints. This mechanism is akin to installing a "behavioral operating system" for the agent, forcing it to follow preset discipline in specific scenarios rather than relying on the model's own judgment.

Test-Driven Development (TDD) is a software development methodology whose core loop is "red-green-refactor": first write a test expected to fail (red), then write the minimal implementation that just makes the test pass (green), and finally refactor the code under the protection of tests to improve the design. The key value of TDD lies in translating requirements into executable assertions and ensuring code always has test coverage. For AI coding agents, the counterintuitive aspect of TDD is that it requires the agent to focus on "how to verify correctness" before considering "how to implement the feature," forcing the agent to clarify expected behavior before acting, thereby reducing speculative coding and over-engineering. Superpowers makes TDD a mandatory skill precisely to exploit this order reversal against the agent's habit of "writing implementation first, adding tests later."

Systematic Debugging and Verification Loops

When problems arise, Superpowers provides a four-phase root-cause investigation process, using techniques such as root-cause tracing, defense in depth, and condition-based weighting to progressively narrow the scope. The agent doesn't scatter print statements everywhere; instead, it carefully instruments the code, precisely traces execution paths, and pinpoints the exact location of the bug. After the fix, there's a verification step to ensure the root cause—not the surface symptom—has been resolved.

If Superpowers itself misbehaves—for example, a skill triggers when it shouldn't, or the agent ignores the established plan—you can use the "Diagnose Superpowers" skill. It reads the session transcript, reports what happened with line-level evidence, and exports a redacted bundle for filing bug reports.

Multi-Agent Collaboration and Branch Management

For large projects, subagent-driven development lets the main agent dispatch a focused new subagent for each task, each with independent context and precise task specifications. The main agent reviews results one by one, fixing and retrying or escalating when there are problems. When tasks are truly independent, this is cheaper than inline execution and also avoids context contamination. Both workflows support dispatching parallel agents for true concurrency. Git Worktrees provide isolation for each development branch so that work doesn't collide.

Collaboration is treated as a first-class citizen. The request code review skill checks against the original plan item by item, reports issues by severity, and critical issues directly block progress. The receive code review skill teaches agents how to respond constructively to teammate feedback rather than defensively. The wrap-up phase offers clear options: merge to the main branch, create a pull request, keep the branch, or cleanly discard it.

Git Worktrees is a feature of the Git version control system that allows multiple working trees to be checked out simultaneously in the same repository, each corresponding to a different branch while sharing the same .git directory. This means developers can work on multiple feature branches in parallel in different directories without switching branches, completely isolated from one another. In multi-agent collaboration scenarios, each agent can be assigned to work in its own worktree, avoiding conflicts and context loss caused by branch switching. The isolation of worktrees also allows agents to safely make experimental changes without affecting the main branch or the work of other agents, thereby improving coordination and reliability in concurrent development.

Extensibility and Testing Toolchain

Superpowers itself is extensible. The "write skill" skill teaches agents to create new skills according to best practices, including the testing methodology that Superpowers enforces. Each skill is stored as a clearly structured markdown file containing instructions, examples, and verification steps. The repository includes a testing toolchain called Drill Evil, and skill behavior tests run against multiple agents to ensure consistency.

Infrastructure tests live in the tests directory and run via shell scripts or NPM test. The philosophy of the testing toolchain is simplicity and "evidence over claims"—new skills must pass the same standard of scrutiny as core skills.

Four Principles That Cannot Be Bypassed

Superpowers is built on four core principles: test-driven development, always write tests first; systematic over ad hoc, process always beats guessing; reduce complexity, simplicity is the primary goal, no gold-plating; evidence over claims, verify before declaring success.

These are not suggestions but hard constraints written into the skills themselves, which the agent cannot skip. This is crucial—if you give the model room to choose, it will most likely take shortcuts, and Superpowers' approach is to remove that option entirely.

"Evidence over claims" is a principle in software engineering that emphasizes verifiability, requiring that any assertion about system state or feature completion be supported by objective evidence rather than subjective claims alone. In the context of AI agents, this means agents cannot merely claim that a "task is complete" or that "tests pass"; they must provide reproducible evidence such as test run logs, code diffs, and build output. Superpowers writes this principle into its skills, requiring agents to perform verification steps and show results before declaring success, thereby preventing agents from falsely reporting completion due to hallucination or overconfidence. This principle works closely with practices such as test-driven development and systematic debugging to form the trustworthy foundation of agent behavior.

Costs and Use Cases

Superpowers enforces discipline, but discipline has real costs: it's slower up front. Brainstorming and planning do take time. However, according to its introduction, this time is immediately repaid by fewer bugs, less rework, and vastly improved coordination in multi-agent collaboration. For indie developers and small teams, this is the difference between a "coding assistant" and a "competent team member"; for large organizations, it's the difference between chaos and scale.

In terms of installation, Superpowers is distributed as a plugin covering 17 coding agent platforms, usually installable with a single command. Claude Code can be installed via the official marketplace or the Superpowers marketplace; Cursor, Devin, and others have their own plugin ecosystems; GitHub Copilot CLI, Gemini, Grok, Kimi, Qwen, OpenCode, and others each have their own installation procedures, all listed in the README. After installation, skills activate automatically the next time you start coding, with no additional configuration required.

It's worth noting that the above information mainly comes from the project's official introduction video; the methodology behind the star count and its sustainability have yet to be verified by third parties. Some paragraphs in the video transcript contain duplication and transcription errors, so for actual feature details, the repository documentation should be taken as authoritative.

One-line Summary

Superpowers uses enforced skill workflows to make AI coding agents follow the engineering discipline of brainstorming, design, test-driven development, and code review.

Paragraph Summary

Superpowers is an enforcement methodology for AI coding agents aimed at solving agents' lack of engineering discipline—their habit of "writing code first, asking questions later." Through a composable skill system, it forces agents to complete brainstorming, design documents, task breakdown, test-driven development, and systematic debugging in sequence, with test-driven development as its core disruptive practice requiring agents to write a failing test before writing minimal implementation. The framework supports both subagent-driven development and inline execution modes, uses Git Worktrees for branch isolation, and includes built-in multi-agent collaboration and code review skills. Superpowers is distributed as a plugin covering 17 coding agent platforms and is itself extensible through the "write skill" skill; its four core principles (TDD, systematic process, reduced complexity, evidence over claims) are written into its skills as hard constraints. The project claims over 308,000 stars in a single week, but this figure has not yet been independently verified.