obra/superpowers Agentic Skills Framework

---
name: obra-superpowers-agentic-workflow
description: Agentic skills framework for coding agents providing structured workflows for TDD, planning, debugging, and subagent-driven development
triggers:
  - "set up superpowers for my coding agent"
  - "install superpowers skills framework"
  - "use superpowers workflow"
  - "help me plan this feature with superpowers"
  - "set up agentic development workflow"
  - "configure coding agent skills"
  - "add superpowers to claude code"
  - "use subagent driven development"
---

# obra/superpowers Agentic Skills Framework

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Superpowers is a composable skills framework that gives coding agents (Claude Code, Cursor, Codex, OpenCode, Gemini CLI) structured workflows for software development. It enforces TDD, systematic debugging, design-first planning, and subagent-driven development — automatically, without manual prompting.

## What It Does

- **Auto-triggers skills** based on what you're doing (planning, debugging, implementing)
- **Enforces RED-GREEN-REFACTOR TDD** — writes failing tests first, always
- **Runs subagent-driven development** — spawns fresh subagents per task with two-stage review
- **Structures design before code** — Socratic brainstorming → spec → implementation plan → execution
- **Manages git worktrees** for parallel isolated development branches

## Installation

### Claude Code (Official Marketplace)

```bash
/plugin install superpowers@claude-plugins-official

Claude Code (via Custom Marketplace)

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Cursor

In Cursor Agent chat:

/add-plugin superpowers

Or search "superpowers" in the plugin marketplace UI.

Codex

Tell Codex in a session:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

OpenCode

Tell OpenCode in a session:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Gemini CLI

gemini extensions install https://github.com/obra/superpowers

Update later with:

gemini extensions update superpowers

Update Any Platform

/plugin update superpowers

Verify Installation

Start a new session and say:

help me plan this feature

The agent should automatically invoke the brainstorming skill without being asked.

---

Core Workflow (in order)

1. Brainstorming — Design Before Code

Triggers automatically when you describe something to build.

The agent will NOT write code immediately. Instead it:

1. Asks clarifying questions to extract a real spec
2. Presents the design in readable chunks for your approval
3. Only proceeds after you sign off

Example prompt:

I want to add rate limiting to my API

The agent will ask: What kind of rate limiting? Per user or per IP? What limits? What happens on exceed? etc.

---

2. using-git-worktrees — Isolated Workspace

Triggers after design approval.

Creates a new git branch + worktree so implementation is isolated:

# What the agent does internally:
git worktree add ../my-project-feature-branch -b feature/rate-limiting
cd ../my-project-feature-branch
# runs project setup (npm install, bundle install, etc.)
# verifies clean test baseline

---

3. writing-plans — Bite-Sized Task Plans

Triggers with approved design.

Produces a plan where every task includes:

• Exact file paths
• Complete code to write
• Verification steps (tests to run)
• 2–5 minute estimated scope

Example plan output structure:

## Task 1: Add RateLimiter class
- File: `src/middleware/rate_limiter.rb`
- Write failing test first: `spec/middleware/rate_limiter_spec.rb`
- Test: `bundle exec rspec spec/middleware/rate_limiter_spec.rb`
- Expected: RED (test fails, class doesn't exist)

## Task 2: Implement token bucket algorithm
- File: `src/middleware/rate_limiter.rb`
- Write minimal code to pass test
- Test: `bundle exec rspec spec/middleware/rate_limiter_spec.rb`
- Expected: GREEN

---

4. subagent-driven-development — Automated Execution

Triggers when you say "go" on the plan.

Dispatches a fresh subagent per task. Each task goes through two-stage review:

1. Spec compliance — did it follow the plan?
2. Code quality — is it clean, minimal, tested?

Critical review issues block forward progress.

Alternative: executing-plans runs tasks in batches with human checkpoints instead of subagents.

---

5. test-driven-development — RED-GREEN-REFACTOR

Triggers during any implementation task.

The strict cycle:

1. Write a failing test
2. Run it — confirm RED
3. Write MINIMAL code to pass
4. Run it — confirm GREEN
5. Refactor if needed
6. Commit
7. Repeat

Anti-pattern the agent will refuse:

• Writing code before tests
• Writing more code than needed to pass the test
• Skipping the "watch it fail" step

If code was written before tests, the agent deletes it and restarts with tests.

---

6. requesting-code-review

Triggers between tasks.

The agent reviews work against:

• The original plan spec
• Code quality standards
• Test coverage

Severity levels: critical (blocks) / major (should fix) / minor (optional)

---

7. finishing-a-development-branch

Triggers when all tasks complete.

Presents options:

• Merge to main
• Open a PR
• Keep branch for more work
• Discard branch

Then cleans up the worktree:

git worktree remove ../my-project-feature-branch

---

Skills Reference

Testing

Skill	What it does
test-driven-development	Enforces RED-GREEN-REFACTOR with anti-pattern detection

Debugging

Skill	What it does
systematic-debugging	4-phase root cause process
verification-before-completion	Confirms issue is actually fixed

Collaboration & Planning

Skill	What it does
brainstorming	Socratic design refinement before any code
writing-plans	Detailed task-by-task implementation plans
executing-plans	Batch execution with human checkpoints
dispatching-parallel-agents	Concurrent subagent workflows
requesting-code-review	Pre-merge review checklist
receiving-code-review	Structured response to review feedback
using-git-worktrees	Parallel isolated development branches
finishing-a-development-branch	Merge/PR/discard decision + cleanup
subagent-driven-development	Per-task subagents with two-stage review

Meta

Skill	What it does
writing-skills	Create new skills following best practices
using-superpowers	Introduction to the skills system

---

Writing a Custom Skill

Skills live in skills/<skill-name>/SKILL.md. To add one:

# Fork the repo, create a branch
git checkout -b skill/my-custom-skill

# Create skill directory
mkdir -p skills/my-custom-skill
touch skills/my-custom-skill/SKILL.md

Follow the writing-skills skill format. Frontmatter structure:

---
name: my-custom-skill
description: One line description
triggers:
  - "phrase that activates this skill"
  - "another trigger phrase"
---

Then submit a PR to obra/superpowers.

---

Common Patterns

Starting a new feature from scratch

You: I want to build a CSV export feature for my Rails app

Agent: [brainstorming skill activates]
Agent: Let me ask a few questions...
  1. What data should be exportable?
  2. Should exports be synchronous or background jobs?
  3. What format — standard CSV or with custom headers?

Resuming an existing plan

You: Let's continue the implementation plan

Agent: [executing-plans or subagent-driven-development activates]
Agent: Picking up at Task 3: Implement background job...

Debugging a failing test

You: This test keeps failing and I don't know why

Agent: [systematic-debugging skill activates]
Agent: Let's work through this systematically.
Phase 1: Reproduce reliably...

Parallel work on independent features

You: Can we work on the auth refactor and the new dashboard in parallel?

Agent: [dispatching-parallel-agents skill activates]
Agent: I'll set up two worktrees and dispatch subagents for each...

---

Philosophy & Guardrails

YAGNI — The agent will push back on scope creep. If it's not in the spec, it won't build it.

DRY — Duplication spotted in review will be flagged as major severity.

Complexity reduction — Simpler solution always preferred over clever solution.

Evidence over claims — The agent runs tests and shows output rather than claiming something works.

Tests first, always — No exceptions. Code written before tests gets deleted.

---

Troubleshooting

Skills not triggering automatically

• Start a new session after installation (skills load at session start)
• Verify install: ask "what superpowers skills do you have?"
• Re-run the install command for your platform

Agent skipping the brainstorming step

Say explicitly:

Before writing any code, use the brainstorming skill

Subagent tasks getting stuck in review loop

Critical review issues block progress by design. Tell the agent:

Show me the critical issues blocking Task N

Then decide: fix them or explicitly override with:

Accept the current implementation and continue to Task N+1

Worktree conflicts

# List active worktrees
git worktree list

# Remove a stuck worktree manually
git worktree remove --force ../project-branch-name
git branch -d feature/branch-name

Plugin update not applying

Restart your agent session after updating — skills are loaded at session initialization.

---

Resources

• Repository: https://github.com/obra/superpowers
• Blog post: https://blog.fsck.com/2025/10/09/superpowers-for-claude-code/
• Discord: https://discord.gg/Jd8Vphy9jq
• Issues: https://github.com/obra/superpowers/issues
• Marketplace: https://github.com/obra/superpowers-marketplace
• Sponsor: https://github.com/sponsors/obra