Skip to content

Commit c35c5f6

Browse files
committed
Update README to be a little more human-written (and mention github sponsors)
1 parent 9a01a0d commit c35c5f6

File tree

1 file changed

+34
-23
lines changed

1 file changed

+34
-23
lines changed

README.md

Lines changed: 34 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,28 @@
11
# Superpowers
22

3-
AI agents skip steps under time pressure. They bypass best practices when confident. They lack consistency across tasks. The result: bugs you didn't catch, designs you didn't validate, tests you didn't write.
3+
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.
44

5-
**Superpowers fixes this.** Skills are mandatory instruction documents agents must follow. When a relevant skill exists, the agent checks for it, uses it, or fails the task.
5+
## How it works
66

7-
## How It Works
7+
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.
88

9-
At session start, the agent learns which skills exist. Before any task, the agent checks: "Does a skill match this work?" If yes, the agent loads and follows that skill.
9+
Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.
1010

11-
Skills are markdown files with proven workflows. The `test-driven-development` skill forces RED-GREEN-REFACTOR. No test-first? Delete the code and start over. The skill prevents rationalization.
11+
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.
1212

13-
## The Workflow
13+
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.
1414

15-
**When you ask to build a feature:**
15+
There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.
1616

17-
1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
18-
19-
2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
2017

21-
3. **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.
18+
## Sponsorship
2219

23-
4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task (same session, fast iteration) or executes in batches (parallel session, human checkpoints).
24-
25-
5. **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.
20+
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 opensource work](https://github.com/sponsors/obra).
2621

27-
6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
22+
Thanks!
2823

29-
7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
24+
- Jesse
3025

31-
**The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.
3226

3327
## Installation
3428

@@ -83,22 +77,40 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
8377

8478
**Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md)
8579

80+
## The Basic Workflow
81+
82+
1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
83+
84+
2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
85+
86+
3. **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.
87+
88+
4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task (same session, fast iteration) or executes in batches (parallel session, human checkpoints).
89+
90+
5. **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.
91+
92+
6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
93+
94+
7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
95+
96+
**The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.
97+
8698
## What's Inside
8799

88100
### Skills Library
89101

90-
**Testing** (`skills/testing/`)
102+
**Testing**
91103
- **test-driven-development** - RED-GREEN-REFACTOR cycle
92104
- **condition-based-waiting** - Async test patterns
93105
- **testing-anti-patterns** - Common pitfalls to avoid
94106

95-
**Debugging** (`skills/debugging/`)
107+
**Debugging**
96108
- **systematic-debugging** - 4-phase root cause process
97109
- **root-cause-tracing** - Find the real problem
98110
- **verification-before-completion** - Ensure it's actually fixed
99111
- **defense-in-depth** - Multiple validation layers
100112

101-
**Collaboration** (`skills/collaboration/`)
113+
**Collaboration**
102114
- **brainstorming** - Socratic design refinement
103115
- **writing-plans** - Detailed implementation plans
104116
- **executing-plans** - Batch execution with checkpoints
@@ -109,9 +121,8 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
109121
- **finishing-a-development-branch** - Merge/PR decision workflow
110122
- **subagent-driven-development** - Fast iteration with quality gates
111123

112-
**Meta** (`skills/meta/`)
124+
**Meta**
113125
- **writing-skills** - Create new skills following best practices
114-
- **sharing-skills** - Contribute skills back via branch and PR
115126
- **testing-skills-with-subagents** - Validate skill quality
116127
- **using-superpowers** - Introduction to the skills system
117128

@@ -134,7 +145,7 @@ Skills live directly in this repository. To contribute:
134145
4. Use the `testing-skills-with-subagents` skill to validate quality
135146
5. Submit a PR
136147

137-
See `skills/meta/writing-skills/SKILL.md` for the complete guide.
148+
See `skills/writing-skills/SKILL.md` for the complete guide.
138149

139150
## Updating
140151

0 commit comments

Comments
 (0)