Superpowers Starts Before the First Line of Code
For obra/superpowers, the first important action in a coding session is not opening a file. It is making sure the agent knows how to decide what kind of action the request requires. This chapter focuses on that startup control: how a bootstrap makes process guidance available before the agent answers, how shared skills reach different harnesses, and how to tell a real integration from files that merely happen to be installed. The practical judgment is simple: if the process arrives too late, the rest of the methodology may never get a chance to shape the work.
The first instruction changes the default
A coding agent is usually ready to act as soon as it receives a request. That readiness is valuable when the task is already precise. It is dangerous when the request contains hidden choices. “Add a dashboard,” “fix the flaky test,” or “make this easier to use” can each lead to exploration, design, implementation, debugging, or some combination of them. If the agent chooses the mode privately, the person directing the work may see the consequences only after code exists.
Superpowers changes that starting condition with a bootstrap that is intended to load at the beginning of a conversation. The bootstrap tells the agent to invoke a relevant process skill before any response or action, including a clarifying question, file exploration, or plan-mode detour. The instruction is deliberately stronger than “consider using a skill.” It treats the skill check as part of the action itself.
That rule creates a control point before the agent's normal momentum begins. For a feature request, the agent should first check the design-oriented process. For an unexpected failure, it should check the debugging process. For implementation, it should check the test-first process. If the initial choice turns out to be wrong, the process can be corrected; what it is not supposed to do is silently skip the decision because the task appears familiar or small.
The bootstrap also contains counters to predictable shortcuts. “This is just a simple question,” “I need more context first,” and “I know what that means” all sound reasonable because they appeal to efficiency or competence. In Superpowers' model, they are warning signs: the question, the context gathering, and the remembered concept are exactly where a process choice can be lost. The point is not to distrust the agent's knowledge. It is to prevent knowledge of a general concept from being mistaken for use of the current, operational guidance.
Why process comes before implementation
The order matters because implementation skills answer a different question. An implementation skill can help build a component, edit a configuration, or use a framework. A process skill decides whether building should start, what assumptions need confirmation, and which evidence will be required later. If the implementation skill goes first, it may turn an ambiguous request into an unapproved design before anyone has named the ambiguity.
Consider a request to add a small option to an existing tool. A direct implementation path might inspect the nearest function, edit it, and run a narrow test. The process-first path asks whether the option changes public behavior, whether a design decision is involved, and whether the work belongs in the current branch. If the answer is no, the resulting ceremony may be short. If the answer is yes, the request becomes a design problem before it becomes a coding problem. Superpowers is not claiming that every request needs a long document. It is insisting that the agent choose the appropriate level of process before it acts.
This is also why the bootstrap gives explicit user instructions priority over the methodology. The person directing the work can constrain the process, decline a workflow, or specify a project rule. Superpowers supplies defaults for disciplined action; it is not an independent authority over the project. The hierarchy matters in practice because a mandatory method without an authority boundary would turn a safety mechanism into an obstacle. The agent must follow the user's instructions first, then apply the relevant skills within those limits.
The startup rule therefore has two sides. It is strong about sequence—check the process before acting—and bounded about authority—do not use the process to override the person responsible for the work. That combination is what makes it a governance mechanism rather than a permanent interruption.
The sequence has an important initial condition: the bootstrap must reach the agent before the request is handled. Its termination condition is not merely “the file was found.” The agent must actually have the guidance in context and use it to select the next action. That distinction explains why Superpowers treats live integration testing as part of the architecture.
One shared body, different delivery mechanisms
Superpowers keeps the substantive skills shared across coding environments. The skills describe actions rather than naming one vendor's tool: read a file, edit a file, invoke a skill, dispatch a subagent, or create a task record. A harness-specific tool mapping translates those actions into the names and capabilities of the environment that is running the agent.
This separation solves two different problems at once. Shared content prevents the development method from changing merely because the agent is running in a different interface. Tool mappings prevent the shared content from pretending that every interface has the same buttons, message format, lifecycle events, or delegation support. The portable unit is the action and its purpose; the adapter owns the local mechanics.
The repository describes three broad delivery shapes. A shell-hook harness runs a command at session start and reads structured output. In that shape, the hook reads the startup skill, wraps it in the expected context, escapes it for the harness's JSON format, and emits the field that the harness actually consumes. The same hook cannot safely emit every possible field: one harness expects a nested context object, another a top-level field, and another a different naming convention. A wrong field can produce silent non-injection or duplicate context.
An in-process plugin works differently. The plugin registers the skills directory through the host's configuration API and injects the bootstrap into the message stream. Because a message transformation may run repeatedly, the integration needs a duplicate-injection guard. Because context can be compacted, it also needs a way to restore the bootstrap when the history is summarized. The message object itself belongs to the host: copying the shape from another integration can fail even when the text is correct.
An instruction-file integration has no running injector. Instead, the installed extension ships a context file that the harness loads and declares at startup. That file points to the shared bootstrap and the local tool mapping. The crucial word is “installed.” Superpowers' porting guidance does not treat editing a user's global instructions as an acceptable substitute for a real extension or plugin. The bootstrap must travel through the harness's own installation mechanism so that activation is reproducible and removable.
These shapes differ in mechanics but preserve the same causal requirement: startup delivery must precede the first decision that the request triggers. Portability is therefore not achieved by copying a skill body and changing tool names inside it. It is achieved by keeping the behavior-oriented content stable and placing local details at the boundary.
How to tell whether integration is real
A manifest can say that a plugin contains skills. A hook can contain a session-start command. A context file can point to the right location. None of those facts alone proves that a live agent received or followed the instructions. Superpowers' porting guide uses a stronger definition of completion: the bootstrap loads automatically in a clean session, the relevant skill can be invoked, the harness's tools are mapped, tests cover the wiring, and an exact acceptance prompt causes brainstorming to begin before code is written.
That last test is valuable because it checks behavior at the point where a weak integration fails. In a fresh session, the prompt “Let's make a react todo list” should cause the agent to enter the brainstorming process before it writes implementation code. A successful result demonstrates more than the existence of a file. It shows that the harness loaded the startup guidance, the agent recognized the request as requiring a process step, and the process took precedence over immediate implementation.
The test still has a boundary. One successful transcript does not establish perfect compliance across every model, version, operating system, or future harness update. It is evidence that a particular integration and runtime path worked under the tested conditions. The repository's own documentation treats this live test as necessary, not as a universal guarantee.
The acceptance test also checks an ordering property that a static test usually misses. It is not enough for the agent to mention brainstorming after it has already proposed code. The process must intervene before implementation, because later advice cannot reliably undo assumptions embedded in the first design. A clean session matters for the same reason: a resumed conversation may already contain the relevant instructions and therefore cannot show whether the harness supplied them automatically. The test is consequently a small experiment about initial conditions, sequencing, and observable behavior. It asks whether the installed integration changes the agent's first move, not whether the repository's configuration looks plausible to a maintainer reading it.
The same reasoning applies to capability gaps. File reading, file editing, and shell execution are treated as essential because the core workflows depend on them. Subagent dispatch, task tracking, and web access can degrade when a harness lacks them, provided the mapping tells the agent what fallback to use. A platform without subagents should not be encouraged to invent a tool call with a familiar name. It should either do the work in the current session or state the missing capability. A platform without a native skill loader may use its documented file-reading path, but that path must be explicit so the agent does not interpret it as a violation of the shared rule.
In other words, a good adapter reports its limits. It does not hide them behind a superficially compatible interface. That is another form of evidence-gated autonomy: the agent may continue when the missing capability has a safe fallback, but it should not claim that the full workflow is available when an important control is absent.
The human authority remains visible
The bootstrap's strength can make Superpowers sound more authoritarian than it is. It uses emphatic language because agents are good at finding plausible reasons to skip a process. But the method still places project-specific instructions and direct requests above its defaults. A person can say that a particular generated artifact does not need a full test cycle, or that a repository has a required way to handle branches. The agent's responsibility is to respect that instruction and make the resulting trade-off clear, not to treat the skill as a higher law.
This boundary also clarifies why “automatic” does not mean “uncontrolled.” Automatic startup removes the need for the person to remember a special command in every session. It does not remove consent at later decision points. Brainstorming still asks for approval before implementation, and branch finishing still leaves integration choices to the human partner. The bootstrap starts the governance process; it does not make all subsequent choices on the user's behalf.
Superpowers' first lesson is consequently about timing, not ceremony. Process guidance must be present before the agent's first consequential interpretation. Shared skills make the intended method portable, adapters translate it into local operations, and live acceptance tests show whether the delivery path works in reality. Once that pre-action boundary is in place, the agent can confront the next problem: turning a rough request into an approved design without imposing the same burden on every kind of work.