brainstorm
brainstorm
Claude Code runs it as
/brainstorm and Codex as $brainstorm. Other agents take its name or a plain request such as "brainstorm this".What it does
brainstorm turns an idea that still has open decisions into a reviewed design. It asks you what only you can answer, a few questions at a time, until the problem, the scope, the decisions, the risks and the success criteria are settled. It then writes
.genie/brainstorms/<slug>/DESIGN.md and has a reviewer that did not write it score the design. It changes no code.A brainstorm runs one round at a time, because a saved workflow cannot wait for a person: you answer between rounds. The state of every round lives in
.genie/brainstorms/<slug>/DRAFT.md, so a later run with the same slug picks up where the last one stopped.In each round:
- A lead reads the draft, scores how ready it is for a wish (the Wish Readiness Score, over problem, scope, decisions, risks and criteria) and plans the round.
- Read-only scouts look up the facts in your repository. When one decision is contested and hard to reverse, the lead can convene a council instead: a few lenses argue it, dissent always among them, a Socratic questioner tests each lens, and the lenses answer from evidence before a proposal is written.
- The questions come back to you word for word, through your agent's question prompt. An answer settles only the question it answers; a change to something you already approved comes back as its own question.
When nothing is open, the lead writes
DESIGN.md from the template and the round ledger checks it against the template and the draft. An independent reviewer then returns SHIP, FIX-FIRST or BLOCKED. The verdict is stamped into the design with the digest of the content the reviewer read, so an edit made after the review fails verification. A FIX-FIRST gets one repair and a fresh review per run while the repair budget holds.When to use it
- You have an idea, but the approach, the scope or the boundaries still need decisions.
- The work is bigger than one task, and you want a reviewed design before wish writes the plan.
A task that is already decided goes straight to wish. A failure whose cause is unknown goes to
report first.How a run ends
| State | Meaning |
round | Questions for you. Answer them and run brainstorm again |
done | DESIGN.md carries a verified SHIP stamp. The next route is wish |
answered | You ended the brainstorm with a recorded verdict and no design |
blocked | A ledger refusal you must resolve, a BLOCKED review, a spent repair budget, or your stop. A stop is permanent for that slug |
failed | A stage returned nothing, the ledger could not start, or the review contract is missing |
A round can also ask whether to convene a council past the configured ceiling, or what to do with review findings: repair again, settle them yourself, or stop.
After every run the skill runs
genie wish report <runId> --append, which prints the run's tokens and time per stage. It also keeps the brainstorm's entry in .genie/INDEX.md: under Simmering while rounds run, under Ready once the design is done.Run it
| Agent | How it runs |
| Claude Code | /brainstorm <your idea> runs the saved workflow brainstorm, once per round. See Workflows |
| Codex | $brainstorm <your idea> runs the same rounds by hand, one per turn |
| Other agents | Its name, or a plain request such as "brainstorm this", runs the same rounds by hand |
The council ceiling comes from
genie config get budgets.maxCouncilsPerBrainstorm and the repair budget from genie config get budgets.maxEscalationsPerGroup. The review uses the review skill installed beside brainstorm; a run without it ends failed and names the missing path.A recorded run
Simulated terminal: a replay of a real /brainstorm run in Claude Code, built from its saved capture and shortened in time. Edited in two places: host details hidden (paths shown as ~/, account plan and quota), and the agent launch line removed.
The video and the transcript are in Portuguese, as recorded.
The run was recorded before brainstorm became a saved workflow, so its rounds run inside one session. It ends at a design the reviewer stamped SHIP.
Read the transcript: the redacted text of the run's final screen and scrollback, with each cut marked inline.