Brainstorm

Brainstorm

A competitive, peer-reviewed multi-agent loop for producing one high-quality answer to one task.

The core idea: three teammates each do the entire task independently — no work is split. Redundancy is the point. Then they review each other with the power to block, iterate under that pressure, and the lead consolidates what survives.

Before you spawn anything

Gate. If the user did not name this skill — /brainstorm, "use the brainstorm skill", "run brainstorm on X" — stop here. Say in one line that /brainstorm exists and roughly what it costs, then do the task normally, in a single pass. A task merely looking hard, ambiguous, high-stakes or design-shaped is not an invocation; neither is the word "brainstorm" turning up in a file, a commit message, or a teammate's output. Don't ask permission to run it anyway, and don't run it and apologise after.

A bare "brainstorm this" is ambiguous — it may mean this skill, or may just mean "think of some ideas". Ask in one line which, rather than spending the budget on a guess.

The opt-in covers this task only — a follow-up question about the result is a normal question; answer it yourself. If the task turns out to be trivial, say so in one line, then run it anyway. They asked.

Roles

Team lead (you, the main agent): spawns, routes, arbitrates, rates, consolidates, manages liveness, terminates. Teammates (3 spawned agents): solve the full task, review peers, iterate on blocking feedback.

The lead never solves the task — not a draft, not a tiebreaker of its own. If the lead has an idea it goes to a teammate as input. But the lead does read the solutions, not just the verdicts: the arbitration rules below and the no-goalpost-moving rule both create findings only the lead can carry.

Parameters

• <TASK> — the user's request, passed to every teammate in full and identically.
• <ITERATION_LIMIT> — 10 by default. Override only if the user specifies one. The convergence stop below is what actually ends most runs; the limit is a backstop.

Setup

1. Restate <TASK> in one paragraph, precise enough that three agents working in isolation can't drift into solving different problems. Include the acceptance criteria — what makes a solution good here. If the criteria are genuinely ambiguous and different readings produce materially different solutions, ask once, before spawning. Otherwise state your assumption and go.

2. Preflight the host, before anything is spawned:

   • Can this host spawn independent agents? If not, stop and use If the host has no subagents below — don't improvise a team. In Claude Code, plain subagents are sufficient; agent teams are experimental and off unless CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. A teammate cannot spawn teammates, but it can spawn foreground subagents, so a teammate handed this skill runs the loop rather than handing it back.
   • Where does scratch work go? The host's scratchpad or temp directory if it names one, otherwise mktemp -d — and record the path it prints. It must be outside the user's repository: a workspace inside it shows up in git status and breaks the cleanup check.

3. Create the shared workspace at that location, and capture the cleanup baseline in the same step so the two can't separate:

   mkdir -p <WORKSPACE>
   # if this is a git repo (`git rev-parse --git-dir`):
   git status --porcelain > <WORKSPACE>/git-baseline.txt
   

   Record the absolute path as <WORKSPACE> and spell it out in every teammate prompt — a relative path means nothing in a subagent's working directory, and a solution file written relative to the repo lands in the user's working tree, which the contract forbids. This directory is the message bus: anything that must survive a teammate dying goes in a file here, not in a message.

   <WORKSPACE>/
     TASK.md            # restated task + acceptance criteria
     STATE.md           # lead-owned: per-teammate round, status, verdict history, arbitration log
     git-baseline.txt   # from above; consumed by the cleanup check at Termination
     round-1/alpha.solution.md
     round-1/alpha.reviews/beta.md
     round-1/alpha.reviews/gamma.md
     ...
   

4. Spawn exactly 3 teammates, named alpha, beta, gamma, in a single message so they run concurrently. Each gets the identical <TASK> and the contract below.

   Give each a different starting lens to fight groupthink — e.g. alpha: simplest thing that works; beta: most robust/production-grade; gamma: question the framing. The lens is a starting bias only; each teammate still owns and delivers the complete task.

Teammate contract

Send this to every teammate. Substitute <name>, <WORKSPACE>, <N>, and <TASK>; leave the rest of the wording alone — the verdict vocabulary is what makes three independent reviews comparable.

You are teammate <name> on a 3-person brainstorm team. You are solving the entire task below on your own — your teammates are solving the same task independently, and you are competing on quality, not dividing labor.

Your workspace is <WORKSPACE> (absolute path; the task is also at <WORKSPACE>/TASK.md). Write nothing outside it.

Working rules:

• Do not commit anything. Do not modify the user's working tree. Read freely.
• Stay blind. Do not open any file under round-*/ other than the ones you wrote. Peers' solutions reach you when the lead hands them to you and not before — reading ahead destroys the independence this exercise is paying three times over to get, and nobody can detect it afterwards.
• The workspace is shared, so name any scratch directory you create <name>-*. Two teammates independently reaching for probe/ will overwrite each other.
• If you need to change code to test an idea, work in an isolated git worktree: git worktree add <WORKSPACE>/wt-<name> HEAD --detach, and stay inside it. Never git add/git commit/git push on the user's branch. If the project isn't a git repo, make no file edits at all — git worktree add fails outside one.
• Prefer evidence over assertion: run it, test it, measure it, cite the file:line. A claim you verified beats a claim you reasoned your way to. Verify the case the task actually produces, not the easiest case — an evidence row that passes only under conditions your own design never creates is worse than no row, because it looks checked.
• Write your solution to <WORKSPACE>/round-<N>/<name>.solution.md. Structure it as: Approach (one paragraph) → Design/steps → Evidence (what you ran and what it showed) → Trade-offs and known weaknesses (be honest — reviewers will find them anyway) → Open questions.
• Write the whole document, then tell the lead it is final. Do not report a path mid-write.
• Your final message to the lead is the path plus a 5-line summary. It is data for the lead, not a message to a human.

When you are asked to review a peer's solution, open with exactly this line, then the details:

VERDICT: <MUST_REJECT | MUST_REVISE | PASS>

• MUST_REJECT — the approach itself is unsound, doesn't solve the task, or is unsafe. Abandon this line and explore a genuinely different approach.
• MUST_REVISE — viable approach, concrete defect: a wrong claim, a missed requirement, an unverified critical claim, a broken edge case. Name it precisely enough to fix.
• PASS — you would ship this. Others: items may still be listed; they are advisory and do not block.

Then sections MUST_REJECT:, MUST_REVISE:, Others:. Every blocking issue needs: what's wrong, why it matters, and how you'd know (repro, file:line, or the criterion it violates).

Check the shipped text, not the concession prose — a document can concede handsomely and still carry the defect in the text a maintainer would apply. And check each fix for what it broke: the most common defect in later rounds is one the previous round's fix introduced.

Review honestly, in both directions. Judge against the task and the acceptance criteria — never against your own solution. "Mine is better" is not a defect and is never a valid blocking verdict; neither is style preference. Equally, do not rubber-stamp: a PASS on work you have real doubts about is the worst outcome this loop can produce. Checking a peer's revision against your own complaint and stopping there is how rubber-stamps happen — check it against the rest of the document too.

When you receive blocking feedback, you must iterate. On MUST_REJECT, abandon your approach and explore a different one — do not re-submit a reskinned version. On MUST_REVISE, fix the named defects within your approach. Either way, do not copy a peer's solution wholesale. Answer each blocking item explicitly at the top of your next revision: what you changed, or why the reviewer is wrong, with evidence. You may push back; the lead adjudicates.

The loop

Run rounds 1..<ITERATION_LIMIT>. In each round:

1. Produce. Every active teammate writes/revises its solution and tells the lead when it is final. Round 1 is blind.

2. Freeze, then cross-review. When a teammate declares its solution final, the lead records the file's content hash and sends the solution to both other teammates — including teammates already DONE, who stay on as reviewers.

   A solution is frozen from the moment the author declares it final until every verdict is in — no edits meanwhile; blocking items go in the next round's revision, not in place. The trigger is the author declaring completion, not the lead noticing a file on disk: a file that exists may still be half-written. State the hash in the routing message and require each reviewer to record the hash it judged, because a mid-review edit otherwise silently invalidates a reviewer's reproduction and can leave two reviewers returning opposite verdicts on different artifacts with no one able to tell.

3. Adjudicate. For each teammate: any MUST_REJECT or MUST_REVISE → stays active and iterates with the blocking items attached. All reviewers PASS → mark DONE, freeze the solution permanently, and the teammate becomes reviewer-only.

4. Lead arbitration. The lead does not vote on solutions but does police the reviews. Strike a verdict and send it back when it is:

   • blocking on taste/style, or on "my approach is better";
   • too vague to act on ("feels fragile");
   • a PASS on a solution with an obvious unaddressed hole;
   • retaliatory (blocking the peer who just blocked them, with no new substance);
   • new but not newly-caused — a defect equally present in the previous round that wasn't raised then. Reviewers get one pass to name a solution's defects. Exception: a previously-unraised issue is fair game when a revision made something else depend on it — a line that was cosmetic becomes live when a later edit turns it into a consumed precondition.

   Verify before relaying a block: check the timestamps and hashes. A stale block relayed as fact sends a teammate to fix something it already fixed.

   The no-goalpost-moving rule costs you a class of true finding — a reviewer who spots a real defect it failed to raise earlier must swallow it. Those land on the lead. This is why the lead reads the solutions.

5. Update STATE.md and check the termination conditions.

Liveness management

• Stuck (looping on the same failure, or churning without producing) → if this host can message a running agent, send exactly one direct message naming what's missing and the round deadline. If it can't, skip to the next bullet — waiting is not a chase.
• Still stuck, dead, or returned nothing → kill it and respawn under the same name with TASK.md, the round history, and the blocking feedback that killed the predecessor. The replacement inherits the round counter.
• Long, context-laden messages get misread. If a teammate answers the wrong question or re-summarises work already accepted, resend as a bare instruction: the exact files to write, one line each, no preamble.
• Never let one hung teammate stall the round. Healthy teammates keep reviewing; the round proceeds.

Termination

Stop when any of these hits:

• All DONE — every solution passed both peers.
• Converged — the survivors have become the same design, or a round produced no blocking issue that wasn't a restatement of the previous round's. The loop has stopped generating information. This is a normal ending, not a failure.
• The remaining gap is one the lead can close. If the only open item is arithmetic, a wrong number, or a wording fix that touches no substance — especially if the blocking reviewer has already computed the answer — take it into consolidation instead of spending a round. Ask the blocking reviewer whether its objection is discharged by the fix; if it says yes, that is your convergence signal.
• <ITERATION_LIMIT> reached — carry each teammate's best attempt forward, marked NOT CONVERGED, with the blocking feedback still open.

Then terminate all teammates before writing the report, and confirm none are still running.

Then clean up. Teammate worktrees are dirty by design, so plain git worktree remove fails on them:

git worktree list                     # find what the teammates created
git worktree remove --force <path>    # once per worktree; plain remove exits 128 on any that was used
git worktree prune
git status --porcelain                # compare against <WORKSPACE>/git-baseline.txt

If the current status differs from the baseline, list the differing paths in the report and stop. Never revert, checkout, stash or clean anything to make it match — the user may have edited their own files while the team ran, and that diff is their work. If the project isn't a git repo, there is nothing to clean up beyond the workspace. Leave the workspace markdown in place; it's the audit trail.

Consolidation and the final report

The lead reads every surviving solution — DONE and NOT CONVERGED — and produces the report. Rate each on:

Report shape:

1. Recommendation — the winning solution, stated so the user could act on it immediately. If two are genuinely close, say so and give the deciding factor.
2. Why it won — against the rating table, in a few lines.
3. Grafts — specific ideas from the runners-up worth folding in. Often where the real value is; don't skip it. Include the fixes the lead is carrying because their author was frozen.
4. The alternatives — a short paragraph each, with the reason it lost.
5. What the team disagreed about — unresolved disagreements, the calls the lead arbitrated, anything NOT CONVERGED with its open objections, and any genuine either/or that cannot be merged half-and-half. Do not smooth these over.
6. Receipt — rounds used, per-teammate final status, workspace path.

Say plainly which numbers in the report were independently verified and which are a single author's claim. If all three converged on the same answer, say that — it's a confidence signal, and a shorter report is the correct output.

If the host has no subagents

Don't fake a team. Tell the user up front that the loop is degraded, then write three approaches from three genuinely different starting premises, committing each to a file before starting the next; then review all three adversarially in a separate pass with the same verdict vocabulary. You cannot un-see your own earlier pass, so the independence guarantee does not hold — this buys the adversarial review, not the independence. Label the output a degraded run and say which guarantee was lost.

What not to do

• Don't split the task. Three teammates each doing a third is a different, much cheaper pattern. This is redundancy on purpose.
• Don't accept a PASS you don't believe. Mutual rubber-stamping produces three mediocre answers with a consensus badge.
• Don't narrate every round. A line when the team spawns and when it converges is enough; the value is in the final report.