Superpowers for AI coding agents: spec first, tests first

You give an AI coding agent a request. It writes code immediately, the tests pass, and you merge. A few weeks later, someone opens the file and cannot tell why the feature works this way, what the tests cover, or where the design decisions live. The code runs, but nobody dares change it.

Agents create this kind of technical debt quickly because they rarely stop to ask, “What do you actually need this for?” Superpowers, obra’s open-source GitHub project, is designed to interrupt that pattern. It installs a set of skills and a working method into your existing agent: clarify intent first, write a spec and plan first, write tests first, and review before merging.

The problem: why does coding immediately create technical debt?

Human requests are rarely complete. “Add report export” does not specify the audience, format, data source, or behavior when there is no data. A person usually asks for clarification. A default agent tends to do the opposite: fill the gaps with assumptions and implement that interpretation. The result works in a demo but is not necessarily what you need.

The code-first workflow has three successive gaps. First, no spec: design decisions are scattered through code, with no document to consult during disagreements. Second, no tests written first: tests are often added afterward to match generated code. Third, no independent review: the person assigning the work is also the only person reading it.

In my view, coding immediately is not always wrong. A one-line fix or a disposable script does not need a spec. Discipline earns its cost when others must read or maintain the change, or when mistakes are expensive: real user features, schema changes, billing logic, or operations scripts running on real systems.

What is Superpowers? A skills framework, not a standalone application

Superpowers is a skills framework and software development methodology for AI coding agents, released under the MIT license at obra/superpowers. The latest version when I checked was v7.0.1, released October 21, 2026. In OctoCounts’ GitHub Trending snapshot for October 30, 2026, it ranked second for the day with around 1,034 new stars. That signals attention, not proof of quality.

Understand this up front: Superpowers has no server or application to open, does not replace your model, and does not replace your team’s CI. It is a set of Markdown skills and startup instructions, packaged for individual harnesses. You install it into Claude Code, Cursor, Gemini CLI, or Codex, and the agent in that harness follows the methodology described in the skills.

It addresses discipline, not capability. Skills turn good habits into a required workflow, and the TDD skill’s rules call for deleting implementation written before tests. It is best suited to people using AI coding agents daily for changes that require long-term maintenance.

Architecture and how it works

The toolkit consists of 15 skills in four groups:

The standard workflow has seven steps: brainstorm; create an isolated Git worktree; write a plan with 2–5-minute tasks; have subagents execute tasks with fresh context; follow RED–GREEN–REFACTOR TDD; perform two-stage code review; then finish the branch and merge. Information moves in that order: intent becomes a spec, the spec becomes a plan, the plan becomes code and tests, and only a satisfactory review leads to merging.

Superpowers enforces this through skill-triggering conventions, not code-level controls. Because these are prompt instructions, a harness may follow them incompletely. This is the method’s biggest limitation.

Technically, Superpowers needs one of the 16 supported harnesses listed in its documentation, that harness’s model and API, Git, and a test runner. It has no separate runtime or API key and stores no separate state beyond the repository and agent session.

Installation by harness

Before installing, prepare three things: a supported harness already signed in to its model/API, a Git repository, and a working test runner. Without a repository, worktrees and branch workflows have no foundation. Without a test runner, TDD is just a slogan.

To be explicit: I checked these commands against the official documentation on October 31, 2026, but have not tested them on a real machine.

Each harness has its own installation; there is no single universal command.

Claude Code, through the official marketplace:

/plugin install superpowers@claude-plugins-official

Or use Superpowers’ own marketplace: /plugin marketplace add obra/superpowers-marketplace, followed by /plugin install superpowers@superpowers-marketplace.

Cursor, in Agent chat: /add-plugin superpowers. Gemini CLI: gemini extensions install https://github.com/obra/superpowers (update with gemini extensions update superpowers). Codex: open /plugins, find superpowers, and select Install Plugin. Copilot CLI: copilot plugin marketplace add obra/superpowers-marketplace, then copilot plugin install superpowers@superpowers-marketplace.

After installation, restart the harness and check its plugin list. Start a new session with a brainstorming request for an ambiguous feature. Expected behavior: the agent asks clarifying questions and presents the spec in sections for approval.

Updates depend on the harness and are often automatic. Removing the plugin is enough to uninstall it, because Superpowers has no separate server or data to migrate. For telemetry, the brainstorming skill’s optional UI loads a logo accompanied only by the Superpowers version, not your prompts or source code. If your environment restricts outbound connections, set SUPERPOWERS_DISABLE_TELEMETRY to true.

Common problems: if you chose the wrong marketplace, remove the plugin and reinstall with the correct command; do not manually copy skills into a harness outside the 16 supported ones; if skills do not trigger, you may have directly requested implementation—start again with brainstorming.

Technical evaluation

The clearest benefit is settling the spec before coding, while disagreements are still cheap. Each 2–5-minute task identifies target files, contents, and verification steps, so you review small pieces rather than an enormous end-of-day diff. TDD requires behavior to be expressed as a test before implementation instead of tests being fitted to generated code. Two-stage review adds a second pair of eyes before merging.

The drawbacks follow directly from those benefits. Questions, plans, subagents, and two rounds of review add interactions, tokens, and time. For small or exploratory tasks, the overhead can exceed the actual work. I see this not as a tool defect but as the nature of discipline: it is intended to slow down work worth slowing down.

Parallel subagents, each carrying separate context, plus two rounds of review also cost substantially more tokens than a single direct agent run. The project does not publish a verified benchmark for this trade-off, so measure it in your own project.

For security, MIT-licensed source and no separate server are positives: no additional third party holds your code. The main risks are prompts and repository permissions you grant the agent. An agent in a worktree can still read and change repository code, and agent review does not replace human review of sensitive changes. Restrict permissions to what is needed and do not put secrets into brainstorming prompts.

Operationally, trying it on one branch is easy; standardizing it across a team is harder. Updates are handled individually by harnesses, skill behavior varies across 16 harnesses, and there is no central dashboard showing which version everyone uses.

Comparison with alternatives in the same space

Criteria: scope, enforcement, TDD, review before merge, harness support, and operational cost.

Superpowers does not replace single-purpose skills; it can work alongside them. Use Impeccable for design or Hallmark to avoid careless design, while Superpowers provides the framework. Similarly, Cloudflare Security Audit Skill is a narrowly scoped audit skill. These linked articles are in Vietnamese.

Compared with a default agent, the biggest difference is what remains afterward: an approved spec, a plan with small tasks, tests constraining behavior, and a review. If someone must still understand and confidently change it three months later, a workflow framework starts earning its keep.

Compared with an in-house process, Superpowers saves documentation-writing and maintenance effort, in exchange for an externally defined method and potentially inconsistent behavior across harnesses. A team’s own AGENTS.md is narrower but fully controlled. In my view, teams with an effective internal process do not need Superpowers.

Headroom handles context compression, while Superpowers handles work sequence, so they are not competitors. Similarly, CC Switch only switches providers for the same agent user. Both linked articles are in Vietnamese.

Practical use cases

For backend teams, Superpowers fits substantial features: a settled spec aligns backend and frontend on API behavior before implementation, and pre-merge review helps maintain shared standards.

For DevOps and SRE, the value is routing infrastructure-as-code and operational scripts through tests and review before applying them. Requiring tests and letting review block execution is worthwhile, provided those tests really run in a test environment.

For IT admins, sysadmins, and homelab operators, a practical case is writing automation scripts on a separate branch with a clear way back: discard the worktree if it goes wrong, and merge only after review. The project describes agents working autonomously for hours, but that is its claim, not a result I have verified.

Risks, limitations, and rollback

The most immediate risk is losing code written before tests. The TDD skill calls for deleting such code, so uncommitted exploratory work may be lost if you enter the workflow midway. Commit or stash exploratory work before starting a TDD session.

The second risk is worktree divergence from the main branch. The longer an agent works in isolation, the farther main moves, creating merge conflicts. Keep sessions short and merge soon after a satisfactory review to reduce this risk.

The third risk is an endless second review. If each round introduces more requested changes, the session may never reach merging. Set the limit up front: the second review blocks only genuine defects.

Rollback is lightweight because Superpowers has no separate state. Before merging, discard the worktree and branch. After merging, revert the commit in Git. To stop using it entirely, uninstall the plugin; no data migration is required.

Conclusion: who it fits, who it does not, and the next step

Superpowers fits teams and individuals using AI coding agents for features with complex requirements that need behavior-constraining tests and pre-merge review. It is not a good fit for one-line tasks, hotfixes, quick exploration, or environments without Git or a test runner.

My suggested next step is not a team-wide rollout. Install it in the one harness you use most, run a complete brainstorming, planning, TDD, and review session on a test branch, and ask three questions: did the spec catch misunderstandings early, did small tasks make review easier, and was the total time acceptable? Only if all three answers are yes should you consider standardizing it across the team.

References

• Official documentation and source: https://github.com/obra/superpowers
• Releases, including v7.0.1 on October 21, 2026: https://github.com/obra/superpowers/releases
• GitHub Trending snapshot for October 30, 2026 (third party): https://octocounts.com/trending