obra/superpowers: Packaging Software Engineering Methodology as Markdown Skills for AI Coding Agents

Forum topic · ✨步子哥 · 2026-08-04

Summary

obra/superpowers is a GitHub project that packages decades of software engineering methodology—TDD, YAGNI, DRY, brainstorming, spec writing, code review—into Markdown skills that AI coding agents can automatically trigger. Instead of telling an agent to 'write code,' Superpowers forces a structured workflow: brainstorming to clarify intent, segmented spec approval, implementation planning, subagent-driven development with fresh context per task, and automated spec-compliance plus quality review. The repository supports 11+ harnesses including Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot CLI, and others, demonstrating that methodology should be harness-agnostic. Its core innovation is the subagent-driven development pattern: dispatching a new subagent for each task keeps context clean and prevents context bleed, enabling autonomous multi-hour runs without deviation. The project, which gained 777 trending stars on 2026-08-04, treats methodology as executable infrastructure rather than documentation, showing how aligning methodology granularity with agent execution granularity turns implicit engineering knowledge into reusable, portable skills.

obra/superpowers: Packaging Software Engineering Methodology as Markdown Skills

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

The Counterintuitive Premise: Methodology Is Becoming "Code"

A 2026-era AI coding agent has an awkward habit: given a task, it immediately starts writing code. It is fast, but the output often ships without tests, design docs, task breakdowns, or review. It runs—until you change something, then it breaks.

This is not an agent flaw. It is a methodology gap. Human engineers spent half a century distilling TDD, YAGNI, DRY, code review, and spec-first practices. These are not decorations; they are the infrastructure that lets code evolve. Agents do not know them, because training data contains far more *writing code* than *how to write code*.

obra/superpowers takes a different approach: package methodology as Markdown skills that agents trigger automatically. Not documentation. Not prompt templates. *Methodology as code* that an agent can recognize and execute.

Core Workflow: From "Just Write Code" to "Think First, Then Write"

Superpowers' workflow begins the moment an agent starts:

1. Brainstorming — When the agent sees you want to build something, it does not write code. It asks: *what are you actually trying to do?* Through multi-turn dialogue, vague intent becomes a sharp spec.

2. Segmented Spec Review — The design document is split into digestible chunks, shown one at a time. Each chunk waits for your sign-off before continuing. No 50-page document dumps.

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 project: a plan must be executable even by someone with none of the qualities a senior engineer would have.

4. Subagent-Driven Development — The core innovation. After you say "go," the agent does not grind through tasks itself. Each task is dispatched to a fresh subagent. When it returns, the main agent runs spec-compliance and code-quality review. Only on pass does the next task start. "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 as skills: tests before code, nothing built that is not needed, and repetition abstracted away.

Key Insight: Methodology as Executable Skill

The most interesting design choice in Superpowers is not any specific skill—it is the automatic-trigger mechanism. You do not tell the agent "now brainstorm." It sees you building something and enters brainstorming. You do not say "now write tests." The TDD skill auto-fires.

This shares a structural philosophy with other skill-file approaches: alignment does not always require retraining; sometimes a skill file is enough. The difference is direction—one constrains output style, Superpowers constrains engineering process.

Through the lens of granularity alignment, Superpowers does this: align the granularity of methodology with the granularity of agent execution. Human methodology is "think before you code"—granularity is one conversation. Agent methodology is "dispatch a brainstorming subagent before each subtask"—granularity is one subagent call. Once the granularities align, methodology actually executes.

11+ Harnesses: Cross-Platform Methodology

Superpowers' 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 not coincidence. Methodology should not be bound to any specific agent. TDD does not change because you switched from Claude Code to Cursor. Superpowers abstracts methodology into Markdown skills; each harness loads them its own way, but the skill content is identical.

This echoes a broader research-skill distillation principle: methodology is a distillinable, portable, reusable asset. One project distills "how to do research and write articles"; Superpowers distills "how to write code." Both turn tacit knowledge into explicit skill.

Subagent-Driven Development: Why "Send a New Hire" Beats "Do It Yourself"

The most counterintuitive design in Superpowers: dispatch a fresh subagent for every task, even when one strong agent could do it all.

The reason is fresh context.

After two hours, the main agent's context is full of details, decisions, and code snippets from every prior task. Judgement on the next task gets polluted—*context bleed*. Dispatch a new subagent, give it clean context and a tight spec, and it executes unclouded.

This mirrors the same principle behind RPI (Research-Plan-Implement) context compression: each stage independently compresses context, keeping utilization at 40–60%. Superpowers pushes this to the limit—every task is a brand-new context.

From a division-of-labor view: Superpowers splits *planning* and *execution* across agents. The main agent plans and reviews; subagents execute. Each role stays focused.

By the Numbers

Supported harnesses: 11+ AI coding clients (Claude Code, Cursor, Codex, Gemini CLI, Copilot CLI, and others)
Trending stars: 777 (2026-08-04)
Core skills: brainstorming, spec, planning, subagent-driven-development, TDD, code review
Auto-trigger: skills activate from context, no manual invocation
Commercial offering: Primeradiant provides enterprise support

Lessons for Agent Developers

1. Methodology is a skill, not a document. A Markdown skill an agent auto-triggers outperforms a "please follow these guidelines" doc by an order of magnitude. 2. Subagent = fresh context. Dispatch a new subagent per task to prevent context bleed. Granularity alignment applied at the execution layer. 3. Methodology is harness-agnostic. TDD does not belong to Claude Code. Abstract methodology into portable skills—write once, run on every platform. 4. Specs must be clear enough for a junior engineer to follow. This is not an insult to the agent; it is an honest acknowledgment that, like a junior engineer, the agent needs explicit instruction.

---

One-line summary: obra/superpowers packages half a century of software engineering methodology into Markdown skills, letting agents auto-trigger the full flow—brainstorming → spec → plan → subagent → review. It does not teach the agent to write code; it teaches the agent *how* to write code.

> Repository: https://github.com/obra/superpowers > Subagent-Driven Development skill: https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md