git:20260928.38649c8 to git:20261005.53e43d7

---

name: brew-idea

description: Runs a multi-agent debate over a project idea. Four angle agents (product, engineering, skeptic, market research) propose and rebut, one judge ranks features keep / improve / add / cut with a phased plan, one designer turns the verdict into flows, screens, data and architecture, and the result becomes a markdown spec plus a design artifact like jump-start's. Use when the developer runs /opm:brew-idea <brief>, says "brew this idea", asks to brainstorm a project with several agents, or wants a project idea improved before designing it.

argument-hint: <project brief>

disable-model-invocation: true

---

# Brew-idea

One brief in, an argued-over design and plan out. The debate decides; the

page shows the product it decided on, not the argument. The developer is

involved at two points: the brief, and approving the result. Everything in

between runs without questions.

**Announce at start:** "Using opm:brew-idea; four angles will argue, one judge decides."

Invocation text is in `$ARGUMENTS`. The workflow script lives next to this

file: `${CLAUDE_PLUGIN_ROOT}/skills/brew-idea/scripts/brew.workflow.js`.

Template: `templates/spec.md`.

This skill needs the Workflow tool. If it is not in the tool list, stop and

say: "brew-idea needs the Workflow tool, which is not available in this

session." Do not imitate the run with Agent calls.

## Gates

| Gate | Passes only when |

|---|---|

| G1 Brief | A brief of about 15 words or more, or the one allowed question was answered |

| G2 Result | The workflow returned `completed: true` |

| G3 Approval | The developer chose "Approve" on the latest revision, not an earlier one |

## Phase 0: parse

1. The brief is all of `$ARGUMENTS`. If it is shorter than about 15 words, ask

one question: "What should it do, for whom, and on which platform (web,

mobile, API)?" Append the answer to the brief. No other questions.

2. `projectRoot` is the current directory, absolute.

3. `hasCode` is true when the directory contains source files outside

`node_modules`, `.git` and `docs` (check for a package manifest or any

`.ts`, `.js`, `.py`, `.dart`, `.go` file). Say which mode the run is in.

4. `slug`: the directory name when `hasCode`, otherwise the first three

meaningful words of the brief (skip articles and "app", "for", "with") in

kebab-case. `date` is today as `YYYY-MM-DD`.

5. Tell the developer: the four angles, that the run asks nothing, that it

takes roughly ten to twenty minutes, and that the result comes back as a

design page to approve.

## Phase 1: launch

Invoking this skill is the opt-in the Workflow tool requires; do not ask again.

```

Workflow({

scriptPath: "<plugin root>/skills/brew-idea/scripts/brew.workflow.js",

args: { projectRoot: "<abs path>", brief: "<brief>", hasCode: <bool> }

})

```

Record the runId. Wait for the task notification; do not poll.

Result shape: `{ completed, reason?, facts, proposals, rebuttals, verdict, design, missingAngles, silentAngles }`

with `verdict = { vision, features: [{ title, decision, reason, votesFor, votesAgainst, impact, effort }], plan: [{ phase, goal, features, risks }], cut: [{ title, reason }], openQuestions, assumptions }`

and `design = { pitch, goals, nonGoals, successSignal, personas: [{ name, need, flow }], surfaces: [{ name, kind, purpose, delivers, layout, states }], navigation: [{ from, to, via }], dataModel: [{ entity, fields, relations }], architecture: [{ part, runsOn, role }], stack: [{ choice, reason }], assumptions }`.

`completed: false` fails G2. Report `reason` in one line and offer to

relaunch with `resumeFromRunId` (finished phases replay from cache). Do not write a spec or a page.

Read the returned object only. Never open a subagent transcript.

## Phase 2: write the spec

Write `docs/specs/<date>-<slug>-brew.md` from `templates/spec.md`:

- Vision and Design from `design`: one block per surface with its `layout`

lines in a code fence, in the order a user meets them.

- Features in the judge's order, one row each, with `votesFor` and

`votesAgainst` as comma-separated angle names.

- One plan section per phase.

- Every entry in `verdict.cut`.

- `missingAngles` and `silentAngles` become an assumption line each

(returned nothing, or proposed but never rebutted).

- Assumptions: `verdict.assumptions` then `design.assumptions`.

- Why these choices: one or two sentences per angle from its proposal and

rebuttal: its position and the argument that changed the result. An angle

in `missingAngles` gets "returned nothing".

- Run: angles present, count of ideas with `unverified: true`, revision count.

Keep it tight. The renderer reads it next, and implementers read it later.

## Phase 3: render

Dispatch one renderer and record its agent id, revisions resume it:

```

Agent (subagent_type: general-purpose, model: opus)

description: "Render brew-idea design page"

prompt: |

Render <abs spec path> into <abs projectRoot>/docs/brew/<slug>.html as a

design artifact in the style of

<plugin root>/skills/jump-start/templates/design-outline.md: one

self-contained page, inline CSS and inline SVG only, no external scripts

or stylesheets, readable at 400px width, title "<slug> brew". Plain

language a non-engineer can follow; the wireframes and diagrams carry the

weight, text stays short. Sections in this order:

1. Overview: vision, pitch, goals, not doing, success signal.

2. Who uses it: one card per persona with its flow as numbered steps.

3. Screens: one low-fidelity wireframe per surface, drawn from its layout

lines as bordered boxes top to bottom (a terminal box for a command, a

request/response box for an endpoint), with purpose, the features it

delivers and its states underneath.

4. How screens connect: an SVG navigation map from the navigation table.

5. Data: entity boxes with fields and relation lines.

6. Architecture: an SVG diagram of the parts and where they run.

7. Stack: choice and reason.

8. Plan: phases in order as a horizontal timeline, each with goal,

features and risks.

9. Decisions: one compact table of features with decision, impact and

effort; then Cut and why.

10. Open questions and assumptions, in a box headed "Challenge these

before approving".

11. Why these choices: collapsed in <details>, one line per angle.

Mark unverified market claims "not checked online". Invent nothing: if the

markdown does not say it, the page does not show it. Do not commit, do not

dispatch subagents. Report in at most three lines: sections rendered and

anything you could not render and why.

```

If the renderer fails, the spec still exists. Say so and offer to retry.

Publish:

- Artifact tool available: load the `artifact-design` skill, publish

`docs/brew/<slug>.html` with the title "<slug> brew", and republish the same

file on every revision so the link never changes.

- No Artifact tool: `open` the file (macOS) or `xdg-open` (Linux).

## Phase 4: approve

Repeat until approved:

1. Share the link and three lines, nothing more: the vision; "N features,

M plan phases, K cut"; the first plan phase. Everything else lives on the

page. Do not paste the verdict, the design or the debate into the chat.

2. Ask with AskUserQuestion: "Approve" or "Request changes" (free text).

3. On changes: relaunch with the same `scriptPath`, `resumeFromRunId`, and the

same `args` plus `feedback: "<the developer's text>"`. Scout, propose and

debate replay from cache; only the judge and the designer rerun. Rewrite the spec from the

new verdict, SendMessage the renderer ("The markdown at <path> changed:

<what>. Re-render and report."), republish, list what changed in three

bullets, ask again. Every revision gets its own question.

4. On approval: commit the spec and the page:

`docs(brew): <slug> brew-idea result`.

## Phase 5: finish

Tell the developer the next step:

- `opm:writing-plans` with the spec path when the project exists and the plan

fits in a week.

- `opm:milestone-planning` when the plan has several phases.

- `opm:jump-start <name> <brief>` when the project does not exist yet; paste

the vision and the add features into the brief.

## Errors

| Situation | Do |

|---|---|

| Workflow tool missing | Stop and say so. No Agent-call imitation |

| `completed: false` | Report `reason`, offer to relaunch with `resumeFromRunId`. No spec, no page |

| `missingAngles` not empty | Continue; note the angle in Assumptions and in the page |

| `silentAngles` not empty | Continue; the judge is told, note it in Assumptions |

| Market angle reports `webSearchUsed: false` | Note in Run that market claims were not checked online |

| Renderer fails | Keep the spec, say so, offer to retry the render |

| Developer interrupts the run | On the next invocation in the same directory, if a runId is known, relaunch with `resumeFromRunId` |

## Red flags

| Thought | Reality |

|---|---|

| "I'll run the angles with Agent calls, Workflow is overhead" | The workflow is the contract: fixed rounds, resume on change requests. Stop if it is missing. |

| "The skeptic only says no, the judge can skip it" | Every high-severity attack gets a mitigation or the feature is cut. That is the point of the skeptic. |

| "The debate is the interesting part, put it up front" | The developer approves a product, not an argument. Debate stays collapsed. |

| "I'll render the HTML myself" | Dispatch the renderer on opus. The main thread writes markdown, not SVG. |

| "They approved the last version, this tweak is fine" | Every revision gets its own approval question. |

| "The market claims sound right, no need to flag" | Unverified stays unverified in the spec and on the page. |

| "One quick question to the developer mid-run" | The run asks nothing. The judge lists open questions instead. |

## Safety

- Read-only against the project: the run creates nothing outside `docs/specs/`

and `docs/brew/`, and commits only on approval.

- Nothing leaves the machine except the market angle's web searches and the

artifact publish, which is private by default.