obra/superpowers: Packaging Software Development Methodology as Markdown

> Original: https://github.com/obra/superpowers

A Counterintuitive Fact: Methodology Is Becoming "Code"

AI coding agents in 2026 have an awkward habit: give them a task and they immediately start writing code. Fast, yes—but the output often lacks tests, design docs, task decomposition, and review. It runs, but breaks the moment you change it.

This isn't an agent problem—it's a missing methodology problem. Human engineers spent half a century distilling TDD, YAGNI, DRY, code review, and spec-first design. These aren't decorations; they're the 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 takes the approach of packaging methodology into Markdown skills that agents trigger automatically. Not documentation, not prompt templates—"methodology code" that agents can recognize and execute.

Core Workflow: From "Code Immediately" to "Think First"

The Superpowers workflow starts the moment the agent boots:

1. Brainstorming — Instead of coding right away, the agent asks: "What are you actually trying to build?" Multiple rounds of dialogue turn vague requirements into a clear spec.

2. Spec in Segments — The design doc is split into digestible chunks, shown one at a time for sign-off. No 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 most precise line in the original text.

4. Subagent-Driven Development — The most core innovation. After you say "go," the agent doesn't grind through everything itself: each task is dispatched to a fresh subagent, then the main agent checks spec compliance and reviews code quality before moving on. "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: write tests first, don't build what you don't need, extract duplication.

Key Insight: Methodology as "Executable Skills"

The most interesting design isn't any single skill—it's the automatic triggering mechanism. You don't tell the agent "now brainstorm"; it sees you're building something and enters brainstorming. You don't say "write tests"; the TDD skill fires automatically.

This mirrors the philosophy behind i-have-adhd: alignment doesn't always require retraining a model—sometimes one skill file suffices. The directions differ: i-have-adhd constrains output style; Superpowers constrains engineering process.

From a "granularity isomorphism" perspective, Superpowers aligns methodology granularity to agent execution granularity. Human methodology is "think before coding"—granularity: one conversation. Agent methodology: "dispatch a brainstorming subagent before each subtask"—granularity: one subagent call. When granularity aligns, methodology actually gets executed.

11+ Harnesses: Making Methodology Cross-Platform

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.

Not by 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.

This parallels cangjie-skill's "methodology distillation": methodology is a distillable, transferable, reusable asset. cangjie distills "how to do research/write articles"; Superpowers distills "how to write code." Both turn tacit knowledge into explicit skills.

Subagent-Driven Development: Why "Sending New People" Beats "Doing It Yourself"

Counterintuitive: intuitively one strong agent doing everything is most efficient. But Superpowers dispatches a new subagent for every task.

Why? Fresh context.

After two hours, the main agent's context is stuffed with details, decisions, and code from prior tasks. Its judgment on the next task gets polluted—"context bleed." A fresh subagent with clean context and a clear task spec isn't contaminated.

This is the same principle as ACE's RPI (Research-Plan-Implement) three-step context compression: compress context independently per stage, keep utilization at 40–60%. Superpowers pushes it to the extreme—every task gets a brand-new context.

By the principle that "division of labor beats unification": Superpowers splits planning and execution across agents—main agent plans and reviews, subagents execute. Each role stays focused.

The Numbers

• Supported harnesses: 11+ AI coding clients (Claude Code, Cursor, Codex, Gemini CLI, Copilot CLI, etc.)
• Stars: 777 (trending on 2026-08-04)
• Core skills: brainstorming, spec, planning, subagent-driven-development, TDD, code review, etc.
• Auto-triggering: no manual invocation; skills activate based on context
• Commercial version: enterprise support via Primeradiant

Takeaways for Agent Developers

1. Methodology is a skill, not a doc: Markdown skills that auto-trigger are 10x more effective than "please follow these guidelines" documents. 2. Subagent = fresh context: dispatch a new subagent per task to avoid context bleed—granularity isomorphism applied at the execution layer. 3. Methodology is cross-harness: TDD isn't bound to Claude Code; extract it into transferable skills for one investment, multi-platform returns. 4. Specs must be clear enough for a "junior engineer to execute": not an insult to agents—just admitting they, like junior engineers, need explicit instructions.

---

One-line summary: obra/superpowers packages half a century of software engineering methodology into Markdown skills that let agents auto-trigger the full brainstorm → spec → plan → subagent → review pipeline. It doesn't teach agents to write code—it teaches agents how to write code.

> Repo: obra/superpowers > Subagent-Driven Development skill: SKILL.md