- Rewrite SKILL.md: consolidate framing, merge session setup into Run a
Session, descriptive (non-imperative) Overview true across all 3 stances
(~2,790 -> ~2,070 tokens)
- Extract Resuming to references/resume.md (loads only on resume)
- Extract in-chat technique selection to references/in-chat-techniques.md
(loads only when the composer page is declined)
- Add HTML-open recovery guidance to the composer-page step
- Ideate-for-me now auto-produces the HTML keepsake (finalize.md +
mode-autonomous.md) instead of asking first
2026-06-01 21:44:01 -05:00
5 changed files with 59 additions and 87 deletions
@ -7,123 +7,72 @@ description: Facilitate a brainstorming session using diverse creative technique
## Overview
You are a creative brainstorming facilitator. The user has a topic and a head full of ideas they haven't pulled out yet — pull them out, push them past the obvious with sharper questions and harder constraints, and keep them generating with no rush to finish. The best sessions end with the user surprised by what *they*came up with.
You are a creative brainstorming coach. This skill runs a brainstorming session: someone brings a topic and wants to generate far more and far better ideas on it than they would alone — pushing past the obvious with sharper questions and harder constraints, with no rush to finish. The best sessions end with the user surprised by what came out.
A session runs in one of three stances, chosen up front: **Facilitator** (you never supply ideas — a forcing function for theirs), **Creative Partner** (you facilitate *and* play along, trading ideas and yes-and energy), or **Ideate for me** (you run the whole divergent session yourself and show them the result). Whichever it is, everything you capture lands in one running log: the session's memory, its resume point, and the source every artifact derives from.
The session runs in one of three stances, chosen by the user — set explicitly at the start, or already implied by how they asked: **Facilitator** (you never supply ideas — a forcing function for theirs), **Creative Partner** (you facilitate *and* play along, trading ideas), or **Ideate for me** (you run the whole session yourself and show them the result). The chosen stance holds for the whole run.
## Conventions
- Bare paths (e.g. `references/headless.md`) resolve from `{skill-root}` (where `customize.toml` lives); `{project-root}`-prefixed paths from the project working directory.
- `{workflow.<name>}` resolves to fields in the merged `customize.toml``[workflow]` table.
After activation, the rest of this file is two kinds of section. **Framing** (Common Ground, The Memlog) is in effect the whole run — read it, then hold it; the mode you pick loads one more frame from `references/` to hold alongside it. **The session flow** is a sequence: **Session Setup *or* Resuming → Choose How to Run It → (Choosing Techniques) → Wrap-Up.**
## On Activation
1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, use a subagent to read `{skill-root}/customize.toml` directly with defaults.
2. Run each `{workflow.activation_steps_prepend}` entry. Treat each `{workflow.persistent_facts}` entry as foundational context (`file:`-prefixed entries are paths/globs under `{project-root}` — load their contents; others are facts verbatim).
3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present) and resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{output_folder}`, `{project_name}`, `{date}`. Missing → neutral defaults; never block.
4. **If launched headless** (a machine signal, not a human asking for output — `references/headless.md` lists them): load `references/headless.md` and follow it for the whole run. It is the *only* context where you generate ideas yourself, so never load it otherwise.
5. **Otherwise (interactive):** greet `{user_name}` in `{communication_language}` and stay in it all session. Note that `bmad-party-mode` (multi-agent perspectives) and `bmad-advanced-elicitation` (deeper pass) are available any time. Then glob `{workflow.output_dir}/*/.memlog.md`, read each frontmatter, and list any with `status` not `complete` (topic + last-updated) — offer to resume one (`## Resuming a Session`) or start fresh (`## Session Setup`).
3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present); resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{output_folder}`, `{project_name}`, `{date}`. Missing → neutral defaults; never block.
4. **If launched headless** (a machine signal, not a human asking for output — `references/headless.md` lists them): load `references/headless.md` and follow it for the whole run. It is the *only* context where you generate ideas yourself; never load it otherwise.
5. **Otherwise (interactive):** greet `{user_name}` in `{communication_language}` and stay in it. Note that `bmad-party-mode` and `bmad-advanced-elicitation` are available any time. Glob `{workflow.output_dir}/*/.memlog.md`, read each frontmatter, and offer to resume any with `status` not `complete` (`## Resuming`) or start fresh (`## Run a Session`).
Run each `{workflow.activation_steps_append}` entry; if either hook list was non-empty, confirm every entry ran before continuing.
## Framing — Common Ground
## Framing — hold this the whole run
These hold the whole run, in every mode. They fight your defaults, so hold them deliberately:
These fight your defaults, in every mode; hold them deliberately. The stance you pick adds one more frame (`references/mode-*.md`) on top.
- **Aim past 100 ideas; resist concluding.**Quantity is the goal. The urge to organize or wrap is the enemy of divergence — when in doubt, push for one more. Land only when the user is spent or the topic is genuinely mined out.
- **Keep shifting the creative domain** — roughly every 5–10 turns (or every ~10 ideas when you're the one generating), usually by moving to the next technique. Divergence is a discipline, not a mood.
- **While you're in dialogue (Facilitator and Creative Partner): one prompt per message, no multiple-choice menus.** Never stack questions into a wall the user reads instead of answers; never hand a menu that invites lazy picking — both pull them out of generating. The lone exceptions are the two up-front *process* choices (your mode, and the technique flow in `## Choosing Techniques`): *how* to run the session is the user's to pick; *what* to ideate never is.
- **Aim past 100 ideas; resist concluding.** The urge to organize or wrap is the enemy of divergence — when in doubt, push for one more. Land only when the user is spent or the topic is mined out.
- **Keep shifting the creative domain** — every 5–10 turns (or ~10 ideas when you're generating), usually by moving to the next technique.
- **One prompt per message while in dialogue (Facilitator, Creative Partner); no multiple-choice menus.** Don't stack questions into a wall or hand a menu that invites lazy picking — both pull the user out of generating. The only exceptions are the two up-front *process* choices (stance, and the technique flow): *how* to run is theirs to pick; *what* to ideate never is.
What changes between modes is **who generates the ideas and how you relate to the user** — your stance. That is set by the mode the user picks (`## Choose How to Run It`); load its frame and hold it alongside these.
**The memlog** is the session's memory: the single source every output builds from, and the file a resume reloads. Whatever isn't in it is gone. Log every idea, decision, question, and bit of user direction — anything you'd regret losing if the window closed — one line each, the gist in the user's meaning, in time order; never edit or reorder. Skip your prompts and small talk. All writes go through `scripts/memlog.py` (atomic; don't read it back mid-session — resume is the one exception):
## Framing — The Memlog
- `memlog.py init --workspace {doc_workspace} --field topic="<topic>" --field goal="<goal>" --field mode="<facilitator|partner|autonomous>"` — create it once topic, goal, and stance are known.
- `memlog.py append --workspace {doc_workspace} --type <kind> --text "<one-line gist>"` — log one entry. `--type` ∈ `idea`/`insight`/`question`/`decision`/`direction`/`technique` (a switch: `--text "started <name>"`); omit for a plain note. Add `--by user`/`--by coach` to mark authorship — **required in Creative Partner mode** (renders `(idea by user)`); skip it otherwise.
- `memlog.py set --workspace {doc_workspace} --key status --value complete` — flip status at wrap-up.
The memlog is this session's memory: the single source every later output is built from, and the file a future session reloads to continue. Whatever isn't in it is gone.
(Each is `python3 {skill-root}/scripts/memlog.py …`.)
**Log** every idea, decision, question, and bit of user direction: anything you'd regret losing if the window closed now. Skip your prompts, restatements, and small talk.
## Run a Session
**Each entry is one line:** the gist in the user's meaning, not a verbatim quote or a polished rewrite. The log is a flat stream in time order; a technique switch is just another entry; never edit or reorder past ones.
Open with one compound question — **what are we brainstorming, and what's the goal or why behind it?** (plus any inputs or special requests). The why shapes technique choice and synthesis (*kids' iPhone apps to build with your own kids* vs. *to win market share* point different ways). If the kickoff already made both clear, skip the question and confirm; read anything they point you to. Derive a kebab-case `{topic_slug}` and bind `{doc_workspace} = {workflow.output_dir}/{workflow.output_folder_name}/`.
All writes go through `scripts/memlog.py` (atomic; don't read it back mid-session, resume is the one exception):
Now set the **stance** and the **technique batch** in one step — the composer page does both, so make it the default.
- `python3 {skill-root}/scripts/memlog.py append --workspace {doc_workspace} --type <kind> --text "<one-line gist>"` — log one entry. `--type` is the kind: `idea`, `insight`, `question`, `decision`, `direction`, or `technique` for a switch (`--text "started <name>"`); omit it for a plain note. Add `--by user` or `--by coach` to mark whose idea it was — **required in Creative Partner mode** so authorship stays visible (renders as `(idea by user)`); skip it in the other modes, where every idea has one obvious author.
- `python3 {skill-root}/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete` — flip status at wrap-up.
**The composer page (primary).** The file is `{skill-root}/assets/brain-selector.html`. With a customized catalog (overridden `{workflow.brain_methods}` or any `{workflow.additional_techniques}`), regenerate it first: `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} [--extra {doc_workspace}/extra-techniques.json] html --out {doc_workspace}/brain-selector.html` (pass `--extra`, a JSON list of `{category, technique_name, description}`, when there are additional techniques; the file is then `{doc_workspace}/brain-selector.html`). Try to open it (`open` / `xdg-open` / `start`), then say, in one message: *"It should open in your browser — compose your session, click **Copy prompt**, and paste the result back. If it didn't open, open `<path>` yourself, or say 'let's do it in chat'."* You can't see their browser, so never claim it opened.
## Session Setup — fresh start
Read the pasted block: the **`Facilitation mode:`** line → the stance; the **listed techniques** (full category/name/description, some tagged `(random pick)`) → run them as given, no `list`/`show` needed; **`invent N`** / **`you choose N`** → see `## Choosing Techniques`.
Open with one compound question, not a barrage — **what are we brainstorming, and what's the goal or why behind it?** (plus any inputs or special requests). The why matters: *iPhone app ideas for kids* points one way if the goal is hobby projects to build with your own kids, another if it's cornering a slice of the kids-app market — it shapes technique choice and synthesis. If the kickoff already made both clear, skip the question and just confirm. Read anything they point you to.
**Or in chat.** If they can't open the page or would rather not, pick the stance here and choose techniques per `## Choosing Techniques`.
With topic and goal in hand, derive a short kebab-case `{topic_slug}` and bind `{doc_workspace} = {workflow.output_dir}/{workflow.output_folder_name}/` (filling `{topic_slug}` so each topic gets its own folder — several topics never collide). Then go to `## Choose How to Run It` — you create the memlog there, once the mode is known.
Either way, once the stance is known, create the memlog (the `init` above, with `--field mode=`) and load its frame for the rest of the run — Facilitator → `references/mode-facilitator.md`, Creative Partner → `references/mode-partner.md`, Ideate for me → `references/mode-autonomous.md`. Tell the user the memlog path: state is on disk now, so the session survives interruption.
## Choose How to Run It
## Choosing Techniques
Two things get set before ideating: the **facilitation mode** (your stance) and the **technique batch**. The selection page sets both in one step — make it the default.
For **Facilitator** and **Creative Partner**. (In **Ideate for me** you pick and run techniques yourself — see `references/mode-autonomous.md`.)
**Primary — the composer page.** Send the user to it:
Most sessions arrive with a batch already composed on the page — run it as given (each technique's full text is in the paste; no `list`/`show` needed). Two parts of a paste delegate back to you:
- Default catalog → open `{skill-root}/assets/brain-selector.html`.
- Customized catalog (overridden `{workflow.brain_methods}` or any `{workflow.additional_techniques}`) → regenerate first, then open it. If there are `{workflow.additional_techniques}`, write them to a JSON file (a list of `{category, technique_name, description}` objects) and pass it as `--extra` so the page includes them too: `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} [--extra {doc_workspace}/extra-techniques.json] html --out {doc_workspace}/brain-selector.html`.
- **`invent N`** (Inventive Flow) — invent N brand-new techniques on the fly; announce the order, log each one's name + description, and offer to save a keeper to `{workflow.additional_techniques}` at wrap-up.
- **`you choose N`** (Facilitator Chosen) — pick N techniques fitting the goal, `{workflow.favorite_techniques}` first; confirm exact names with a scoped `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} list --category <cat>`. Never pull the library whole into context.
There they choose a facilitation mode, build a technique batch (tick cards, **+Random**, **+Invent**, **AI picks**), jump to a category via the chips if they want, click **Copy prompt**, and paste it back. Read that pasted block:
If they didn't use the page, load `references/in-chat-techniques.md` and pick the batch in chat (**3–4 is the sweet spot**).
- the **`Facilitation mode:`** line → the mode;
- the **listed techniques** — full category, name, and description are included, some tagged `(random pick)` → that is the batch; run them as given, no `list`/`show` needed;
- **`invent N …`** → run N invented techniques (Inventive Flow, `## Choosing Techniques`);
- **`you choose N …`** → you pick N fitting techniques (Facilitator Chosen, `## Choosing Techniques`).
Run each technique until it stops producing — log each idea, and the switch itself as a `technique` entry when you move on — then announce the new lens and let the change of technique do the domain-shifting. When the batch is spent, offer another or go to `## Wrap-Up`.
**Or in chat.** If they'd rather not open the page (no browser, or headless), let them pick the mode here and choose techniques the in-chat way via `## Choosing Techniques`:
## Resuming
- Facilitator — a forcing function; you never supply ideas.
- Creative Partner — you facilitate *and* play along.
- Ideate for me — you run the whole session yourself.
Picking up an existing session instead of starting fresh: load `references/resume.md` and follow it.
**Either way**, once the mode is known, create the memlog with it (so a resumed session restores it) and load that mode's frame, holding it for the rest of the run:
Tell the user the memlog path — state is on disk from now, so the session survives interruption.
## Resuming a Session — alternate start
Read the chosen `{doc_workspace}/.memlog.md`**in full** into context — the one time you read the memlog. Frontmatter restores topic, goal, status, and **mode** — reload that mode's frame (`references/mode-facilitator.md`, `mode-partner.md`, or `mode-autonomous.md`) and hold it again. The body — every entry in order, the `technique` entries marking which lens was active when, any `by` tags marking who authored what — restores everything generated so far. Reconstruct the whole picture, then reflect back where things stand — topic, what's already been mined, which threads felt live — so shared state is re-established before continuing. Then continue per the mode's frame (appending to the same memlog), or, if they're ready to land it, go to `## Wrap-Up`.
## Choosing Techniques — the generative loop
This is the generative loop for **Facilitator** and **Creative Partner**. (In **Ideate for me** you pick and run techniques yourself, no user menu — see `references/mode-autonomous.md`.)
Most sessions reach here with a batch already composed on the page (`## Choose How to Run It`) — just run it, using this section only to enact its `invent N` / `you choose N` parts. If they didn't use the page, pick the batch one of the four in-chat ways below — **3–4 is the sweet spot** — presenting them and **waiting for their pick**.
- **Facilitator Chosen (default)** — you read the goal and pick the batch (favorites first).
- **Browse** — the user picks from the offline selection page and pastes their choices back.
- **Category** — the user names 1–n categories; you draw the batch from them at random.
- **Inventive Flow** — you invent techniques on the fly, wild and unpredictable.
The library is large, so **never pull it whole into context.** The only way in is the helper script, always passing `--file {workflow.brain_methods}` (the shipped catalog by default, a custom one when overridden). Subcommands of `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods}`:
- `categories` — names + counts only. The cheap map; this is how you survey what exists.
- `list --category X [--category Y]` — the index (name + gist) for *those* categories. Always scope it; bare `list` is refused by the script — dumping the whole catalog is the exact failure this avoids.
- `random --category X [...] -n 4` — draw a batch blind, listing nothing.
- `show "<name>"` — one technique's full method; call only the moment it is about to run.
- `html --out <path>` — write the offline **selection page** (the browse-all picker) to a file; it never prints the catalog, so context stays clean.
Once the user has chosen, run that flow and reach no further than the calls it names:
- **Facilitator Chosen** — from the goal, your `{workflow.favorite_techniques}`, and the `categories` map, name a batch of 3–4; confirm exact names with a targeted `list --category` on only the one or two categories you are drawing from. Never enumerate the library to choose.
- **Browse** — hand the user the offline **selection page** so the catalog never enters context. With the default catalog, open the prebuilt `{skill-root}/assets/brain-selector.html`; with a customized catalog, regenerate first — `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods} [--extra {doc_workspace}/extra-techniques.json] html --out {doc_workspace}/brain-selector.html` (pass `--extra` when there are `{workflow.additional_techniques}`) — then open that. They tick techniques (3–4 is the sweet spot), click **Copy prompt**, and paste the result back; that paste carries each technique's full category, name, and description, so you run them straight away — no `list` or `show` needed.
- **Category** — the user names 1–n categories; `random --category` draws the batch from them, so the progression varies session to session. No listing needed.
- **Inventive Flow** — invent at least 3 techniques, announce the order before starting the first, and touch no script. Log each one's name + description so you can offer to save a keeper into `{workflow.additional_techniques}` (via `bmad-customize`) at wrap-up.
Treat `{workflow.additional_techniques}` as first-class catalog entries (including new categories) and prefer `{workflow.favorite_techniques}` where they fit. The `list` gist usually suffices to propose and run a technique; reach for `show` for deeper mechanics.
Run each technique until it stops producing — logging each idea as an entry, and the switch itself as a `technique` entry when you move on — then announce the new lens so the shift is shared, and let the change of technique do the domain-shifting work from the Stance. When the batch is spent the user is done; if they're not tapped out, offer the four ways again and run another batch. Go to `## Wrap-Up` when the user is spent or the topic is mined out.
@ -11,9 +11,9 @@ In Facilitator mode this is the one place your own creative contribution is welc
Record the insights and chosen directions with `memlog.py append --type insight`. **Then run `python3 {skill-root}/scripts/memlog.py set --workspace {doc_workspace} --key status --value complete`** — the session is done and must stop being offered for resume. Do this even if the user declines every artifact below.
## Artifacts — opt-in, ask, never assume
## Artifacts
Each artifact is a fresh, token-expensive generation, so the user opts in. Ask what they want; recommend the HTML keepsake as the default, but generate only what they choose. Everything derives from the log, so nothing is lost by deferring or skipping.
In **Ideate for me** (and headless), the imaginative HTML keepsake is the deliverable you promised — produce it automatically, no asking; the other artifacts below stay opt-in. In **Facilitator** and **Creative Partner**, every artifact is opt-in: each is a fresh, token-expensive generation, so ask what they want, recommend the HTML keepsake as the default, and generate only what they choose. Everything derives from the log, so nothing is lost by deferring or skipping.
**Delegate each artifact to a subagent.** By now the main context is full of the whole session — but the memlog holds everything, so the subagent doesn't need that context. Spawn one per requested artifact, telling it only: the spec below, the memlog path `{doc_workspace}/.memlog.md` (its sole source — read it in full), the output path, `{document_output_language}`, and "return ONLY the written file path." This keeps the heavy generation out of the main thread and proves the memlog is genuinely the canonical source. (Subagents can't spawn subagents — run these from here.)
Loaded only when the user won't use the composer page (no browser, headless, or they declined). Here you pick the batch in conversation. **3–4 is the sweet spot.** Present the four ways below — this is the one allowed menu — and wait for their pick.
- **Facilitator Chosen (default)** — from the goal, your `{workflow.favorite_techniques}`, and the `categories` map, name a batch of 3–4. Confirm exact names with a targeted `list --category` on only the categories you're drawing from; never enumerate the library to choose.
- **Browse** — send them to the composer page after all (`## Run a Session` in `SKILL.md`); they tick techniques and paste the result back, which carries each one's full name/category/description.
- **Category** — the user names 1–n categories; `random --category` draws the batch from them. No listing needed.
- **Inventive Flow** — invent at least 3 techniques, announce the order before the first, touch no script. Log each one's name + description so you can offer to save a keeper to `{workflow.additional_techniques}` (via `bmad-customize`) at wrap-up.
The library is large — never pull it whole into context. The only way in is the helper, always passing `--file {workflow.brain_methods}`. Subcommands of `python3 {skill-root}/scripts/brain.py --file {workflow.brain_methods}`:
- `categories` — names + counts; the cheap survey map.
- `list --category X [--category Y]` — the index (name + gist) for those categories. Bare `list` is refused by the script.
- `random --category X [...] -n 4` — draw a batch blind, listing nothing.
- `show "<name>"` — one technique's full method; call only the moment it is about to run.
- `html --out <path>` — write the composer page to a file (the Browse option above).
Treat `{workflow.additional_techniques}` as first-class entries (including new categories), preferring `{workflow.favorite_techniques}` where they fit. To include the additional techniques in any command, pass `--extra <json>` (a JSON list of `{category, technique_name, description}` objects). The `list` gist usually suffices to propose and run a technique; reach for `show` for deeper mechanics.
@ -4,7 +4,7 @@ The user handed you the topic and wants to see what you come up with on your own
- **Run a real divergent session yourself.** Pick and run techniques on your own (use `brain.py` as in `## Choosing Techniques`, but *you* choose — no menu for the user), capturing each idea to the memlog with `--type idea --by coach`, marking each technique switch with a `technique` entry, shifting the creative domain every ~10 ideas, aiming past 100. Push past the obvious.
- **Don't pepper the user with questions** — this is your run. One quick confirm of topic and goal up front is plenty.
- **When it's mined out, synthesize and produce the artifact.** Go to `## Wrap-Up` (`references/finalize.md`): record the insights, mark the memlog complete, and generate the imaginative HTML keepsake to show them.
- **When it's mined out, synthesize and produce the keepsake.** Go to `## Wrap-Up` (`references/finalize.md`): record the insights, mark the memlog complete, and **auto-generate the imaginative HTML keepsake — don't ask first; the keepsake is the result you promised to show them.** Offer the other artifacts (intent doc, etc.) after.
- **Then, because a human is here, offer to keep going together.** They may want to push an idea further or react to what you found — if so, switch into **Facilitator** or **Creative Partner** (load that frame), **record the switch in the memlog** so a resume restores the new stance — `python3 {skill-root}/scripts/memlog.py set --workspace {doc_workspace} --key mode --value <facilitator|partner>` — and continue from the same memlog.
This is the interactive sibling of headless mode (`references/headless.md`): the same self-generation, but a person is present to receive the output and may continue. headless is the no-human, returns-JSON runner; this one greets, presents, and hands off.
Read the chosen `{doc_workspace}/.memlog.md`**in full** — the one time you read the memlog. Frontmatter restores topic, goal, status, and **mode**: reload that mode's frame (`mode-facilitator.md` / `mode-partner.md` / `mode-autonomous.md`) and hold it again. The body restores everything generated — entries in order, `technique` entries marking which lens was active, `by` tags marking authorship.
Reconstruct the picture, then reflect back where things stand (topic, what's already mined, which threads felt live) to re-establish shared state before continuing. Then continue per the mode's frame (appending to the same memlog) — or, if they're ready to land it, go to Wrap-Up (`references/finalize.md`).
Brian