Superpowers

Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them.

It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it doesn't just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do.

Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.

After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.

Next up, once you say "go", it launches a subagent-driven-development process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.

Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superpowers skill.

• brainstorming - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
• using-git-worktrees - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
• writing-plans - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
• subagent-driven-development / executing-plans - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
• test-driven-development - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
• requesting-code-review - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
• finishing-a-development-branch - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.

This document describes how to test Superpowers skills, particularly the integration tests for complex skills like subagent-driven-development.

Testing skills that involve subagents, workflows, and complex interactions requires running actual Claude Code sessions in headless mode and verifying their behavior through session transcripts.

Test Structure:

tests/
├── claude-code/
│   ├── test-helpers.sh         # Shared test utilities
│   ├── test-subagent-driven-development-integration.sh
│   ├── analyze-token-usage.py  # Token analysis tool
│   └── run-skill-tests.sh      # Test runner

Integration tests execute real Claude Code sessions with actual skills.

# Run the subagent-driven-development integration test
cd tests/claude-code
./test-subagent-driven-development-integration.sh

Note: Integration tests can take 10-30 minutes as they execute real implementation plans with multiple subagents.

Requirements:

• Must run from the superpowers plugin directory (not from temp directories)
• Claude Code must be installed and available as claude command
• Local dev marketplace must be enabled: "superpowers@superpowers-dev": true in ~/.claude/settings.json

What the integration test verifies:

• Plan Loading: Reads the plan once at the beginning
• Full Task Text: Provides complete task descriptions to subagents (doesn't make them read files)
• Self-Review: Ensures subagents perform self-review before reporting
• Review Order: Runs spec compliance review before code quality review
• Review Loops: Uses review loops when issues are found
• Independent Verification: Spec reviewer reads code independently, doesn't trust implementer reports

tests/
├── claude-code/
│   ├── test-helpers.sh         # 共享测试工具
│   ├── test-subagent-driven-development-integration.sh
│   ├── analyze-token-usage.py  # Token 分析工具
│   └── run-skill-tests.sh      # 测试运行器

# 运行 subagent-driven-development 集成测试
cd tests/claude-code
./test-subagent-driven-development-integration.sh

Guide for using Superpowers with OpenAI Codex via native skill discovery.

Windows (PowerShell) — Use a junction instead of a symlink:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

Codex has native skill discovery — it scans ~/.agents/skills/ at startup, parses SKILL.md frontmatter, and loads skills on demand.

Skills are discovered automatically. Codex activates them when:

• You mention a skill by name (e.g., "use brainstorming")
• The task matches a skill's description
• The using-superpowers skill directs Codex to use one

Create your own skills:

mkdir -p ~/.agents/skills/my-skill
# Create ~/.agents/skills/my-skill/SKILL.md:
---
name: my-skill
description: Use when [condition] - [what it does]
---
# My Skill
[Your skill content here]

Update skills:

cd ~/.codex/superpowers && git pull

Skills update instantly through the symlink.

Uninstall:

rm ~/.agents/skills/superpowers

Troubleshooting:

• Verify the symlink: ls -la ~/.agents/skills/superpowers
• Check skills exist: ls ~/.codex/superpowers/skills
• Restart Codex — skills are discovered at startup

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"

mkdir -p ~/.agents/skills/my-skill
# 创建 ~/.agents/skills/my-skill/SKILL.md:
---
name: my-skill
description: Use when [condition] - [what it does]
---
# My Skill
[Your skill content here]

cd ~/.codex/superpowers && git pull

rm ~/.agents/skills/superpowers

Complete guide for using Superpowers with OpenCode.ai.

The plugin does two things:

• Injects bootstrap context via the experimental.chat.system.transform hook, adding superpowers awareness to every conversation.
• Registers the skills directory via the config hook, so OpenCode discovers all superpowers skills without symlinks or manual config.

Skills written for Claude Code are automatically adapted for OpenCode:

• TodoWrite → todowrite
• Task with subagents → OpenCode's @mention system
• Skill tool → OpenCode's native skill tool
• File operations → Native OpenCode tools

Troubleshooting:

• Check OpenCode logs: opencode run --print-logs "hello" 2>&1 | grep -i superpowers
• Verify the plugin line in your opencode.json is correct
• Make sure you're running a recent version of OpenCode
• Use OpenCode's skill tool to list available skills
• Check that the plugin is loading
• Each skill needs a SKILL.md file with valid YAML frontmatter
• Check OpenCode version supports experimental.chat.system.transform hook
• Restart OpenCode after config changes

Superpowers is built by Jesse Vincent and the folks at Prime Radiant.

• Discord: Join us for community support, questions, and sharing what you're building
• Issues: GitHub Issues
• Release announcements: Sign up to get notified about new versions
• Blog post: Superpowers for Claude Code

If Superpowers has helped you do stuff that makes money and you are so inclined, I'd greatly appreciate it if you'd consider sponsoring my open source work.

Skills live directly in this repository. To contribute:

1. Fork the repository
2. Create a branch for your skill
3. Follow the writing-skills skill for creating and testing new skills
4. Submit a PR

See skills/writing-skills/SKILL.md for the complete guide.