The agent checks for relevant skills before any task. If there is even a 1% chance a skill applies, the agent invokes it. This is not optional behavior.
The seven-step loop
Brainstorming
Before writing a single line of code, the agent explores the project context, asks clarifying questions one at a time, proposes 2–3 approaches with trade-offs, and presents a design in sections for your approval. A design document is saved to
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and committed. Implementation is blocked until you approve the spec.Learn more about brainstorming →Creating a worktree
After design approval, the agent creates an isolated git worktree on a new branch using the
using-git-worktrees skill. This prevents any implementation from touching main or master. The worktree is verified to have a clean, passing test baseline before work begins.Writing a plan
With an approved spec and a clean worktree, the agent writes a detailed implementation plan: exact file paths, complete code, TDD steps, verification commands, and commit instructions for every task. Tasks are 2–5 minutes each. No placeholders, no “TBDs”. The plan is saved to
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md.Learn more about writing plans →Executing the plan
You choose how tasks are executed: subagent-driven (recommended) or inline. Subagent-driven dispatches a fresh subagent per task with isolated context and automatic two-stage review after each one. Inline execution runs tasks in sequence with human-in-the-loop checkpoints.Learn more about executing plans →
Test-driven development
During execution, the
test-driven-development skill enforces strict RED-GREEN-REFACTOR: write the failing test, watch it fail, write minimal code to pass, watch it pass, commit. Code written before a failing test is deleted. This happens for every task in the plan.Code review between tasks
After each task, the
requesting-code-review skill runs a review against the plan and reports issues by severity. In subagent-driven mode, this is a two-stage review: spec compliance first (did the implementation match the plan?), then code quality (is it well-built?). Critical issues block the next task.Finishing the branch
When all tasks are complete, the
finishing-a-development-branch skill verifies the full test suite, runs a final code reviewer subagent over the entire implementation, and presents exactly four options: merge locally, push and create a PR, keep the branch as-is, or discard. The worktree is cleaned up automatically for merge and discard.Learn more about finishing a branch →Skill priority hierarchy
When skills conflict with other instructions, this order applies:| Priority | Source | Example |
|---|---|---|
| 1 (highest) | User’s explicit instructions | CLAUDE.md, AGENTS.md, direct requests |
| 2 | Superpowers skills | brainstorming, writing-plans, TDD |
| 3 (lowest) | Default system prompt | Platform defaults |
CLAUDE.md says “skip TDD for this project” and the TDD skill says “always enforce RED-GREEN-REFACTOR,” your explicit instruction wins. You are always in control.
How skills trigger automatically
You do not invoke skills manually. Theusing-superpowers skill instructs your agent to check for relevant skills before responding to any message. The rule: if there is even a 1% chance a skill applies, the agent invokes it.
Skills load their full instructions at invocation time — the agent does not rely on cached knowledge. This means skill updates take effect immediately without reinstalling Superpowers.
Skills are rigid (like TDD and debugging) or flexible (like design patterns). Rigid skills must be followed exactly. The skill itself tells you which kind it is.
Navigate the workflow
Brainstorming
Refine ideas, explore approaches, produce a validated design doc before any code is written.
Writing plans
Break the approved spec into 2–5 minute tasks with complete code and TDD steps.
Executing plans
Dispatch subagents per task with two-stage review, or run inline with checkpoints.
Finishing a branch
Verify tests, run a final review, and choose to merge, PR, keep, or discard.