obra/superpowers: Packaging Software Development Methodology into Markdown Skills for AI Agents
> Source: https://github.com/obra/superpowers
A Counterintuitive Fact: Methodology Is Becoming "Code"
AI coding agents in 2026 share an awkward pattern: give them a task and they immediately start writing code. Fast—but the output often has no tests, no design docs, no task decomposition, no review. It runs, but breaks the moment you change it.
This is not an agent problem; it's a missing methodology problem. Human engineers spent half a century distilling TDD, YAGNI, DRY, code review, and spec-first development. These aren't decorations—they're infrastructure that lets code evolve. Agents don't know them because their training data contains far more "writing code" than "how to write code."
obra/superpowers packages methodology into Markdown skills that agents automatically trigger. Not documentation, not prompt templates—"methodology code" that agents can recognize and execute.
Core Workflow: From "Code Immediately" to "Think First"
The workflow starts the moment the agent boots:
1. Brainstorming — Instead of writing code right away, the agent asks what you actually want to build, turning vague requirements into a clear spec through multi-turn dialogue.
2. Spec shown in segments — The design doc is split into digestible chunks, presented one at a time for your sign-off. Not a 50-page dump.
3. Implementation Plan — "Clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow." The sharpest line in the original docs: a plan must be executable by someone with no taste, no judgment, no context, and no love of testing.
4. Subagent-Driven Development — The project's core innovation. After you say "go," the main agent dispatches a new subagent per task, then runs spec-compliance checks plus code-quality review before moving on. Per the docs, it's "not uncommon for your agent to work autonomously for a couple hours at a time without deviating from the plan."
5. TDD + YAGNI + DRY — Three iron rules enforced via skills: tests first, write only what's needed, extract duplication.
Key Insight: Methodology as Executable Skills
The most interesting design isn't any single skill but the automatic triggering mechanism. You never say "now brainstorm"—the agent sees you're building something and enters brainstorming. You never say "now write tests"—the TDD skill fires on its own.
Viewed through a "granularity isomorphism" lens: Superpowers aligns the granularity of methodology with the granularity of agent execution. Human methodology says "think before coding" at the granularity of a conversation; agent methodology says "dispatch a brainstorming subagent before each subtask" at the granularity of a subagent call. When granularity aligns, methodology actually executes.
Unified Across 11+ Harnesses: Cross-Platform Methodology
The supported-harness list reads like a 2026 AI coding-tool roll call: Claude Code, Antigravity, Codex App, Codex CLI, Cursor, Factory Droid, Gemini CLI, GitHub Copilot CLI, Kimi Code, OpenCode, Pi.
This is no accident. Methodology shouldn't be bound to a specific agent—TDD doesn't change whether you use Claude Code or Cursor. Superpowers extracts methodology into Markdown skills; each harness loads them its own way, but the skill content is identical.
Subagent-Driven Development: Why "Sending in Fresh Hires" Beats "Doing It Yourself"
Intuition says a strong agent doing everything itself is most efficient. Superpowers instead dispatches a new subagent per task—because of fresh context.
After two hours, the main agent's context is stuffed with details, decisions, and code from earlier tasks. Its judgment on the next task gets contaminated—"context bleed." A new subagent gets clean context plus a precise task spec, and stays uncontaminated. Superpowers also separates planning from execution: the main agent plans and reviews; subagents implement.
By the Numbers
- Supported harnesses: 11+ AI coding clients (Claude Code, Cursor, Codex, Gemini CLI, Copilot CLI, etc.)
- Stars: 777 (trending, 2026-08-04)
- Core skills: brainstorming, spec, planning, subagent-driven-development, TDD, code review, and more
- Triggering: fully automatic based on context, no manual invocation
- Commercial edition: enterprise support via Primeradiant
Takeaways for Agent Developers
1. Methodology is a skill, not documentation: Markdown skills that auto-trigger beat "please follow these rules" docs by an order of magnitude. 2. Subagent = fresh context: one new subagent per task avoids context bleed. 3. Methodology is harness-agnostic: extract it into portable skills—one investment, multi-platform returns. 4. Specs must be clear enough for a junior engineer: not an insult to agents—it's acknowledging they, like junior engineers, need explicit instructions.
---
One-line summary: obra/superpowers packages half a century of software engineering methodology into Markdown skills, letting agents automatically run brainstorming → spec → plan → subagent → review. It doesn't teach agents to write code—it teaches agents *how* to write code.
> Repo: obra/superpowers > Subagent-Driven Development skill: SKILL.md