How to Start a Feature With Superpowers: A Step-by-Step Guide

You've installed Superpowers. Now what?

The good news: you don't need to learn any special commands or memorize a workflow. You just describe what you want to build — and Superpowers quietly takes over the rest, guiding your AI agent through a structured process before a single line of code gets written.

This guide walks you through exactly what happens, step by step, using a real-world example: adding a PayOS payment integration.

Before You Start: The Only Thing You Need to Know

Superpowers works by injecting skills into your coding agent. These skills auto-trigger based on context — you don't call them manually. When you describe a feature, the agent recognizes it and activates the right skill automatically.

Think of it like hiring a senior engineer who has a process they always follow, no matter what you ask them to build.

Step 1 — Describe What You Want (That's It)

Open Claude Code or Cursor. Type something like:

I want to add a PayOS payment integration to our checkout flow

Or more casually:

Let's build a notification system that alerts users when their timesheet is overdue

Or even vague:

I need a way for admins to export reports as PDF

All of these work. You don't need to write a perfect prompt. The agent's job — with Superpowers — is to turn your rough idea into something precise.

Step 2 — The Agent Asks Questions (Don't Skip This)

Instead of immediately writing code, the agent activates the brainstorming skill and starts asking clarifying questions:

• "What payment flows do you need — one-time, recurring, or both?"
• "Should failed payments retry automatically?"
• "Who handles refunds — the system or a human?"
• "What happens if the PayOS API is down?"

Answer each one honestly. If you don't know, say so — the agent will suggest a sensible default and move on.

After your answers, the agent produces a design document — a clear summary of what it understood, broken into sections short enough to actually read.

💡 Tip: This is the most important moment in the whole process. Mistakes caught here cost 2 minutes. The same mistake caught after implementation costs 2 hours.

Step 3 — Review and Approve the Design

The agent shows you the design in chunks. For each section you can:

• Say "looks good" to move on
• Say "change X to Y" and the agent updates it
• Ask "what about Z?" and the agent incorporates it

Example exchange:

Agent: "Section 1: PayOS client will use REST API with HMAC signature verification.
        Timeout: 10 seconds. Retry: 3 times with exponential backoff."

You:   "Change timeout to 5 seconds, we want to fail fast."

Agent: "Updated. Section 2: ..."

When you're happy with the whole design, just say:

Approved. Let's go.

Step 4 — The Agent Sets Up a Safe Workspace

The using-git-worktrees skill kicks in. The agent creates an isolated branch for your feature:

git worktree add ../feature-payos-integration feature/payos-integration

Your main branch is untouched. If anything goes wrong, you can throw away this branch with zero consequence. The agent also runs your existing test suite to confirm everything is green before starting.

💡 Tip: If your test suite is already failing before you start, the agent will flag it. Fix those first — it's good hygiene regardless.

Step 5 — The Agent Breaks the Work Into Small Tasks

The writing-plans skill activates. The agent splits the design into tasks of roughly 2–5 minutes each. Not vague milestones — concrete tasks with exact file paths, expected code, and a verification step.

Example plan for the PayOS feature:

Task 1 — Create PayOSClient
  File: src/payments/PayOSClient.ts
  Code: class with constructor(apiKey, endpoint) and createOrder() method
  Verify: unit test for createOrder() passes

Task 2 — Add config values
  Files: appsettings.json, appsettings.Development.json
  Code: PayOS section with ApiKey, Endpoint, TimeoutSeconds
  Verify: config loads without exception on startup

Task 3 — Create payment endpoint
  File: src/controllers/PaymentController.ts
  Code: POST /api/payments/create → calls PayOSClient.createOrder()
  Verify: integration test returns 200 with valid order object

Task 4 — Handle webhook callback
  ...

Task 5 — Add refund flow
  ...

The agent shows you the full plan. You can ask to split, merge, or reorder tasks before saying "go."

Step 6 — Say "Go" and Watch It Work

go

The subagent-driven-development skill takes over. For each task, a fresh subagent:

1. Reads the task spec
2. Writes a failing test first (RED)
3. Writes the minimum code to make it pass (GREEN)
4. Refactors if needed (REFACTOR)
5. Gets reviewed: does it match the spec? → is the code quality acceptable?
6. If both reviews pass → commits and moves to the next task

If a review fails, the subagent fixes it before moving on. You don't need to intervene.

✓ Task 1 complete — PayOSClient created, tests passing
✓ Task 2 complete — config loaded cleanly
✓ Task 3 complete — endpoint returning 200
⟳ Task 4 in progress...

💡 Real talk: It's normal to walk away and come back 30–45 minutes later to find 6 out of 8 tasks done with passing tests. This is the whole point.

Step 7 — Choose What to Do With the Branch

When all tasks are complete, the agent asks:

All tasks complete. Tests passing. What would you like to do?

  1. Merge to main
  2. Open a Pull Request
  3. Keep the branch for now, continue later
  4. Discard all changes

Pick the one that fits your team's workflow. Done.

The Full Picture

You type a feature idea
        │
        ▼
  Agent asks questions
  (brainstorming skill)
        │
        ▼
  You approve design
        │
        ▼
  Agent creates branch
  (git worktrees skill)
        │
        ▼
  Agent writes task plan
  (writing-plans skill)
        │
        ▼
  You say "go"
        │
        ▼
  Subagents execute tasks
  → write test → write code → review → commit
  (subagent-driven-development + TDD skills)
        │
        ▼
  Merge / PR / keep / discard

What You Actually Do vs What the Agent Does

Your job is to make decisions. The agent's job is to execute them — correctly, with tests, in a repeatable way.

Common Questions

What if I want to skip brainstorming for a tiny change?

You can tell the agent: "Skip brainstorming, this is a small change — just add a loading spinner to the submit button." Superpowers won't force the full flow on trivial tasks. It's smart enough to match the workflow to the scope.

What if the agent gets something wrong in a task?

The two-stage review catches most issues automatically. But if you spot something wrong, just tell the agent during execution: "Task 3 is missing error handling for 422 responses." It will fix the current task before proceeding.

Can I add my own skills?

Yes. The writing-skills skill walks you through creating custom skills for your specific domain. For example, you could write an etm-timesheet-task skill that always reminds the agent to log time against the correct Azure DevOps work item after completing each task.

The Bottom Line

Superpowers doesn't make your AI agent smarter. It makes your AI agent more disciplined — and discipline, it turns out, is what was missing all along.

The next time you want to build a feature, just open Claude Code or Cursor and describe it. The agent handles the rest.

→ github.com/obra/superpowers