How the Brainstorming Skill Works in Superpowers: A Complete Technical Guide

The brainstorming skill in Superpowers is a mandatory, process-oriented workflow that enforces design-before-implementation by running a six-step checklist through a hard-gated state machine, ensuring every feature starts with an approved design document.

The Superpowers repository (obra/superpowers) implements a rigid creative workflow through its brainstorming skill, which acts as a mandatory prerequisite for all implementation tasks. This declarative process ensures that no code is written, refactored, or scaffolded until a thorough design review is completed and documented in the repository.

What Is the Brainstorming Skill?

The brainstorming skill is a hard-gated, checklist-driven workflow defined in skills/brainstorming/SKILL.md. Unlike typical CLI commands that execute imperative code, this skill declares a state machine that the Superpowers engine parses and enforces. It serves as the entry point for all creative work, preventing premature implementation through explicit <HARD-GATE> constraints that block any writing or scaffolding operations until design approval is granted.

How the Brainstorming Skill Is Invoked

The CLI Command Entry Point

Users trigger the workflow by executing:

superpowers brainstorm

This command maps to commands/brainstorm.md, which contains minimal configuration. The file instructs the engine to invoke superpowers:brainstorming and defer all output generation to the skill implementation itself.

Disabling Direct Model Output

The command file sets disable-model-invocation: true, preventing the CLI handler from generating autonomous responses. This flag ensures that only the scripted dialogue defined in the skill's checklist can produce output, maintaining strict process control and preventing the AI from skipping steps.

Skill Discovery and Resolution

Locating the Skill File

When the command is parsed, the engine calls resolveSkillPath from lib/skills-core.js (lines 99-138). This utility searches for SKILL.md in the following order:

1. Personal skill directory (user overrides)
2. Built-in skills/brainstorming directory

This resolution strategy allows custom implementations to shadow the default workflow while maintaining fallback integrity to the built-in skill.

Extracting Metadata

The extractFrontmatter function (lines 5-15 of lib/skills-core.js) parses the YAML header of SKILL.md to retrieve the skill name and description. This metadata populates help listings and validates the "skill-name: brainstorming" resolution required by the engine to confirm the correct skill is loaded.

The Hard-Gate Enforcement Mechanism

The <HARD-GATE> section (lines 14-16 of SKILL.md) declares a strict precondition: no implementation skill, code write, or scaffold may be invoked until a design has been presented and approved. The engine enforces this by rejecting transitions to "write-plan", "frontend-design", or similar nodes until the brainstorming flow reaches the "Invoke writing-plans" state. This creates an immutable barrier between ideation and execution, ensuring architectural decisions are documented before coding begins.

The Six-Step Checklist Process

The skill defines a mandatory six-step checklist (lines 22-31) that structures the creative workflow:

1. Explore project context – Analyze existing files, documentation, and recent commits to establish baseline understanding.
2. Ask clarifying questions – Engage in one-question-per-message interaction to resolve ambiguities.
3. Propose 2-3 approaches – Present alternative solutions with explicit trade-offs and a clear recommendation.
4. Present design – Break the proposal into sections, requesting approval after each segment.
5. Write design doc – Persist the approved design to docs/plans/YYYY-MM-DD-<topic>-design.md.
6. Transition to implementation – Automatically invoke the writing-plans skill to begin execution.

State Machine and Process Flow

The workflow is visualized as a DOT graph (lines 35-52) representing a finite state machine. After user approval of the design, the skill writes the design document and hands control to the writing-plans skill. This declarative approach ensures that the engine, not the user, manages state transitions according to the predefined graph, preventing skipped steps or premature execution.

Implementation Guards and Constraints

The skill enforces strict interaction patterns through two key constraints embedded in SKILL.md:

• One question at a time (lines 59-64): The dialogue protocol prohibits multi-part questions to maintain clarity and prevent overwhelming the user.
• Multiple-choice preferred (lines 91-93): When presenting options, the skill must use structured multiple-choice formats rather than open-ended prompts, reducing ambiguity in user responses.

These constraints are enforced by the engine's dialogue parser, ensuring consistent user experience across all brainstorming sessions.

Summary

• The brainstorming skill is a mandatory, declarative workflow defined in skills/brainstorming/SKILL.md that gates all creative work in Superpowers.
• It is invoked via superpowers brainstorm, which delegates to the skill while disabling direct model output through disable-model-invocation: true.
• The engine uses resolveSkillPath and extractFrontmatter from lib/skills-core.js to locate and parse the skill definition.
• A hard-gate prevents any implementation until the six-step checklist is completed and the design is approved.
• The process enforces structured dialogue through "one question at a time" and "multiple-choice preferred" constraints.

Frequently Asked Questions

What triggers the brainstorming skill in Superpowers?

The skill is triggered by executing superpowers brainstorm in the CLI. This command maps to commands/brainstorm.md, which instructs the engine to invoke the superpowers:brainstorming skill and disables direct model invocation to ensure the skill's scripted workflow controls all output.

Why does the brainstorming skill use a hard-gate mechanism?

The hard-gate, defined in the <HARD-GATE> section of SKILL.md, ensures that no implementation work—such as writing code, scaffolding, or invoking planning skills—can occur until a design has been presented and explicitly approved. This prevents premature execution and enforces design-first development practices.

How does Superpowers locate the brainstorming skill files?

The engine calls resolveSkillPath from lib/skills-core.js to locate SKILL.md. It first checks the personal skill directory for user overrides, then falls back to the built-in skills/brainstorming directory. Once found, extractFrontmatter parses the YAML header to retrieve metadata like the skill name and description.

What constraints does the brainstorming skill place on user interaction?

The skill enforces two primary dialogue constraints: the "one question at a time" rule, which prohibits multi-part questions to maintain clarity, and the "multiple-choice preferred" principle, which requires presenting options as structured choices rather than open-ended prompts. These constraints are embedded in the skill definition and enforced by the engine's dialogue parser.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}