Superpowers Makes Your Agent Write the Spec Before It Writes Code

The most-starred repository in this week's GitHub trending list is not a model, a framework, or a startup's open-source loss leader. It is a folder of Markdown files that tells your coding agent how to behave.

Superpowers, by Jesse Vincent, sits at roughly 311,000 stars with about 5,900 added in the past week. Its own description: a complete software development methodology for your coding agents, built on a set of composable skills plus some initial instructions that make sure the agent actually uses them.

Three hundred thousand stars for a methodology is a strange thing to look at. Either the largest cohort of developers in a decade has simultaneously decided they want process, or the star button has become a bookmark for "I should think about this later". Probably both. But the thing itself is worth taking seriously, because it is the most opinionated answer anyone has shipped to the question of what an agent should do before it writes code.

The first move is to not start

Here is the workflow as the README describes it. As soon as the agent sees you are building something, it does not jump into writing code. It steps back and asks what you are actually trying to do.

Once it has teased a spec out of the conversation, it shows it to you in chunks short enough to read. Not one wall of requirements. Chunks. After you sign off, it produces an implementation plan detailed enough, in the README's words, for "an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing" to follow.

That sentence is the best thing in the repository. It is also a precise description of what an LLM is on a bad day, and writing the plan for that reader is a discipline most engineers skip because we assume the reader shares our context.

Then, once you say go, it launches subagent-driven development: agents work through each task, inspect and review their work, and keep going. The README claims it is not uncommon for the agent to work autonomously for a couple of hours without deviating from the plan.

What is actually in the box

Fifteen or so skills, grouped by function.

Testing has one entry, and it is the one that matters: test-driven-development, the red-green-refactor cycle, with a reference document on testing anti-patterns. Debugging has systematic-debugging, a four-phase root-cause process with techniques for tracing, defense in depth and condition-based waiting, plus verification-before-completion, whose only job is to stop the agent declaring victory on something that is not fixed.

Collaboration is where the real weight is: brainstorming to draw out intent, writing-plans, executing-plans, dispatching-parallel-agents, requesting and receiving code review, using-git-worktrees, finishing-a-development-branch, and subagent-driven-development with its two-stage review — spec compliance first, then code quality.

Two meta skills close the loop: writing-skills, for creating new ones, and using-superpowers, the introduction that prompts the model to load the system at the start of a conversation. Because the skills trigger automatically, the theory is that you do not have to remember any of this. Your agent just has it.

Install, per harness, sixteen times over

This is the part that tells you how fragmented the agent tooling market has become. Superpowers ships instructions for Claude Code, Antigravity, the Codex app and CLI, Cursor, Devin CLI, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build, Kimi Code, OpenCode, Pi, Qwen Code, Hermes, and Muse.

Claude Code, via the official marketplace:

/plugin install superpowers@claude-plugins-official

Or through Vincent's own marketplace:

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Cursor, in the agent chat: /add-plugin superpowers. Gemini CLI: gemini extensions install https://github.com/obra/superpowers. Copilot CLI: register the marketplace, then copilot plugin install superpowers@superpowers-marketplace. Antigravity: agy plugin install https://github.com/obra/superpowers. Devin: devin plugins install obra/superpowers. Factory Droid: register, then install. Codex app and CLI both go through the official plugins marketplace.

If you use more than one harness, you install it separately for each. Which means the same twelve skills exist as twelve copies with no shared update path, and the README's advice for updating is "somewhat coding-agent dependent, but often automatic". That is not a criticism of this project. It is the current state of the ecosystem, and watching a methodology repo cope with it is genuinely informative.

The contribution policy is the tell

Buried in the contributing section: they do not generally accept contributions of new skills, updates to skills must work across all supported agents, and they do not accept agent-written PRs that fix issues filed by someone else unless a maintainer asked for one, even when you hit the same problem.

Think about what that last rule is for. The obvious failure mode for a repo like this is being buried in plausible-looking skills generated by the very agents the skills are meant to govern. Vincent has seen it coming and pre-empted it, at the cost of looking unfriendly.

It also has a subtler implication. If your agent can generate a skill for anything, the scarce resource stops being the skill and becomes the judgement about which skills are worth having. That judgement is what the repository is actually selling, and it is not open to pull requests.

Where the methodology breaks

Four things, in order of how often I have seen them bite.

Process cannot fix taste. A perfectly executed plan for a badly conceived feature produces a well-tested version of the wrong thing. The brainstorming skill helps by asking what you actually want, but it will not tell you the idea is dull.

Token economics. Spec, chunked review, plan, subagent dispatch, two-stage review per task, verification before completion. On a small task this is a spectacular amount of overhead. The methodology is designed for work measured in days, and it will feel absurd on a one-line fix.

Plans drift. Two hours of autonomous work against a plan written at minute zero is fine when the plan was right. When the third task reveals the second was based on a wrong assumption, you get two hours of confident work in the wrong direction, and the review is the only thing standing between you and a very large diff.

And the honest one: skills are prompts, and prompts are suggestions. Everything here depends on the model choosing to follow the skill rather than five other things it also knows. That is why using-superpowers exists as a bootstrap — it is a prompt whose job is to make other prompts load.

Who this is for

If you are shipping code that other people depend on, and you have watched an agent confidently mark something done that was not, this is a reasonable set of guardrails and it costs one command to try. Start with test-driven-development and verification-before-completion and ignore the rest for a week. Those two change behaviour the most.

If you are prototyping, skip it. The methodology is optimised for not shipping garbage, which is a different objective from finding out whether the idea works.

Three hundred thousand stars is not a verdict on the methodology. It is a verdict on the moment: a lot of people now have agents that can write code faster than they can supervise it, and they are looking for something that makes the supervision cheaper. Superpowers is one answer. The fact that it is made of Markdown is the most interesting part.