Superpowers Plugin Methodology: Autonomous AI Development with Composable Skills

Superpowers is a comprehensive software-development methodology that layers a library of composable skills and instructional hooks on top of AI coding agents to autonomously guide projects from initial concept to production-ready code.

The Superpowers plugin methodology is implemented in the openai/plugins repository as a deterministic framework for AI-powered coding agents. Unlike standard assistants that provide suggestions, this methodology enforces mandatory engineering practices through automated skill discovery and execution. The system operates via a plugin manifest, bootstrap hooks, and a structured workflow engine that governs every phase of development.

Core Architecture of the Superpowers Plugin Methodology

The methodology operates through five integrated components defined in the source code:

Plugin Manifest

The manifest declares the plugin’s capabilities, metadata, and skills library location. According to the source code, this is defined in plugins/superpowers/.codex-plugin/plugin.json, which exposes the plugin structure to host runtimes.

Skills Library

This component comprises markdown-based reference guides stored in plugins/superpowers/skills/. The library includes definitions for Test-Driven Development, systematic debugging, and brainstorming that agents discover and invoke automatically.

Bootstrap Hook

The bootstrap mechanism injects using-superpowers at session start and after compaction. This hook ensures all relevant skills load automatically without requiring manual user configuration or intervention.

Workflow Engine

The engine orchestrates a deterministic sequence of skill activations. As documented in the README’s "The Basic Workflow" section, the engine progresses from brainstorming to finishing a development branch, with each step enforcing specific checks and hand-offs before proceeding.

Sub-agent Execution

When the writing-plans skill decomposes work into tasks, the methodology dispatches fresh sub-agents for each unit. Each sub-agent undergoes a two-stage review process—spec compliance verification followed by code quality checks—before committing changes, as specified in skills/subagent-driven-development/SKILL.md.

How the Superpowers Plugin Methodology Works

The workflow consists of six mandatory phases that the agent executes autonomously:

1. Kick-off and Specification Extraction

When the agent detects build intent, it pauses to extract a concise specification by asking clarifying questions about the project goals. This phase ensures the agent understands what to build before writing any code.

2. Design Presentation

The agent presents the specification in short, readable chunks for explicit user approval. The methodology blocks further progress until the user validates the design direction.

3. Implementation Planning

Upon approval, the writing-plans skill breaks the work into bite-sized tasks (2-5 minutes each) with explicit file targets and verification steps. This creates a deterministic execution plan rather than ad-hoc coding.

4. Sub-agent-Driven Development

Each task spawns a sub-agent that follows the RED-GREEN-REFACTOR TDD loop defined in the skills library:

• RED: Write failing test
• GREEN: Implement minimal code to pass
• REFACTOR: Clean up and commit

This process adheres to the specifications in skills/subagent-driven-development/SKILL.md.

5. Code Review and Debugging

The requesting-code-review and systematic-debugging skills run automatically after implementation. These enforce the systematic debugging workflow documented in skills/systematic-debugging/SKILL.md to catch regressions before they reach the main branch.

6. Branch Finalization

The finishing-a-development-branch skill executes final verification steps. According to skills/finishing-a-development-branch/SKILL.md, this includes running the full test suite, presenting merge or PR options, and cleaning up temporary worktrees.

Key Principles Underlying the Methodology

The Superpowers plugin methodology enforces three non-negotiable engineering principles:

• Test-Driven Development: TDD foundations underlie every skill creation and task execution, requiring tests before implementation
• Systematic over ad-hoc: Each step follows prescribed processes defined in markdown skill files rather than improvisational coding
• Evidence over claims: Every claim of success requires verification via passing tests or explicit two-stage review

Practical Implementation Example

Below is a declarative example showing how developers invoke Superpowers in host environments like Claude Code or Codex CLI:

# 1️⃣ Install the plugin

/plugin install superpowers@claude-plugins-official

# 2️⃣ Provide a high-level requirement

You: "I need a CLI tool that converts CSV to JSON."

# 3️⃣ Agent runs the brainstorming skill

[Agent extracts specification and presents design for approval]

# 4️⃣ Approve the specification

You: "Sounds good, go ahead."

# 5️⃣ Agent triggers writing-plans and creates tasks

[Creates tasks: "Create src/main.ts", "Write failing test for CSV parsing"]

# 6️⃣ Sub-agents execute TDD loop

[RED: Write failing test → GREEN: Implement code → REFACTOR: Commit]

# 7️⃣ Agent runs finishing-a-development-branch skill

[Verifies test suite, offers PR creation, cleans up worktree]

The same flow applies across runtimes (Antigravity, Codex CLI, Gemini CLI) via respective marketplace commands, as the underlying methodology remains identical.

Summary

• The Superpowers plugin methodology is a deterministic framework for autonomous AI coding agents implemented in openai/plugins
• It utilizes a skills library of markdown-based guides located in plugins/superpowers/skills/ that agents invoke automatically
• The bootstrap hook loads capabilities at session start via using-superpowers without manual configuration
• Execution follows a mandatory six-phase workflow from specification extraction to branch finalization
• Sub-agents handle individual tasks through a two-stage review process and RED-GREEN-REFACTOR TDD cycles
• All operations require evidence-based verification through passing tests or explicit reviews

Frequently Asked Questions

What distinguishes Superpowers from standard AI coding assistants?

Standard assistants provide contextual suggestions without enforced structure, whereas the Superpowers plugin methodology mandates specific skill executions. The agent cannot proceed to implementation without successfully executing writing-plans, requesting-code-review, and other required skills, ensuring disciplined engineering practices rather than ad-hoc generation.

How does the sub-agent execution model maintain code quality?

When the writing-plans skill creates tasks, each unit dispatches a fresh sub-agent as defined in skills/subagent-driven-development/SKILL.md. Each sub-agent must pass a two-stage review—first verifying spec compliance, then code quality—before committing. This enforces the RED-GREEN-REFACTOR TDD loop at the task level.

Is the Superpowers plugin methodology compatible with different AI runtimes?

The methodology is runtime-agnostic. While hosted in the openai/plugins repository, it integrates with Claude Code, Codex CLI, Antigravity, and Gemini CLI through marketplace installations. The core plugin.json manifest and skills library remain identical across environments, ensuring consistent behavior.

Which files control the debugging and finalization workflows?

The systematic-debugging workflow is defined in skills/systematic-debugging/SKILL.md, while branch finalization is governed by skills/finishing-a-development-branch/SKILL.md. These files, along with the main plugins/superpowers/README.md, constitute the executable specifications that agents reference during the debugging and cleanup phases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}