Superpowers Turns Ideas into Approved Designs
In obra/superpowers, brainstorming is the mechanism that decides what a request means before anyone decides how to implement it. This chapter focuses on the transition from a rough request to an approved design: how the workflow changes its level of ceremony for different kinds of work, why approval remains a hard boundary even for a tiny change, and how questions, alternatives, scope checks, and an optional visual companion reduce uncertainty. The practical result is a way to tell whether a task is ready for execution or is still hiding a design decision.
Three kinds of request, three levels of ceremony
A request does not announce its own scope reliably. “Can this approach work?” may be a feasibility probe. “Add one option to this existing command” may be a bounded change. “Build a new system that connects several independent services” is architectural. The words alone are not enough; the surrounding project and the consequences of the change determine the path.
Superpowers therefore begins by classifying the work as a spike, bounded, or architectural. The classification is not a ranking of importance. It selects the smallest process that can expose the decisions the task actually contains.
A spike is a feasibility question whose intended output is an answer, not production code. The agent frames the question and the proposed probe in a few sentences, gets a nod, investigates as cheaply as correctness allows, and reports a recommendation. Anything built during the probe remains throwaway. That last condition matters: a successful experiment answers “is this possible?” It does not silently authorize turning the experiment into a maintained feature.
A bounded task changes an existing flow in a well-understood repository. A new flag, a small endpoint, or a one-file behavior change may fit this path. The agent explores enough context to understand the flow, asks the questions that affect the outcome, presents a short design in the conversation, and stops for explicit approval. There is no written specification or implementation-plan document by default. The artifact is smaller, but the authorization boundary is the same.
An architectural task creates a project, subsystem, or interface that changes how components fit together. Here, the workflow expands: the agent explores context, asks focused questions, proposes two or three approaches with trade-offs, presents a design in sections, writes a specification, performs a self-review, and waits for the person's review before moving to planning. If the request contains several independent subsystems, Superpowers says to decompose it into separate sub-projects, each with its own design and implementation cycle.
The important rule is that the classification can move in only one direction during the task. If a bounded request reveals hidden complexity, the agent upgrades the process instead of preserving the lighter label to save time. A label that exists only to avoid difficult questions is not scope control; it is scope denial.
The state model makes two boundaries visible. First, the paths are conditional: the same request can become heavier when its actual scope changes. Second, the implementation state is reachable only after the relevant design or probe decision has been approved. The chart does not mean that a spike's throwaway probe becomes a product; its terminal result is a recommendation. That separation prevents evidence gathered for a question from being mistaken for authorization to ship a solution.
Approval is a transition, not a courtesy
It is tempting to treat approval as a polite pause while the agent prepares the “obvious” implementation. Superpowers treats it differently. Before approval, the agent is still proposing an interpretation. After approval, the interpretation becomes the shared boundary within which planning and implementation can proceed.
That distinction remains necessary when the design is only two sentences. A short design may say which existing behavior will change, what will remain stable, and how the result will be tested. The brevity reduces reading cost; it does not remove the possibility of an incorrect assumption. Small changes are often where an agent can make a local edit that looks harmless but alters a public contract, introduces a new dependency, or solves the wrong version of the request.
The approval gate also preserves ownership. The agent can recommend an approach, explain trade-offs, and make a design legible. The person directing the work decides whether that design represents the intended change. If they ask for revisions, the design returns to refinement. If they approve it, the agent has permission to move to the next boundary; it has not gained permission to add unrelated features or reinterpret the agreement whenever implementation becomes inconvenient.
This is why the gate is not measured by document length. The process scales the artifact, not the authority. A spike may receive a short probe description. A bounded task may need a compact in-chat design. Architectural work may need a full specification. Each path still stops at the point where another person must confirm that the agent's understanding is the one they want implemented.
Questions reduce uncertainty before options multiply
The quality of the design depends on the questions asked before it is written. Superpowers recommends asking one question at a time, with a preference for concrete choices when they clarify the decision. The purpose is not to conduct an exhaustive interview. It is to uncover purpose, constraints, and success criteria that would otherwise be smuggled into the implementation.
A useful question changes the set of possible designs. If a person asks for a new report, the agent may need to know whether the report is for occasional human inspection or for a machine-consumed interface. If they ask to make a workflow faster, the agent may need to know whether latency, cost, or reliability is the binding constraint. If they ask for a visual change, the agent may need to distinguish a preference about layout from a requirement about accessibility or information hierarchy. The answers affect the architecture, not just the wording of the eventual plan.
Once the purpose and constraints are clear, Superpowers asks the agent to propose two or three approaches with trade-offs and a recommendation. This prevents the design conversation from becoming a menu of unranked possibilities. The agent should lead with the option it recommends and explain why it fits the stated goal. It should also apply YAGNI—“You Aren't Gonna Need It”—by removing features that do not serve the current outcome.
The recommendation is not a substitute for approval. It is a way to make the decision inspectable. A person can accept it, reject it, or point out a constraint the agent missed. A list of alternatives without reasoning simply transfers the prioritization burden back to the person. A confident single answer without alternatives can hide the fact that the agent never considered another way to satisfy the goal. The useful middle is a small set of meaningful choices, explicit trade-offs, and a reasoned recommendation.
Boundaries are part of design quality
Superpowers' design guidance treats isolation and clarity as technical concerns, not merely organizational preferences. A unit should have one clear purpose, a defined way to be used, and known dependencies. Someone should be able to understand what the unit does without reading its internals, and consumers should be able to rely on the interface while the implementation changes behind it.
These boundaries matter because an agent reasons better about a system it can hold in context. A file that contains unrelated responsibilities is harder to inspect and easier to change incorrectly. A subsystem with no clear interface forces each caller to know internal details. A proposal that spans chat, storage, billing, and analytics may sound like one product request, but it contains several designs with different risks. Decomposing it is not bureaucratic delay; it identifies which promises can be tested independently and which dependencies must be settled first.
The guidance is deliberately targeted rather than revolutionary. In an existing codebase, Superpowers says to follow established patterns and improve a tangled boundary only when the improvement serves the current goal. This prevents a design discussion from turning into a license for unrelated refactoring. The agent must balance two errors: preserving a boundary so confusing that the requested change cannot be made safely, and expanding the scope until the original outcome is lost.
The same reasoning applies to the specification that follows an architectural design. A specification records a shared decision before planning translates it into tasks. It is not meant to describe every possible future. Its value is that it makes the selected boundary explicit enough for review and execution, while leaving implementation details to the later plan when those details are necessary.
The visual companion has a narrow job
Some design questions are genuinely spatial. A choice among navigation layouts, a relationship among system components, or a comparison of visual hierarchies may be easier to understand as a diagram or mockup than as paragraphs. Superpowers includes an optional browser-based visual companion for those cases, but its placement reveals the larger philosophy: it is offered just in time, not at the start of every conversation and not for every question.
The decision rule is whether the user would understand the specific content better by seeing it than by reading it. Requirements, scope decisions, conceptual alternatives, and trade-off lists remain terminal conversations. A question about a user interface is not automatically a visual question; “what should this wizard mean?” is conceptual, while “which of these wizard layouts works?” may be visual.
When the companion is used, the server watches a content directory and serves the newest screen. The person can click options, and those interactions are recorded as structured events that the agent reads alongside the person's written response. This creates a useful distinction between exploration and commitment: a person may click several options while comparing them, and the final choice or the pattern of hesitation can inform the next question.
The companion also has operational boundaries. Its session URL includes a key that gates browser requests and WebSocket connections. The server is designed to keep served content separate from session state, to persist a project-backed session when requested, and to protect the file-serving surface against path escapes and other unsafe access patterns. These safeguards matter because a visual brainstorming server may run on a shared or remotely reachable machine. The browser is an aid to design, not an excuse to expose the design session.
The feature remains optional because visual interaction has costs. It may be unavailable in a headless environment, slower to use than a text exchange, or unnecessary for a purely conceptual decision. Superpowers does not equate a richer interface with a better design. It asks the same question it asks of every other addition: does this reduce a real uncertainty in the current request?
What an approved design has accomplished
At the end of brainstorming, Superpowers has not proved that the future code will be correct. It has accomplished something narrower and necessary. The agent and the person directing the work have agreed on the problem being solved, the scope that matters, and the boundary within which implementation may proceed. The design has been made proportionate to the task, and hidden complexity has had a chance to force a more appropriate path.
That changes the kind of uncertainty the next stage must handle. The question is no longer primarily what the request means. It is how to preserve that meaning while work is isolated, divided into executable tasks, and exposed to tests and review. Approved intent is the starting condition for safe execution, not its guarantee. The next step is to connect it to a protected workspace and a plan precise enough for action.