Brainstorming before you build

Finds out what you want to build and why: one question at a time, its understanding played back part by part, two or three approaches to pick from and a design doc, with no code until you approve it. Use for a new feature or change when the request leaves the essentials open.

Vibe codingPack: Superpowers316 linesbrainstorming
Author
Source
obra/superpowers/skills/brainstorming @ 22f0b46
License
MIT · Copyright (c) 2025 Jesse Vincent

About this skill

What it does

Brainstorming makes the agent find out what you want, and why, before it builds anything. A request that already holds everything ("make the icon cornflower blue") just gets done. Otherwise the agent reads the project, asks one question at a time, plays its understanding back part by part, offers two or three ways to build it with a recommendation, and writes a design doc. Nothing is built until you approve it: no code, scaffolding or new dependencies.

The doc goes to docs/superpowers/specs/. For a project-sized design, builder-check-prompt.md has a fresh subagent read it as a builder who cannot ask questions, so you get only the open questions that are yours to answer.

The rest is a visual companion for questions about how something looks. scripts/start-server.sh runs server.cjs, a dependency-free Node server that shows the agent's HTML mockups in a browser tab and records which option you click; visual-companion.md is the guide. Its page loads a logo from primeradiant.com unless SUPERPOWERS_DISABLE_TELEMETRY is set.

When to use it, and when not

Use it before a new feature, component or change of behaviour when the request leaves open what gets built, including work outside code, such as a talk or a renovation.

Skip it when the request is complete or you want the agent to start now. If you did not ask for brainstorming, its first message offers to just dive in; saying yes ends the skill.

How to run it

The install command below puts the whole folder in place. The agent picks the skill up by its description before creative work; to call it yourself:

  • Claude Code: /brainstorming, or ask for the skill by name.
  • Codex: $brainstorming.
  • Cursor: type / in the Agent chat and pick brainstorming.

Example: /brainstorming Add CSV export to the orders page. Ask me what you need before writing code.

After approval the skill hands off only to writing-plans, whose plan is run by subagent-driven-development or executing-plans; install them together. The companion needs Node and bash (Git Bash on Windows).

How it differs from similar skills

Spec-first kickoff from our catalog also holds code back until you agree, but it asks up to five questions at once, each with a default, and returns a one-page spec and a 4–10 step plan in one go. Brainstorming is a conversation: one question at a time, playback, approaches in their own message, a builder check, the plan left to another skill. Pick spec-first kickoff for a quick start on a small app, brainstorming when the intent is unclear and a wrong guess is expensive.

Interview me also asks one question at a time, but attaches its guess to each and stops at a confirmed statement of intent, with no approaches or design doc. Idea refinement works a step earlier: it generates five to eight variations on purpose and ends with a one-pager and a Not Doing list. Grilling a plan questions a plan you already have in numbered rounds with recommended answers and writes nothing down.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/brainstorming/SKILL.md https://anymodel.org/en/skills/superpowers/brainstorming/SKILL.md -o ~/.claude/skills/brainstorming/LICENSE https://anymodel.org/en/skills/superpowers/brainstorming/LICENSE -o ~/.claude/skills/brainstorming/builder-check-prompt.md https://anymodel.org/en/skills/superpowers/brainstorming/builder-check-prompt.md -o ~/.claude/skills/brainstorming/scripts/frame-template.html https://anymodel.org/en/skills/superpowers/brainstorming/scripts/frame-template.html -o ~/.claude/skills/brainstorming/scripts/helper.js https://anymodel.org/en/skills/superpowers/brainstorming/scripts/helper.js -o ~/.claude/skills/brainstorming/scripts/server.cjs https://anymodel.org/en/skills/superpowers/brainstorming/scripts/server.cjs -o ~/.claude/skills/brainstorming/scripts/start-server.sh https://anymodel.org/en/skills/superpowers/brainstorming/scripts/start-server.sh -o ~/.claude/skills/brainstorming/scripts/stop-server.sh https://anymodel.org/en/skills/superpowers/brainstorming/scripts/stop-server.sh -o ~/.claude/skills/brainstorming/visual-companion.md https://anymodel.org/en/skills/superpowers/brainstorming/visual-companion.md && chmod +x ~/.claude/skills/brainstorming/scripts/start-server.sh ~/.claude/skills/brainstorming/scripts/stop-server.sh
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/brainstorming/SKILL.md https://anymodel.org/en/skills/superpowers/brainstorming/SKILL.md -o ~/.agents/skills/brainstorming/LICENSE https://anymodel.org/en/skills/superpowers/brainstorming/LICENSE -o ~/.agents/skills/brainstorming/builder-check-prompt.md https://anymodel.org/en/skills/superpowers/brainstorming/builder-check-prompt.md -o ~/.agents/skills/brainstorming/scripts/frame-template.html https://anymodel.org/en/skills/superpowers/brainstorming/scripts/frame-template.html -o ~/.agents/skills/brainstorming/scripts/helper.js https://anymodel.org/en/skills/superpowers/brainstorming/scripts/helper.js -o ~/.agents/skills/brainstorming/scripts/server.cjs https://anymodel.org/en/skills/superpowers/brainstorming/scripts/server.cjs -o ~/.agents/skills/brainstorming/scripts/start-server.sh https://anymodel.org/en/skills/superpowers/brainstorming/scripts/start-server.sh -o ~/.agents/skills/brainstorming/scripts/stop-server.sh https://anymodel.org/en/skills/superpowers/brainstorming/scripts/stop-server.sh -o ~/.agents/skills/brainstorming/visual-companion.md https://anymodel.org/en/skills/superpowers/brainstorming/visual-companion.md && chmod +x ~/.agents/skills/brainstorming/scripts/start-server.sh ~/.agents/skills/brainstorming/scripts/stop-server.sh
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','builder-check-prompt.md','scripts/frame-template.html','scripts/helper.js','scripts/server.cjs','scripts/start-server.sh','scripts/stop-server.sh','visual-companion.md') { $p = Join-Path "$HOME\.claude\skills\brainstorming" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/superpowers/brainstorming/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','builder-check-prompt.md','scripts/frame-template.html','scripts/helper.js','scripts/server.cjs','scripts/start-server.sh','scripts/stop-server.sh','visual-companion.md') { $p = Join-Path "$HOME\.agents\skills\brainstorming" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/superpowers/brainstorming/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/superpowers/brainstorming/SKILL.md

SKILL.md

Raw

Brainstorming

You are very good at building. You build what you believe your human partner wants, and that belief is usually thinner than it feels. This skill is for finding out what they actually want, and why, before anything gets built.

People often haven't finished working out what they want. Good questions help them think it through. When you understand the why, you make the hundred decisions they never mention the way they would have made them.

First: What Do You Actually Know?

Before you reply, ask yourself: what do I know about what they want, and why?

  • Everything that matters is in the request ("make the icon cornflower blue"). This is a quick, clear task. Do it, and say what you did.
  • Something non-trivial is missing. Start the conversation.

Before you start implementing, you must, in order:

  1. Lay out the approaches in a message of their own, and have your human partner pick one (see Lay out the approaches).
  2. Write the design doc, short or full (see Size the Work).
  3. Get their approval of that doc.
  4. Invoke the superpowers:writing-plans skill.

If nothing is open when you write your first message and there's one sensible way, steps 1 to 3 happen in that message (see Your First Message).

Two things aren't implementing: a spike they said yes to (see Spike to feel things out), and doing what they asked once they've opted out of the questions.

Look Before You Ask

In an existing project, or when they've given you context (a spec, a plan, a handoff, files they pointed at, earlier conversation), dig in before your first message. Read what they referred to and the code or material it connects to, and keep reading until you can explain how the relevant parts work today and what this change would touch. Never ask what the project or their context already answers, or reopen what they've already decided.

Your First Message

Move the work forward, with one of these:

  • They've already said what they want (a spec, a plan, a detailed request): aim for about 200 words for the whole message. Echo their request back in your own words, so they can see whether you've got its shape: what they want, who it's for, and why, as far as they've said. Add what you found that bears on it: how the relevant parts work today and what the change would touch. If you found something they may not have considered that would change what they're asking for or how it has to be built, like a constraint, a conflict, or a cheaper path, say so plainly. How to build it comes later, once you understand what they want (see Lay out the approaches). End with one line inviting corrections. Then, if they haven't told you why they want it, even if you can guess, ask about that: one open question in their own terms, with nothing to pick from. If they have told you, and their request and the project leave open something whose answer would change what gets built, ask about the one that would change it most; when its choices can be named, sketch each concretely, with what it trades off and which you'd pick. If nothing like that is open, there's one sensible way: end with the short design itself (the approach, a line on why the others don't fit, and the design in a few lines) and ask them to approve it. Their approval covers the approach and the design: write the short design doc as approved and go on to the plan. Specs are often incomplete, so confirm before you build on one.
  • They haven't: one open question, in their own terms, about the biggest thing their request leaves unsettled. Say why you're asking: what the answer would change about what you build. For "a website for my bakery": "If it's mostly for people deciding whether to stop by, I'd lead with hours and what's in the case today; taking orders is a different site. What do you want someone to do when they land on it?"

How the message ends depends on whether their message asked for brainstorming:

  • They asked for it (by name, by invoking it, or by asking for a design discussion): end there. They want this conversation.
  • They didn't: they may not want a conversation at all. End with a light, one-line offer to just get going instead, like "Or if you'd rather I just dive in, say so." If they take you up on it, this skill is done: state any significant how-it-gets-made choice (platform, language, medium) in one plain line, then do what they asked through the normal workflow.

That's the whole message.

The Conversation

Ask a question only when the answer would change what gets built and neither the request nor the project answers it. Otherwise, state your call and your reason as a proposal they can correct, and move the work forward. Process steps are always your calls: writing things up, where files go, looking further, how to show something. Do them and say so. Ask one at a time. Use plain language, pitched just a little above where your human partner is. Match their vocabulary; never use process jargon. You never need to quote this skill to your human partner.

Be clear and concise. Lead with what matters. Avoid jargon. When you report what you found, give them the most important findings and offer the rest.

Get them describing. Until you know why they want it, ask open questions, with no example answers attached. Their own words carry intent that your options can't. Once you know why, when a decision has choices you can name, sketch each concretely, with what it trades off and which you'd pick. When they say "just guess" or "what do you think?", propose something concrete.

How it gets made. Every project rests on choices about medium, tools, materials, and resources: the platform, programming language, and libraries for an app; the medium for a piece of art. Read from how they talk which of those choices they want to make. Someone who raises the how or asks about trade-offs wants the options with your pick. Someone who talks about outcomes is handing you the how: make those calls and state each in a line. When there's existing work, build on what it already uses. Any choice you make goes in the design as your call, never as something they agreed to.

Ground to cover. This is territory, not a script. Never read these out as questions:

  • what kind of thing this is, and what makes it special
  • why now, and what success looks like to them
  • goals, non-goals, and anti-goals (what would make this a failure even if it technically works)
  • prior art: what they've seen elsewhere, loved or hated
  • current state: what exists now, what they've tried
  • the details they care about

Make every question specific to their project and what they've told you. Ask Socratically, the way a sharp colleague would: build each question on their last answer or on something you found, so it helps them think through a consequence or a case they may have missed ("Voting closes before the meeting, and two members joined this month. Does someone who joins mid-round get a vote?"). When the reason isn't already plain, say what you're hoping to learn or what the answer would change. A proposal they can correct, plus your reason for it, often beats a question.

Do recon. Once you have a bit of grounding and looking further would help, go look: deeper into their codebase or project, their own files and data, or the web. Say what you looked for and what you found.

Lay out the approaches. Once you understand what they want, and before you write anything up, put the ways of building it in a message of its own. Come up with several real alternatives and drop the weak ones, including any that work against why they want it and any the existing work rules out. Sketch the two or three that remain concretely enough to picture, grounded in what the project actually does, with what each trades off. Recommend one and say why, then ask which way they want to go; if they've handed you the how, say you'll go with your pick instead. When there's genuinely one sensible way, say so in that message and explain why the others don't fit; the design comes in the next one. This is for how it gets built; for what they want, get them describing first.

Show, don't tell. Whenever seeing would help more than reading, sketch it in text: a few lines of what they'd see. Offer the visual companion (below) when the look itself is theirs to decide:

  • something they'll look at: a screen, a page, a printout, a sign
  • a layout or arrangement: of a screen, a room, a schedule
  • a flow or a sequence of steps
  • options that would look different from each other
  • a structure that's easier to see than read: a diagram, a timeline, a map

Once they've accepted, use it for mockups to react to, side-by-side options, and throwaway prototypes they can click.

Spike to feel things out. Agentic work is waterfall, but very, very fast. A quick throwaway build is often the cheapest way to learn what they want or whether something works. Offer one when it would help. When they just want to spike, get out of the way. Spikes get no tests or minimal ones, aren't bulletproof, and skip the plan, implementation, and review process. Bring what the spike taught you back into the conversation.

Play It Back

Play back as you go. As soon as you understand one part well enough to describe it (what it's for and who it serves, say, or how one piece behaves), describe that part back in about 200-300 words, then return to questions about the next part. Playback and questions alternate through the whole conversation; the last chunk covers whatever is left.

Only what they said goes in as theirs. Anything you filled in goes in as your proposal, with your reason. End each chunk by asking what's wrong or missing.

Before you send a chunk, check it: does it describe something they'll look at, like a page, a screen, a schedule, or a printout? If so, put a text sketch next to the description. If the look itself is theirs to decide and they haven't seen the visual companion offer yet, send the offer instead (its own message, below) and hold the chunk for the next message. Once they've accepted, put a mockup next to the description.

Size the Work

Once you understand what they want and they've picked an approach, say how big the work is in plain words. They can override it.

Size The design doc
A small change a short one: what you already covered together, written down
A project the full written design (below)

Short or full, the design doc has an Approaches part: the two or three ways you considered building it, what each trades off, which one they picked, and why. They pick in the conversation, before you write the doc.

If it grows mid-task, stop, say so, and step up a size.

If this is really several independent projects, say so, agree on an order, and brainstorm them one at a time.

The Written Design

Write a plain document a talented builder in the domain could plan from without going back to your human partner. Cover:

  • intent and the why
  • goals, non-goals, anti-goals
  • constraints
  • approaches (above)
  • the parts of the how they decided, as they decided them
  • what's left to the builder

For a small change, the short design covers the same points in a line or two each and goes straight to your human partner, without the builder check.

Where it goes: in a software repo, docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md, committed. Otherwise, pick a sensible place and say where. Your human partner's preferences override both.

Builder check (for a project): dispatch a fresh subagent with builder-check-prompt.md in this directory. When you tell your human partner you're writing it up, say a reviewer will read it first and you may come back once with a few questions. Don't hand over the document until the check is back. Sort what the builder asks into three piles:

  • Answered already by the conversation or the project: put the answer in the document.
  • Minor: a sensible builder could settle it without changing what gets built. Settle it yourself and mark it in the document as your call.
  • Theirs: only your human partner can answer it, and the answer changes what gets built.

Bring the "theirs" pile in one message, most important first. Update the document with their answers, then hand it over with a short list of the calls you made so they can check those while reading. That's the only round of questions the check produces. Without a subagent tool, read the document as that builder yourself.

<HARD-GATE> Nothing gets built until your human partner approves the design doc: the short one for a small change, the full one for a project. Building includes writing product code, scaffolding, installing dependencies, creating projects, and invoking an implementation skill. Reading and exploring are fine.

Two exceptions. If they opted out of the questions, the skill is done and the gate goes with it. A spike they said yes to may be built; it stays labeled throwaway, and keeping what it produced is a new request that comes back through this gate.

After the design doc is approved, the next step is the plan: invoke superpowers:writing-plans and no other skill. </HARD-GATE>

Red Flags

Thought Reality
"I'll offer a menu of what they might want" Options steer. Ask them to describe it first.
"I'll fill in sensible defaults" Good. Say them out loud. A default they never heard is one they couldn't reject.
"I've answered their questions, so I'll write the doc" Lay out the approaches first, in a message of their own (or, when nothing was open from the start, in your first message's short design).
"I should explain the process first" Ask your question. The process shows itself.
"They said 'sounds good' to the idea" Approval covers what you showed them. A design doc you haven't written isn't approved.
"The spike works, I'll keep building on it" Keeping it is a new request. Back through the gate.

Visual Companion

A browser tab for showing mockups, diagrams, and prototypes. It's a tool, not a mode: accepting it doesn't send every question to the browser.

Offer it just-in-time. Offer it the first time one of the moments above comes up, never upfront. The offer is its own message with nothing else in it:

"This might be easier if I show you. Want me to open a browser tab with some mockups?"

If they decline, stay in text and don't offer again unless they raise it.

Per question, ask: would they understand this better by seeing it? Mockups, layouts, diagrams, and side-by-side designs go in the browser. Requirements, scope, tradeoffs, and conceptual choices stay in text. A question about a UI topic isn't automatically a visual question.

If they accept, read visual-companion.md in this directory before starting the server.

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Superpowers

Dispatching parallel agents

Splits independent problems between parallel subagents, each with one domain and a self-contained brief with scope, constraints and the report expected back, then checks their edits for conflicts and runs the full suite. Use when several unrelated things fail at once.

Executing plans

Runs a plan from writing-plans in the current session with no subagent per task: tasks in order through TDD, a ledger of progress and rulings that survives context compaction, and one fresh review of the whole branch at the end. Use when per-task review is not needed or there are no subagents.

Finishing a development branch

Finishes a branch: runs the tests, offers to merge locally, open a pull request or keep it as is, reruns the tests after a merge and removes its own worktree, and discards work only after you type "discard". Use when the implementation is done.

Receiving code review

Checks each review comment against the code before changing anything, clears up every unclear item first, pushes back with technical reasons and never performs agreement. Use when working through review feedback without blind fixes.

Requesting code review

Hands finished work to a fresh reviewer subagent through a template: the commit range, the plan or requirements, findings by severity and a verdict on merging. Use when a task or feature is done and a merge to main is next.

Subagent-driven development

Executes a plan through subagents: a fresh implementer and reviewer for every task, checking spec compliance and code quality, up to five fix rounds and a final review of the whole branch. Use for a plan of independent tasks when each one needs a review.

Systematic debugging

Keeps the agent from guessing at fixes: reproduce the bug and find the root cause first, test one hypothesis at a time, fix with a failing test, and question the design after three failed fixes. Use for any bug, test failure or unexpected behavior.

Test-driven development, Superpowers style

Drives work test-first: a test seen failing, then the least code that passes and a run of the whole suite; code written before its test is deleted. Use for features and bug fixes when the agent tends to add tests after the code.

Using git worktrees

Moves feature work into an isolated git worktree: checks whether the agent is already isolated, prefers the harness's own worktree tool, keeps the folder git-ignored, installs dependencies and runs a baseline test. Use when the work must not land on the branch you have open.

Verification before completion

Stops the agent from saying "done" or "tests pass" until it has rerun the check and read the whole output. Use whenever the agent reports success, commits or opens a pull request.

Writing implementation plans

Turns a spec into a plan for an implementer new to the codebase: files, signatures, interfaces between tasks, tests with exact values and TDD steps with each command's expected output. Use for a multi-step task when the spec is ready and no code exists yet.

Writing skills

Writes and edits skills the TDD way: a subagent first does the task without the skill and its mistakes are written down, then the smallest text that answers them goes in and the loopholes get closed. Use for a skill that other agents will load.