How I spec out features with Superpowers

I use Superpowers to work through features before handing them to a coding agent to implement. I want the agent to help me figure out what I'm asking for, including the decisions I haven't thought through yet.

One feature I've been thinking about is letting a design doc contain additional documents. Take a Redis migration: you've got the spec and implementation plan, but now you want to rehearse it in staging and need a runbook.

The initial request is pretty simple: let someone create that runbook inside the design doc.

But if they follow the runbook, record a failed rehearsal, and then change the instructions, what happens to the record of that first attempt? Someone looking at it later needs to see the instructions that were actually used.

That's already more specific than “let people add documents.” It's also something I'd want decided before an agent starts building it.

For this feature, I'd give the agent the migration example and work through what the team needs to do:

That brings up questions about ownership, permissions, and revisions. Can a runbook be shared across unrelated changes? Does it inherit the design doc's permissions? What happens to old references if someone renames or archives it?

For the first version, I'd keep each supporting document attached to one change and use that change's permissions. Sharing a runbook across migrations and automatically executing its commands would be separate work.

I want those decisions written down so the agent has a clear scope to work within.

Superpowers has a brainstorming skill that works through the request and possible approaches before moving into a design and implementation plan. It also tells the agent to inspect the project before asking questions the code or existing docs already answer.

That last part matters to me. I don't want to point the agent at every relevant document or explain something it could find in the codebase. I want it to look first, then ask about what's still unresolved.

With the runbook example, an agent could ask whether I want version history. I'd probably say yes, but that answer leaves a lot unspecified.

A more useful question would be:

Someone follows revision 1 in staging and records a failed attempt. They change the instructions and try again using revision 2. What should someone reviewing the first attempt be able to see?

That question puts me in the position of someone actually using the product. I can think about the engineer reviewing the failed rehearsal, what they're trying to understand, and what they'd need to see. Just asking “Do you want version history?” makes it easy to say yes without thinking through how anyone will use it.

From that answer, we can get to a specific requirement: the first attempt has to keep a reference to revision 1. Editing the document can't change what that reference opens.

Permissions need the same attention. Inheriting the parent's permissions should cover old revisions, search results, and access through the agent, as well as the page someone opens in their browser.

These are the details I want to work through in the conversation.

One of my big gripes with using Superpowers is that I still have to tell the agent to do outside research. I mean searching the web, reading current documentation, and looking at how other people have approached the problem.

I think an informed decision needs more than what the model learned during training. Reading my codebase gives it context about the project. I also want it to look for information outside the project that could change its recommendation.

For the runbook example, I'd want it to investigate how other systems handle changes to a procedure after someone has used it. What tradeoffs did they make? What problems did they run into? That gives us more to consider when deciding how our version should work.

I want the agent to recognize when that research would help and do it without me having to ask. Then show me the sources, explain how they apply to this feature, and make it clear which conclusions are its own. Having to remember to add “go research this” is a part of the workflow I'd like to improve.

In my workflow, the spec describes what the change needs to accomplish. The implementation plan covers how to build it.

Part of the spec for this feature could be:

A supporting document belongs to one design doc and inherits its access permissions.

A recorded rehearsal can reference the exact document revision used.

Editing, renaming, or archiving the document preserves that reference for authorized readers.

Creating a runbook doesn't establish that the migration succeeded.

The implementation plan can then work out how to store those references, which UI and agent operations need updating, and how to test them.

The agent should also check what it can reuse. If the project already has revision history, I want the plan to explain how this feature fits into it. Introducing another versioning system would need a reason.

I'd take the revision requirement and turn it into a scenario:

An implementation could have a history page and still get this wrong. The scenario tells the agent exactly which behavior needs to hold up.

The runbook describes the procedure. The rehearsal record says what happened when someone followed it. Both need to stay understandable after the instructions change.

The same issue comes up elsewhere. If a pricing rule changes after an invoice is issued, you still need to know which rule produced that invoice. Thinking through a sequence like that helps me get more specific about what the feature needs to preserve.

If you have Superpowers installed, you could adapt this:

Use Superpowers to help me work through this feature before implementation.

Problem:
[Describe a specific situation and what someone needs to accomplish.]

Look through the relevant code, docs, and previous decisions first.
Tell me what already exists that affects this change.

Identify decisions that would benefit from outside research and
research them before recommending an approach. Look for current
documentation and relevant examples of how others solved similar problems.
Link the sources and explain how they affect your recommendation.
Distinguish what the sources establish from your own conclusions.

Ask about decisions we still need to make. Explain what the options
would mean for the feature and recommend an approach.

Make it clear when something is an assumption or your proposal.

Write a spec covering the intended behavior, what's in and out of scope,
unresolved questions, and concrete acceptance scenarios.

Once we've agreed on the spec, create an implementation plan based on
the codebase. Include how we'll check that the important behavior works.

Give it an actual situation to work through. For a notification feature, for example, explain who needs to be notified, what happened, and what they need to do next.

Superpowers is what I use, but I'd like to hear from people using other tools. Their docs describe a few approaches:

I'm also interested in people using their agent's planning mode and a Markdown file. Sometimes I just want to work through a problem without going through a full feature workflow.

One thing I'm still thinking about is how to handle changes once implementation starts. The agent finds that an assumption was wrong, the plan changes, and the next session needs to know why. I keep a work log alongside the design doc to record what changed and why.

How do you handle that in your setup? Do you update the spec, keep a separate record, or rely on the PR and conversation history?

I'd also like to hear about a recent change where planning helped, or where it became more work than it was worth. Which tool were you using, and what did you end up keeping or skipping?