brainstorming

Overview

What the brainstorming skill does

The brainstorming skill enforces a clear rule: design and specification come first, implementation comes later. When enabled, brainstorming guides you to explore user intent, requirements, and high-level design before writing code, scaffolding projects, or invoking any implementation skill.

It is built around collaborative dialogue. You start from a rough idea, refine context and constraints through targeted questions, then converge on an explicit design and spec the user can review and approve. Only after that hard approval gate is it appropriate to move on to build or refactor work.

Who brainstorming is for

Use the brainstorming skill if you:

• Work with Claude or similar agents on product features, components, UI flows, or architecture changes
• Want to avoid the anti-pattern of “this is too simple to need a design”
• Need repeatable, auditable design conversations before code changes
• Frequently build or adjust frontend, UI/UX, or workflow-heavy systems

It fits solo developers, product engineers, designers, and teams that want a lightweight but consistent design-first workflow.

Problems this skill solves

The brainstorming skill is designed to prevent:

• Jumping straight into code without clarifying goals
• Hidden assumptions that only surface late in implementation
• UI/UX changes built without clear user journeys or visual direction
• Specs that are too vague for reliable planning or delegation

By forcing a design checkpoint, brainstorming reduces rework, misaligned implementation, and design debt.

When brainstorming is a good (or bad) fit

A strong fit when:

• You are planning new features, modifying behavior, or designing UI/UX flows
• You want a structured template for ideation, context gathering, and design approval
• You benefit from visual mockups or diagrams while thinking through options

A weaker fit when:

• You are doing pure mechanical edits (typo fixes, renaming a variable, updating a constant with no behavioral change)
• You already have a detailed, approved spec and are only executing it (in that case, you may use implementation-focused skills instead)

Even seemingly trivial tasks like a small config change or a single-function utility can benefit from a short design pass, but you can keep that pass brief while still using the brainstorming process.

How to Use

Installation and setup

1. Install the brainstorming skill

Use the skills CLI to add the brainstorming skill from the obra/superpowers repository:

npx skills add https://github.com/obra/superpowers --skill brainstorming

This pulls in the skill definition plus supporting prompts and optional helper scripts under the skills/brainstorming directory.

2. Explore the key files

After installation, review these files to understand the workflow and available helpers:

• SKILL.md – Core description of the brainstorming process, including the hard design-before-code gate and the checklist of required steps.
• spec-document-reviewer-prompt.md – Template prompt for a spec-review subagent that checks completeness, consistency, and clarity of your spec.
• visual-companion.md – Guide for using a browser-based visual companion to show mockups, diagrams, and visual options.
• scripts/frame-template.html – HTML frame template used by the visual companion for consistent, UI-focused layouts.
• scripts/helper.js – Client-side helper for handling selection events and live reload in the visual companion.
• scripts/server.cjs, scripts/start-server.sh, scripts/stop-server.sh – Scripts to run and manage the visual companion server.

You do not need to modify these files to start using the brainstorming workflow, but knowing what is available helps you integrate it into your own setup.

Core brainstorming workflow

1. Start with project context

Begin any session with brainstorming by orienting around the current project. The checklist in SKILL.md emphasizes:

• Inspecting relevant files and docs
• Skimming recent commits for context
• Identifying which parts of the system are in play

When using Claude or another agent, prompt it to explore project context first instead of asking for code changes right away.

2. Offer the visual companion for visual questions

If the task includes UI/UX or other inherently visual topics, offer to use the visual companion as a separate step. The rule from visual-companion.md is:

Decide per-question, not per-session. Ask: would the user understand this better by seeing it than reading it?

Use the browser-based companion for:

• UI mockups and layout options
• Architecture and flow diagrams
• Side‑by‑side comparisons of design directions
• Discussions about spacing, hierarchy, and visual polish

Stay in the terminal (text-only) for:

• Scope, requirements, and definitions of terms
• Conceptual tradeoffs and API/data modeling choices
• Clarifying questions where the answers are words, not visuals

3. Ask clarifying questions one at a time

The brainstorming skill expects a disciplined conversation, not a single mega-prompt. Use a sequence of focused questions, for example:

• "Who are the primary users of this feature?"
• "What constraints do we have on performance or deployment?"
• "Which platforms and screen sizes matter most?"

Ask one question at a time, wait for answers, and refine your understanding incrementally.

4. Produce a concrete design and spec

Once you have enough context, synthesize it into a design that the user can actually approve. Depending on the task, that may include:

• High‑level goals and success criteria
• User stories or example flows
• UI layout descriptions and visual directions (optionally backed by the visual companion)
• Data structures, interfaces, or integration points
• Non‑functional requirements that affect implementation

Write this as a structured spec document in your preferred location (for example, under docs/superpowers/specs/ if you follow the repository convention).

5. Enforce the hard design gate

A key rule from SKILL.md is the hard gate:

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.

This applies even when the work seems simple. The design might only be a few sentences for a trivial change, but it must exist and be explicitly confirmed before moving ahead.

Using the spec document reviewer template

1. Draft your spec

After brainstorming, draft your spec using whatever structure suits your project. Save it to a file path you can reference, such as:

docs/superpowers/specs/my-feature-spec.md

2. Dispatch a spec reviewer subagent

When the spec is ready for validation, use spec-document-reviewer-prompt.md as a template to spin up a spec-reviewing subagent. Replace [SPEC_FILE_PATH] in the prompt with the path to your spec file.

This reviewer will:

• Check for missing sections, TODOs, or “TBD” placeholders
• Look for contradictions and inconsistent requirements
• Flag ambiguous requirements that could cause mis‑implementation
• Ensure the scope is tight enough for a single, coherent plan

The reviewer output includes an Approved | Issues Found status and a list of issues, each tied to why it matters for implementation planning.

3. Iterate until approved

If the reviewer finds issues, update the spec and re‑run the review. Once your spec is approved, you have a solid base for implementation skills and planning tools.

Using the visual brainstorming companion

1. Start the visual companion server

From the scripts directory, you can start the brainstorm server using:

./start-server.sh --project-dir /path/to/your/project

Useful options include:

• --project-dir <path> – Store session files under <path>/.superpowers/brainstorm/ instead of /tmp for persistence.
• --host <bind-host> – Bind to a specific interface (for example, 0.0.0.0 in containers or remote environments).
• --url-host <display-host> – Control the hostname shown in the returned URL JSON.
• --foreground or --background – Choose whether the server runs in the current terminal or as a background process.

On startup, the script prints JSON with the session URL. Open that URL in a browser to access the visual brainstorming frame.

2. Render visual options

The server watches a directory for HTML files and always serves the newest one. The typical pattern is:

1. Claude (or your agent) writes an HTML file to the configured screen_dir using frame-template.html as the base.
2. The browser automatically reloads via helper.js when a new file is created.
3. Users can click options or cards within the UI, and those events are sent back over WebSocket for the agent to consume.

This makes it easy to show:

• Multiple layout options as clickable cards
• Flow diagrams and state machines
• Visual comparisons of color, spacing, or component variants

3. Stop the server when done

When the session is over, cleanly stop the brainstorm server using:

./stop-server.sh <session_dir>

For sessions under /tmp, this also cleans up the generated files. Persistent directories under .superpowers/ are preserved so you can revisit mockups and diagrams later.

Integrating brainstorming into your own workflow

• As a standard pre‑commit step: Require a brainstorming pass and an approved spec before merging feature branches.
• With other skills: Run brainstorming first, capture the spec, then hand off to implementation, refactoring, or testing skills.
• For UI/UX work: Combine conversational brainstorming with the visual companion to validate layout and interaction ideas before any CSS or component code is written.

Adjust the folder paths, naming, and spec format to match your existing repos while keeping the core pattern: context → questions → design/spec → review → implementation.

FAQ

Is the brainstorming skill only for big, complex projects?

No. The brainstorming skill is explicitly designed to avoid the anti-pattern of “this is too simple to need a design.” Even a small config change or one‑off utility can hide assumptions. For very small tasks, the design may be just a concise description, but you should still articulate and confirm it before implementation.

Can I skip brainstorming if I already have a spec?

If you already have a thorough, up‑to‑date, and approved spec, you may not need a full brainstorming session. However, you can still use the spec reviewer template from spec-document-reviewer-prompt.md to validate that spec before implementation. If the review reveals gaps or ambiguities, run a shorter brainstorming pass to close them.

How does brainstorming work with implementation skills?

The brainstorming skill is intended to run before any implementation skills. It produces:

• A clear, user‑approved design
• A spec document that can be reviewed and iterated

Only after that approval gate is passed should you invoke coding or refactoring skills. This separation helps keep design intent explicit and reduces back‑and‑forth during implementation.

Do I have to use the visual companion to benefit from brainstorming?

No. The visual companion is optional.

• If your work is mostly backend logic, APIs, or infrastructure, you can use brainstorming as a purely text-based workflow.
• If you do UI/UX, product design, or frontend work, using the visual companion from visual-companion.md and the scripts/ directory can make it much easier to compare options and gather feedback.

Choose based on whether visuals would genuinely clarify the conversation.

What happens if I ignore the hard gate and start coding anyway?

Ignoring the hard design gate removes the main benefit of the brainstorming skill: catching misalignments early. You may end up with:

• Features that do not match user expectations
• UI implementations that need to be rebuilt after feedback
• Specs that lag behind the code and become documentation debt

Treat the gate as a process rule: do not write or request code until the design is written, reviewed, and explicitly approved.

Can I customize the spec review criteria?

Yes. spec-document-reviewer-prompt.md defines categories like completeness, consistency, clarity, scope, and YAGNI considerations. You can adapt this template to your own domain (for example, adding security, performance, or compliance checks) while keeping the same review flow.

Is brainstorming tied to a specific framework or tech stack?

No. The brainstorming skill is stack‑agnostic. It focuses on context gathering, requirements clarification, design articulation, and visual exploration, not on framework-specific code. You can use it for frontend apps, backend services, integrations, or mixed systems.

How do I uninstall or disable the brainstorming skill?

The skill is just a part of the obra/superpowers skill set. To stop using it, you can:

• Remove or comment out its configuration in your agent or skills loader
• Stop calling it in your workflows and pipelines

No global system changes are made by the brainstorming skill itself, so removal is simply a matter of configuration and usage.