Superpowers: Inside the Agentic Skills Framework and Subagent TDD Methodology

As autonomous coding agents have evolved from research experiments into daily developer tooling, engineering teams have encountered a consistent failure mode: left to themselves, large language models tend to jump directly into code generation, skip architectural clarification, produce untested abstractions, and drift from project context during extended autonomous runs.

Created by open-source systems engineer Jesse Vincent (founder of Best Practical, creator of Request Tracker, and maintainer of K-9 Mail), Superpowers has emerged as a standardized software development methodology for coding agents. With more than 283,000 GitHub stars and cross-harness support for Claude Code, Cursor, Codex, OpenCode, Hermes Agent, and Antigravity, the framework replaces unguided generation with structured engineering discipline.

The Architectural Pillars of Superpowers

Superpowers operates on a fundamental observation: coding agents fail not because they lack syntax comprehension, but because they lack execution guardrails. The framework implements these guardrails through composable skills stored in .agents/skills/ or environment-specific plugin manifests.

1. Conversational Intent Teasing

When an unconstrained agent receives a prompt such as “add user authentication,” it frequently implements hundreds of lines of boilerplate code using arbitrary databases and token libraries.

Superpowers forces the agent to step back. Through skills such as brainstorming and interview-me, the agent interrogates the developer:

• What is the authentication provider (OAuth, passkeys, sessions)?
• What security posture is required (rate limiting, MFA, audit logs)?
• What existing database models and abstractions should be reused?

The agent refuses to generate implementation code until the developer explicitly approves a short, structured specification document.

2. Guarded Implementation Plans

Once the design is locked, the agent generates an implementation plan structured for an execution worker that has zero initial context. Every plan is split into micro-tasks containing:

• Exact file paths to create or modify.
• Precise test commands with expected outputs.
• Concrete functional requirements without speculative abstractions.

By eliminating ambiguity before execution begins, the agent prevents “context hallucination” where assumptions made early in a run compound into architectural failure hours later.

3. Strict Test-Driven Development (TDD)

Superpowers bans post-hoc testing, where an agent writes production code first and then crafts tests that merely mirror its implementation errors.

The methodology enforces a rigid sequence:

• Red Phase: The worker writes a unit or integration test describing the desired behavior. It executes the test suite and confirms that the test fails for the expected reason.
• Green Phase: The worker implements the minimal amount of application code required to make the test pass.
• Refactor Phase: The code is cleaned and structured without altering existing test assertions.
• Anti-Weakening Rule: Under no circumstances is an agent permitted to delete, skip, or loosen an assertion to make a suite pass. A failing test is treated as authoritative proof of an application defect.

4. Workspace Isolation via Git Worktrees

Running multi-step autonomous workflows in a developer’s primary working tree creates severe risks: uncommitted user edits can be overwritten, and failed experiments leave the tree in a dirty state.

Superpowers uses native git worktree functionality. Before beginning multi-step changes, the agent provisions an isolated worktree in a sibling directory. All compilation, intermediate commits, and test executions occur inside this bubble. Only after the entire suite passes and code reviews complete is the branch integrated back into the active tree.

5. Fresh-Context Subagent Reviews

Context window exhaustion is a primary driver of agent errors. When a single model session accumulates tens of thousands of tokens of debugging logs and error stack traces, its reasoning capacity degrades.

Superpowers mitigates this through subagent-driven-development. The parent coordinator dispatches isolated subagent sessions for each engineering task. When a subagent claims completion, a separate review subagent with a pristine, unpolluted context window audits the git diff against the original spec. If flaws are detected, feedback is returned to the worker before the coordinator advances to the next step.

Skill Definition and Harness Portability

A hallmark of Superpowers is its declarative skill architecture. Each capability is defined as an independent directory containing a SKILL.md specification with YAML frontmatter:

---
name: test-driven-development
description: Drives development with tests. Use when implementing any logic, fixing any bug, or changing any behavior.
---

# Test-Driven Development

1. Write failing test first.
2. Verify test failure.
3. Write minimal code to pass.
4. Verify test pass.
5. Refactor cleanly.

Because this format follows the open agent skill specification, Superpowers functions identically across diverse agent runtimes:

• Claude Code: Invoked via native .claude-plugin hooks, helping developers maintain velocity within tightened subscription rate limits.
• Cursor: Ingested through .cursor-plugin and system rule files.
• Hermes Agent: Native skill resolution via .hermes-plugin.
• Codex & OpenCode: Parsed directly through .agents/skills indexing, and complementing persistent desktop orchestrators like OpenClaw and AST analyzers like Graphify.

Practical Example: A Superpowers Engineering Session

To illustrate the methodology in practice, consider an agent tasked with adding an exponential backoff retry mechanism to an HTTP client:

# The agent creates an isolated worktree branch:
git worktree add -b feature/retry-backoff .worktrees/retry-backoff main

# Red Phase: The subagent writes the failing test
npm test -- test/http-client.test.ts
# Result: FAIL - Expected retry count 3, received 1

# Green Phase: The subagent implements backoff logic in src/http-client.ts
npm test -- test/http-client.test.ts
# Result: PASS - 4 tests passed (12ms)

# Verification Gate: Verification subagent reviews diff
# Confirms zero regressions, no mock leaks, full branch coverage

The entire cycle executes without human intervention, yet adheres strictly to the team’s testing conventions.

Trade-offs and Operational Realities

Adopting Superpowers introduces specific trade-offs:

• Higher Token Overhead: Requiring conversational specification clarification, formal implementation plans, and independent review subagents consumes significantly more tokens than simple prompt-and-code generation.
• Slower Initial Velocity: Developers seeking a quick one-line script may find the mandatory design interview and planning gates heavy for trivial tasks.
• Tooling Dependencies: The framework requires projects to have reliable, deterministic automated test suites. In codebases without test runners, the TDD phase cannot execute without first establishing test harnesses.

Despite these overheads, for production software engineering where correctness, security, and architectural durability outweigh raw speed, Superpowers provides the structured engineering discipline autonomous agents have long lacked.

Sources

• GitHub Repository: obra/superpowers
• Superpowers Release Notes and Changelog
• Agent Skills Open Specification
• Martin Fowler: Test-Driven Development Guide