---
name: superpowers
description: Use when the user is starting to build something non-trivial — a feature, endpoint, module, service, refactor, or any multi-part implementation. Stops the agent from rushing into code; runs a short interview, drafts a spec for sign-off, writes a plan, then builds and reviews in scoped passes.
---

# Superpowers (lightweight spec-driven flow)

You are operating under a spec-driven methodology. Your default failure mode is
rushing into code with guessed assumptions. This skill exists to stop that. When
it triggers, you change posture: you do not write implementation code until a
spec has been approved by the user.

## When to trigger

Activate this flow when the user is doing implementation work, such as:

- "Add / build / implement / create" a feature, endpoint, command, or module.
- "Refactor" or "rewrite" something with more than one moving part.
- Any task where building the wrong thing would cost real time to undo.

Do NOT trigger for:

- One-line fixes, typos, or trivial edits.
- Throwaway experiments and spikes where a spec gate just slows things down.
- Pure questions ("how does X work?") with no build attached.

If you are unsure whether the task is trivial, ask one question:
"Is this a quick change, or a real build where we should spec it first?"
Respect the answer.

## The flow, in order

1. Interview
2. Spec (get sign-off — hard gate)
3. Plan
4. Build (scoped passes)
5. Review (against the spec)
6. Verify and report

Never skip the spec sign-off. It is the entire point.

---

### Step 1 — Interview

Stop. Do not write code yet. Ask a SHORT, focused set of questions aimed only at
the ambiguity that actually changes the build. Target 3–6 questions, not 40.

Cover, only where relevant:

- Goal behind the goal — what is this actually for?
- Users / callers — who or what uses this, and how?
- Inputs, outputs, and data shape.
- Constraints — performance, security, compliance, existing patterns to match.
- Edge cases that change the design (scale, partial failure, auth boundaries).
- Definition of done and explicit out-of-scope.

Rules:

- Ask in one batch when you can, so the user can answer in one pass.
- Do not ask questions whose answers do not change what you build.
- If the user gives a vague answer that matters, ask one targeted follow-up.

### Step 2 — Spec (HARD GATE)

From the interview, write a specification. Keep it tight and concrete. Use this
shape:

```md
# Spec: <short title>

## Goal
<one or two sentences: what and why>

## Users / callers
<who uses this and how>

## Requirements
- <requirement>
- <requirement>

## Constraints
- <constraint>

## Acceptance criteria
- [ ] <observable, checkable condition>
- [ ] <observable, checkable condition>

## Out of scope
- <thing we are explicitly not doing>
```

Then STOP and present it. Say plainly: "Please review this spec. I won't write
any code until you approve it. Tell me what to change."

Hard rules:

- Do not proceed to a plan or code until the user approves.
- If the user requests changes, revise the spec and ask again.
- If requirements change later, update the spec FIRST, then continue. The spec is
  the contract the review step checks against; a stale spec corrupts the review.

### Step 3 — Plan

After the spec is approved, write a separate implementation plan. The spec is the
"what and why"; the plan is the "how." Keep them distinct.

```md
# Plan: <short title>

## Approach
<one paragraph on the strategy>

## Steps
1. <file/change> — <what and why>
2. <file/change> — <what and why>

## Slices for build passes
- Slice A: <bounded unit of work>
- Slice B: <bounded unit of work>

## Test strategy
<how correctness will be checked>
```

Slice the work into bounded units. Each slice should be independently buildable
and reviewable, with minimal context bleed between slices. Small, clean slices
keep each build/review pass focused.

### Step 4 — Build (scoped passes)

Implement ONE slice at a time. For each slice:

- Load only the context that slice needs: the spec, the relevant plan step, and
  the files it touches. Do not drag the whole history into every change.
- Write the implementation for that slice and nothing more.
- Keep changes small and consistent with the codebase's existing patterns.

If your runtime supports subagents, dispatch each slice to a builder subagent
with a clean, scoped context. If it does not, simulate the separation: implement
the slice in isolation, then in Step 5 deliberately switch into a critical
reviewer mindset rather than defending what you just wrote.

### Step 5 — Review (against the spec)

After each slice is built, review it adversarially. The reviewer's job is to find
problems, not to bless the work. Review the implementation against:

- The spec's acceptance criteria — does the code satisfy each one?
- The plan step it was supposed to fulfill.
- Correctness, edge cases, and the constraints from the spec.
- Consistency with surrounding code.

Produce findings as a concrete list:

```md
## Review findings — Slice <X>
- [BLOCKER] <what is wrong vs the spec, and where>
- [SHOULD] <improvement that matters>
- [OK] <criterion confirmed satisfied>
```

If there are BLOCKER or SHOULD findings, revise the slice and review again.
Loop until the slice satisfies the spec. Then move to the next slice.

If using subagents, the reviewer subagent must NOT be the same instance that
wrote the code — independent context produces honest review.

### Step 6 — Verify and report

When all slices are built and reviewed:

- Confirm every acceptance criterion in the spec is checked off.
- Run the project's tests / linters / type checks if available and report results.
  Do not claim something works if you have not verified it.
- Give the user a short summary: what was built, how it maps to the spec, what
  was verified, and anything left out of scope.

## What to avoid

- Do NOT write implementation code before the spec is approved.
- Do NOT ask interview questions whose answers don't change the build.
- Do NOT approve your own spec on the user's behalf — wait for them.
- Do NOT let the spec and the code drift apart; update the spec when goals change.
- Do NOT skip the review pass to "save time." It is the cheapest bug catch you get.
- Do NOT run this heavy flow on trivial work — match the ceremony to the stakes.
- Do NOT claim verification you didn't perform.

## How to verify you followed this skill

Before declaring done, confirm:

- [ ] An interview happened and its answers shaped the spec.
- [ ] A written spec existed and the user explicitly approved it.
- [ ] A plan existed, separate from the spec, sliced into bounded units.
- [ ] Each slice was built, then reviewed against the spec.
- [ ] All acceptance criteria are satisfied and checks were actually run.
- [ ] The final report maps the result back to the approved spec.

If any box is unchecked, you have not finished the flow.