superpowers-droid

structured agentic workflows for Factory Droid. fork of obra/superpowers.

install

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/yigitkonur/superpowers-droid/main/install.sh)"

or with flags:

npx superpowers-droid install --user       # all sessions
npx superpowers-droid install --project    # this project only
npx superpowers-droid uninstall --user
npx superpowers-droid status

the installer uses droid's native plugin system when available (droid plugin install), falls back to git clone + AGENTS.md injection. safe to re-run.

installation guide →

what this is

superpowers is a skill-based development workflow by @obra. 14 composable skills enforce design-before-code, TDD, two-stage review, and evidence-based verification. the original targets Claude Code.

this fork ports everything to Factory Droid, replacing tool names and adding droid-native capabilities:

claude code                          factory droid
───────────                          ─────────────
Bash                             →   Execute
Write                            →   Create
WebFetch                         →   FetchUrl
Task (subagent)                  →   Task (same)
CLAUDE.md                        →   AGENTS.md
1 generic agent                  →   5 tool-restricted droids
no reasoning control             →   reasoningEffort: high/medium
manual git worktree              →   droid --worktree
no subagent completion hook      →   SubagentStop hook
gh pr create                     →   Create-PR tool

why this fork →

how it works

skills auto-activate when your task matches their description. you don't invoke them — droid checks before every response.

user: "build a login page"
     │
     ▼
 brainstorming ──→ questions, alternatives, spec doc
     │
     ▼
 writing-plans ──→ 2-5 min tasks with file paths
     │
     ▼
 using-git-worktrees ──→ droid --worktree login
     │
     ▼
 subagent-driven-development
     │
     ├──→ implementer droid ──→ builds, tests, commits
     │         │
     │    spec-reviewer droid ──→ "matches spec?" (read-only)
     │         │
     │    code-quality-reviewer ──→ "well built?" (read-only)
     │
     ▼
 finishing-a-development-branch ──→ Create-PR

architecture →

vs native droid

droid ships with a Task tool for dispatching sub-agents. superpowers adds the workflow on top:

| | native Task only | with superpowers | |---|---|---| | design phase | none | socratic brainstorming → spec | | task granularity | "build the feature" | 2-5 minute steps | | review | optional, full-access | mandatory, two-stage, read-only | | test discipline | suggested | enforced RED-GREEN-REFACTOR | | completion claims | trust the agent | evidence required (fresh test run) | | debugging | guess and retry | 4-phase root cause investigation |

full comparison →

skills

14 composable skills, auto-activating:

| skill | when | what | |---|---|---| | brainstorming | creative work | socratic design → spec document | | writing-plans | spec approved | 2-5 min tasks with exact paths | | using-git-worktrees | plan ready | droid --worktree isolation | | subagent-driven-development | plan ready | fresh droid per task + two-stage review | | executing-plans | plan ready (alt) | single-session with checkpoints | | test-driven-development | implementation | RED → GREEN → REFACTOR | | systematic-debugging | bug found | 4-phase root cause analysis | | requesting-code-review | task complete | dispatch reviewer droid | | receiving-code-review | PR feedback | rigorous technical response | | verification-before-completion | claiming "done" | evidence before assertions | | finishing-a-development-branch | all tasks done | merge / PR / keep / discard | | dispatching-parallel-agents | 2+ independent tasks | concurrent droid dispatch | | writing-skills | creating skills | TDD for documentation | | using-superpowers | every session | routing layer |

skills reference →

droids

5 tool-restricted agent definitions — reviewers cannot modify code:

| droid | tools | reasoning | role | |---|---|---|---| | implementer | full | medium | builds tasks, writes tests, commits | | spec-reviewer | read-only | high | does the code match the spec? | | code-quality-reviewer | read-only | high | is it well-built? | | code-reviewer | read-only | high | final review against plan | | plan-reviewer | read-only | high | is the plan feasible? |

tools: read-only restricts to Read, Grep, Glob, LS only.

droids reference →

iron laws

1. no production code without a failing test first
2. no fixes without root cause investigation
3. no "done" without running verification fresh

known limitations

two upstream primitives have no droid equivalent:

| missing | impact | workaround | |---|---|---| | Skill tool | can't invoke skills by tool name | auto-activation by description. browse with /skills. | | EnterPlanMode | no dedicated plan-mode UI | brainstorming skill triggers automatically |

everything else maps 1:1. see architecture → for the full table.

docs

| doc | content | |---|---| | 01-why-this-fork | motivation, changelog | | 02-architecture | system design, tool mapping, file layout | | 03-skills-reference | all 14 skills with triggers | | 04-droids-reference | all 5 droids with frontmatter | | 05-vs-native-subagents | superpowers vs raw Task tool | | 06-installation | install, uninstall, configuration |

also available for

• superpowers-codex — same 14 skills for OpenAI Codex CLI
• obra/superpowers — the original, for Claude Code

credits

built on superpowers by @obra (Jesse Vincent). MIT license.