obra-superpowers-agentic-workflow

Provides coding agents with structured workflows enforcing TDD, planning, debugging, subagent-driven tasks, and isolated git worktrees for disciplined softwa...

Security Scan

The skill's instructions, required resources, and behavior are coherent with its stated purpose (agentic TDD/workflow orchestration); it does perform potentially destructive and networked operations that a user should review before allowing an agent to run them automatically.

Purpose & Capability

The README-like SKILL.md describes an agent workflow for TDD, planning, subagents, and git worktrees; the actions it instructs (creating branches/worktrees, running tests, running package setup) are consistent with that purpose and nothing requested is unrelated.

Instruction Scope

Instructions tell an agent to run repo-modifying commands (git worktree add/remove, create branches, commit, delete code when anti-patterns are detected), run project setup (npm/bundle installs), and execute tests. These are in-scope for a coding workflow but are destructive and involve running third-party package install scripts and network access — the user should expect the agent to modify the repository and run arbitrary build/install steps.

Install Mechanism

This is an instruction-only skill with no install spec or bundled code. The SKILL.md points users to platform marketplace commands and to GitHub raw URLs for platform-specific installs; that is expected for a cross-platform agent skill, but those external URLs will fetch remote content and should be verified by the user prior to following them.

Credentials

The skill does not declare or require any environment variables, credentials, or config paths. It does assume access to the developer's git repo and the ability to run local package managers and tests, which is proportional to its purpose but means no secret-access claims are hidden in the metadata.

Persistence & Privilege

The skill is not forced-always and does not request persistent system changes itself (no install spec). However, it expects the agent to run autonomously when invoked and to perform repository-modifying operations; autonomous invocation plus destructive git/file operations increases risk if allowed without human supervision.

Assessment

This skill appears to do what it claims: orchestrate TDD workflows, spawn subagents, create isolated git worktrees, run package installs, run tests, commit, and delete code in your repository. Before installing or enabling it: 1) only run it on repositories you can safely modify or in a disposable/feature worktree; 2) expect it to run package managers (npm, bundler) that may execute postinstall scripts and network requests — run in an environment you control; 3) review any external URLs (marketplace entries, raw.githubusercontent.com links) and only install from trusted marketplaces; 4) require manual checkpoints if you want to avoid automated destructive actions (merges, deletes); 5) if you need higher assurance, test the workflow in a sandbox clone of your repo and inspect any generated commits and commands the agent plans before allowing execution.

---
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