From 6252b231d0c0898c596b11aa511c1c935d8f18c7 Mon Sep 17 00:00:00 2001 From: gitgitWi Date: Sun, 17 May 2026 01:32:41 +0900 Subject: [PATCH 1/7] feat(brainstorm): add standalone flow:brainstorm skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extract multi-LLM brainstorming from skills/plan/SKILL.md:52-202 into a first-class skill that: - Owns provider lenses, dispatch contract, idempotency check, and brainstorm.md synthesis template (lifted verbatim from plan). - Resolves input by precedence: research.md + meta.md, else meta.md only, else inline task brief with ad-hoc .planning/-brainstorm-/ output (mirrors the existing pr-review variant). - Carries triggering keywords ("brainstorm", "options", "alternatives", "다각도", "second opinion before planning") in the frontmatter description for Claude Code auto-invocation. flow:plan and flow:research will be trimmed to short pointers in follow-up commits. Resolves the "Future refactor (open question)" note at skills/plan/SKILL.md:200-202. --- skills/brainstorm/SKILL.md | 272 +++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 skills/brainstorm/SKILL.md diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md new file mode 100644 index 0000000..49f8c87 --- /dev/null +++ b/skills/brainstorm/SKILL.md @@ -0,0 +1,272 @@ +--- +name: brainstorm +description: Run a multi-LLM brainstorming round and synthesize a single `brainstorm.md` (plus per-model raw outputs under `brainstorms/`) surfacing architecture options, hidden risks, and security/correctness angles for an upcoming change. Use this whenever the user wants to weigh "options", "alternatives", "다각도로 보자", a "second opinion before planning", or whenever a non-trivial change benefits from diverse perspectives BEFORE the planner commits to a shape. Invoked directly by the user (`/flow:brainstorm`), or as an optional sub-phase from `flow:research` / `flow:plan`. Runs without any prior `.planning/` directory — accepts an inline task brief when needed. +--- + +# flow:brainstorm — Multi-LLM option-generation + +Brainstorm is **option-generation, not decision-making**. The point is to surface +architecture shapes, risks, and security angles BEFORE the planner commits — not +to second-guess a plan after it lands (that's `flow:plan-review`). The output is +`brainstorm.md`, a single synthesized file the planner consults while drafting +`plan.md`. Raw per-model outputs live under `brainstorms/` for audit; the planner +should never read them directly. + +## When to run + +This skill is callable in three contexts; the triggers differ. + +### As a sub-phase of `flow:plan` (most common) + +- **Size L** — always run. +- **Size M** — run when any of: + - The change touches **multiple modules** (cross-module impact flagged in + `meta.md` or surfaced from `research.md`). + - **Security-sensitive surface**: auth, payments, PII, cryptography, file + uploads, anything user-controlled landing in a privileged context. + - **Public surface area** (a new external API endpoint, a published SDK, a + webhook contract). + - The user explicitly asks for "options" / "alternatives" / "다각도로 보자" + before planning. +- **Size S** — skip. One perspective is fine for an atomic edit. + +If unsure for an M task, ask the user one short question. Default-no for plain M, +default-yes for L. + +### As a sub-phase of `flow:research` + +Research suggests brainstorming when its *Candidate approaches* list has 3+ +viable shapes with comparable risk, or when the user explicitly asks for +option-generation. Research itself does not auto-dispatch; the suggestion lands +in `research.md` and the user (or `flow:orchestrate`) decides. + +### Standalone (`/flow:brainstorm`, no prior pipeline) + +The user wants to weigh options on a sketch without committing to a plan yet. No +`.planning/` dir exists. The skill accepts a one-paragraph **inline task brief** +from the user, creates an ad-hoc working directory (see *Input precedence* +below), and runs the same dispatch + synthesis flow. + +## Input precedence + +Resolved at the start of every invocation, in this order: + +1. **`research.md` + `meta.md` exist** in the current + `.planning/-/`. Richest context — read both, dispatch + contributors with both paths. +2. **Only `meta.md` exists.** Same as today's plan-internal flow — dispatch + contributors with `meta.md` only. +3. **Neither exists** (standalone invocation, no `.planning/` dir at all). + Prompt the user inline: + - "I don't see a `.planning/` task directory. Give me a one-paragraph task + brief — what change are you weighing options on?" + - Derive a **slug** from the brief: first 4–6 content words, kebab-cased, + stopwords (`a`, `the`, `for`, `to`, `with`, `and`, `or`) stripped, ASCII + only. Example brief: "Should we move auth tokens out of localStorage into + httpOnly cookies?" → `auth-tokens-localstorage-cookies`. + - Create + `/.planning/-brainstorm-/` (today's date, + local timezone). If the directory already exists for the same date+slug, + append `-2`, `-3` until unique. This mirrors the existing + `.planning/-pr-review/` ad-hoc variant + (`../../references/directory-structure.md#naming-rules`). + - Write a minimal `meta.md` to that directory with `type: meta`, + `size: M` (default — bump to L if the brief clearly warrants), and the + brief copied verbatim under `goal:`. This becomes the input contributors + read. + +`$TASK_DIR` below refers to whichever directory was resolved. + +## Idempotency precondition + +Before dispatching anything, check whether the brainstorm has already run: + +```bash +BRAINSTORM="$TASK_DIR/brainstorm.md" +if [[ -f "$BRAINSTORM" ]] && grep -q '^status: active' "$BRAINSTORM"; then + echo "brainstorm.md already exists (status: active)" +fi +``` + +If it does, **do not silently re-dispatch.** Ask the user: (a) keep the +existing synthesis and exit, (b) regenerate (the existing `brainstorm.md` and +`brainstorms/` files are moved to `brainstorm.v.md` / `brainstorms.v/`, +mirroring the `plan.v.md` versioning convention), or (c) abort. The most +common path after an interrupted session is (a) — re-running the brainstorm +doubles cost and clobbers the audit trail. + +## Provider roles + +Two providers minimum (the `../../references/multi-llm.md` ≥2 quorum); three +when size is L or the user requested a security lens. Each model gets a +**focused lens** so outputs are differentiated, not duplicated. + +- **`gemini-3.1-pro` — Architecture & alternatives.** Surface 2–3 distinct + architectural shapes for the change. Name load-bearing tradeoffs (cost / + blast radius / reversibility). Bring ecosystem analogues. +- **`opencode-go/kimi-k2.6` — Risk & failure modes.** Enumerate what could go + wrong: race conditions, partial states, rollback paths, observability gaps, + regressions in adjacent modules. Be concrete. +- **`opencode-go/deepseek-v4-pro` — Security & correctness** *(size L, or M + with security-sensitive surface)*. Threat-model the change: auth/authz, + injection, data exposure, dependency surface, secrets handling. + +Model IDs come from `../../references/models.md` — if they move, edit there, +not here. + +## How to dispatch + +Follow the full dispatch + verification + quorum pattern in +`../../references/multi-llm.md`. Key points specific to brainstorming: + +- **File-write contract.** Each contributor uses its native Write tool to + write its output to a specific absolute path. The orchestrator captures + stdout to a **runlog** file (diagnostic only — not the review). See + `../../references/multi-llm.md` "Dispatch contract." +- **Sentinel.** Every contributor file must end with + ``. Absent sentinel = treat as failed + even if file size looks reasonable. +- **Heartbeat.** Run `watch_review` (defined in `../../references/multi-llm.md`) + in parallel with each dispatch so progress is visible at 1-minute + resolution. A dispatch without a heartbeat is indistinguishable from a hung + one for 10+ minutes. + +```bash +mkdir -p "$TASK_DIR/brainstorms" + +REVIEW_ARCH="$TASK_DIR/brainstorms/architecture-gemini.md" +RUNLOG_ARCH="$TASK_DIR/brainstorms/_runlog-architecture-gemini.txt" + +# Build the read-list for the contributor prompt. research.md is optional. +READ_LIST="$TASK_DIR/meta.md" +[[ -f "$TASK_DIR/research.md" ]] && READ_LIST="$READ_LIST and $TASK_DIR/research.md" + +( timeout 600 gemini --model gemini-3.1-pro-preview --yolo --skip-trust \ + --prompt "$(cat < +4. Print only: "wrote architecture-gemini.md" + +Your lens: ARCHITECTURE & ALTERNATIVES. +- Propose 2–3 distinct architectural shapes for this change. +- For each: the shape in 2 sentences, and load-bearing tradeoffs (cost / blast radius / reversibility). +- Name relevant ecosystem analogues. +- Surface non-obvious design constraints the planner should know. + +Output format inside the file (Markdown, no preamble): +## Option A — +- Shape: ... +- Tradeoffs: ... +## Option B — +... +## Constraints surfaced +- ... +PROMPT +)" > "$RUNLOG_ARCH" 2> "$RUNLOG_ARCH.stderr"; \ + echo $? > "$RUNLOG_ARCH.exit" ) || true & + +# Run watch_review (from multi-llm.md) in parallel so progress is visible at 1-min resolution. +watch_review "$REVIEW_ARCH" 25 & + +# Same wrapping for risk lens (kimi) — file-write to brainstorms/risk-kimi.md +# Same wrapping for security lens (deepseek) — size L or security-sensitive only + +wait +``` + +Apply the full post-call verification (exit code, non-empty, **sentinel +present**, **structural content present**, no failure signature) and quorum +policy from `../../references/multi-llm.md`. If only one contributor +succeeds, stop and ask the user (re-auth, swap, or proceed labeled +"single-perspective"). + +## Synthesis — `brainstorm.md` + +Read each raw output **once**, extract load-bearing ideas, and write a single +English `brainstorm.md` at `$TASK_DIR/brainstorm.md`. This is what the planner +(or the user, in standalone mode) consults next. + +```markdown +--- +title: "Brainstorm — " +type: brainstorm +task: +task_date: +created: +last_updated: +status: active +size: +parent: ./meta.md +related: + - ./research.md (if exists) + - ./brainstorms/architecture-gemini.md + - ./brainstorms/risk-kimi.md +contributors: + - gemini-3.1-pro + - opencode-go/kimi-k2.6 +missing_contributors: [] +--- + +# Brainstorm — + +## Architecture options +- 2–3 shapes the planner should weigh. One-line tradeoff each. + +## Risks worth designing against +- Concrete failure modes raised by the brainstorm. Short and actionable. + +## Security / correctness angles +- Threat-model bullets that should shape the plan or land as explicit non-goals. + (Omit this section entirely when no security lens was run.) + +## Convergence +- Where models agreed. These are usually safe assumptions for the plan. + +## Divergence (most valuable section) +- Where models disagreed. Each entry: which model said what, and the planner's + current lean — or "open question — needs user" when unresolved. + +## Open questions for the user +- Anything the brainstorm could not resolve. Surface these before drafting the plan. +``` + +## What NOT to do + +- **Don't run brainstorming for size S.** It's noise. +- **Don't paste raw model output into the conversation.** Files only — that's + the whole point of `../../references/multi-llm.md`. +- **Don't let the brainstorm become the plan.** The planner still drafts + `plan.md`. Brainstorm is option-generation; plan is decision. In standalone + mode, `brainstorm.md` is the final artifact — but it still presents options, + not a chosen direction. +- **Don't run brainstorm *and* `flow:plan-review` on the same plan as a + default.** They serve different stages — brainstorm before drafting, + plan-review after. Doubling up is justified only when plan-review surfaces + re-architecting questions that need fresh brainstorming. +- **Don't auto-dispatch from `flow:research`.** Research *suggests*; the user + or orchestrate decides. + +## Handoff + +- **Sub-phase mode**: when invoked from `flow:plan` or `flow:research`, return + to the caller after `brainstorm.md` is written. The caller continues from + where it paused (typically: planner reads `brainstorm.md` and drafts + `plan.md`). +- **Standalone mode**: print the path to `brainstorm.md` and a one-line summary + of the divergence section. The user decides whether to next invoke + `flow:prep` + `flow:plan`, iterate on the brief, or stop here. + +## Reference + +- Multi-LLM dispatch & quorum: `../../references/multi-llm.md` +- Model registry (lenses + IDs): `../../references/models.md` +- Directory layout (including `.planning/-brainstorm-/` variant): + `../../references/directory-structure.md` +- Frontmatter schema (`brainstorm` + `brainstorm-contribution` types): + `../../references/frontmatter.md` +- Doc style (prefer lists over tables): `../../references/doc-style.md` From 96e9467ded3f5c0e8fa531b1d8076fde5b6aae78 Mon Sep 17 00:00:00 2001 From: gitgitWi Date: Sun, 17 May 2026 01:35:26 +0900 Subject: [PATCH 2/7] refactor(plan): delegate brainstorm body to flow:brainstorm skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Collapse the inline "Multi-LLM brainstorming" section (formerly ~150 lines) to a ~40-line "Optional brainstorming sub-phase" pointer: - Keep the size-based trigger matrix (S skip / M conditional / L always), the cross-module / security-sensitive / public-surface flags, and the "ask once when unsure" rule. These are planning-side decisions. - Drop provider lenses, idempotency check, dispatch code, synthesis template, anti-patterns, and the "Future refactor (open question)" note — those now live in skills/brainstorm/SKILL.md. - Update the Output files note for brainstorm.md to credit flow:brainstorm as the author. - Update the Workflow step that decides whether to brainstorm to point at the new section name and the flow:brainstorm invocation. - Add flow:brainstorm to the Reference list. No behavior change for users: the size matrix still triggers the same runs; the invocation simply fans out to a different skill. --- skills/plan/SKILL.md | 184 +++++++++---------------------------------- 1 file changed, 39 insertions(+), 145 deletions(-) diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index eabe2ac..a5556ac 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -45,161 +45,54 @@ All written under `/.planning/-/`: - **`plan.md`** — approach, scope, architecture decisions, rollout. ~500 lines max for the whole thing (including any phase sub-plans). If it grows beyond that, split into `plan-phase-1.md`, `plan-phase-2.md` and let `plan.md` become a short index. - **`tasks.md`** — Given-When-Then checkbox list, the single source of truth for progress during develop. -- **`brainstorm.md`** — *conditional.* Multi-LLM brainstorming synthesis, written before `plan.md` when scope warrants (see "Multi-LLM brainstorming" below). Raw per-model outputs go under `brainstorms/`. +- **`brainstorm.md`** — *conditional.* Multi-LLM brainstorming synthesis, + written by `flow:brainstorm` before `plan.md` when scope warrants (see + "Optional brainstorming sub-phase" below). Raw per-model outputs go under + `brainstorms/`. All authored docs are **English** (any coding agent picks them up). Add a `## Korean summary (요약)` at the bottom of `plan.md` if the user wants to skim it quickly. -## Multi-LLM brainstorming (run when scope warrants) +## Optional brainstorming sub-phase -Before drafting `plan.md`, run a multi-LLM brainstorming round when the change is large enough or cross-cutting enough that diverse perspectives meaningfully sharpen the approach. The point is to surface **architecture options, hidden risks, and security/correctness angles *before* the planner commits to a shape** — not to second-guess the plan afterward (that's `flow:plan-review`). +Before drafting `plan.md`, consider running a multi-LLM brainstorming round. +The point is to surface **architecture options, hidden risks, and +security/correctness angles *before* the planner commits to a shape** — not to +second-guess the plan afterward (that's `flow:plan-review`). -### When to run +The full mechanism — provider lenses, dispatch contract, idempotency check, +synthesis template, anti-patterns — lives in the standalone **`flow:brainstorm`** +skill. This section only documents *when* to invoke it from `flow:plan`. -- **Size L** — always run. Large changes benefit most from multi-angle exploration. +### Trigger criteria + +- **Size L** — always run. - **Size M** — run when any of: - - The change touches **multiple modules** (cross-module impact flagged in `meta.md` or surfaced from `research.md`). - - **Security-sensitive surface**: auth, payments, PII, cryptography, file uploads, anything user-controlled landing in a privileged context. - - **Public surface area** (a new external API endpoint, a published SDK, a webhook contract). - - The user explicitly asks for "options" / "alternatives" / "다각도로 보자" before planning. + - The change touches **multiple modules** (cross-module impact flagged in + `meta.md` or surfaced from `research.md`). + - **Security-sensitive surface**: auth, payments, PII, cryptography, file + uploads, anything user-controlled landing in a privileged context. + - **Public surface area** (a new external API endpoint, a published SDK, a + webhook contract). + - The user explicitly asks for "options" / "alternatives" / "다각도로 보자" + before planning. - **Size S** — skip. One perspective is fine for an atomic edit. -If unsure for an M task, ask the user one short question. Default-no for plain M, default-yes for L. - -### Provider roles - -Two providers minimum (the `references/multi-llm.md` ≥2 quorum); three for size L. Each model gets a **focused lens** so outputs are differentiated, not duplicated. - -- **`gemini-3.1-pro` — Architecture & alternatives.** Surface 2–3 distinct architectural shapes for the change. Name load-bearing tradeoffs (cost / blast radius / reversibility). Bring ecosystem analogues. -- **`opencode-go/kimi-k2.6` — Risk & failure modes.** Enumerate what could go wrong: race conditions, partial states, rollback paths, observability gaps, regressions in adjacent modules. Be concrete. -- **`opencode-go/deepseek-v4-pro` — Security & correctness** *(size L, or M with security-sensitive surface)*. Threat-model the change: auth/authz, injection, data exposure, dependency surface, secrets handling. - -Model IDs come from `references/models.md` — if they move, edit there, not here. - -### Idempotency precondition - -Before dispatching anything, check whether the brainstorm has already run: - -```bash -BRAINSTORM=.planning/-/brainstorm.md -if [[ -f "$BRAINSTORM" ]] && grep -q '^status: active' "$BRAINSTORM"; then - echo "brainstorm.md already exists (status: active)" -fi -``` - -If it does, **do not silently re-dispatch.** Ask the user: (a) keep the existing synthesis and skip the sub-phase, (b) regenerate (the existing `brainstorm.md` and `brainstorms/` files are moved to `brainstorm.v.md` / `brainstorms.v/`, mirroring the `plan.v.md` versioning convention), or (c) abort. The most common path after an interrupted session is (a) — re-running the brainstorm doubles cost and clobbers the audit trail. - -### How to dispatch - -Follow the full dispatch + verification + quorum pattern in `references/multi-llm.md`. Key points specific to brainstorming: - -- **File-write contract.** Each contributor uses its native Write tool to write its review to a specific absolute path. The orchestrator captures stdout to a **runlog** file (diagnostic only — not the review). See `references/multi-llm.md` "Dispatch contract." -- **Sentinel.** Every contributor file must end with ``. Absent sentinel = treat as failed even if file size looks reasonable. -- **Heartbeat.** Run `watch_review` (defined in `references/multi-llm.md`) in parallel with each dispatch so progress is visible at 1-minute resolution. A dispatch without a heartbeat is indistinguishable from a hung one for 10+ minutes. - -```bash -mkdir -p .planning/-/brainstorms - -REVIEW_ARCH=.planning/-/brainstorms/architecture-gemini.md -RUNLOG_ARCH=.planning/-/brainstorms/_runlog-architecture-gemini.txt - -( timeout 600 gemini --model gemini-3.1-pro-preview --yolo --skip-trust \ - --prompt "$(cat </meta.md and (if it exists) the research at /research.md. -2. Write your brainstorm using the Write tool to: $REVIEW_ARCH -3. The LAST LINE of the file MUST be exactly: - -4. Print only: "wrote architecture-gemini.md" - -Your lens: ARCHITECTURE & ALTERNATIVES. -- Propose 2–3 distinct architectural shapes for this change. -- For each: the shape in 2 sentences, and load-bearing tradeoffs (cost / blast radius / reversibility). -- Name relevant ecosystem analogues. -- Surface non-obvious design constraints the planner should know. - -Output format inside the file (Markdown, no preamble): -## Option A — -- Shape: ... -- Tradeoffs: ... -## Option B — -... -## Constraints surfaced -- ... -PROMPT -)" > "$RUNLOG_ARCH" 2> "$RUNLOG_ARCH.stderr"; \ - echo $? > "$RUNLOG_ARCH.exit" ) || true & - -# Run watch_review (from multi-llm.md) in parallel so progress is visible at 1-min resolution. -watch_review "$REVIEW_ARCH" 25 & - -# Same wrapping for risk lens (kimi) — file-write to brainstorms/risk-kimi.md -# Same wrapping for security lens (deepseek) — size L or security-sensitive only - -wait -``` - -Apply the full post-call verification (exit code, non-empty, **sentinel present**, **structural content present**, no failure signature) and quorum policy from `multi-llm.md`. If only one contributor succeeds, stop and ask the user (re-auth, swap, or proceed labeled "single-perspective"). - -### Synthesis — `brainstorm.md` - -Read each raw output **once**, extract load-bearing ideas, and write a single English `brainstorm.md` at `.planning/-/brainstorm.md`. This is what the planner consults while drafting `plan.md`. - -```markdown ---- -title: "Brainstorm — " -type: brainstorm -task: -task_date: -created: -last_updated: -status: active -size: -parent: ./meta.md -related: - - ./research.md (if exists) - - ./brainstorms/architecture-gemini.md - - ./brainstorms/risk-kimi.md -contributors: - - gemini-3.1-pro - - opencode-go/kimi-k2.6 -missing_contributors: [] ---- - -# Brainstorm — - -## Architecture options -- 2–3 shapes the planner should weigh. One-line tradeoff each. - -## Risks worth designing against -- Concrete failure modes raised by the brainstorm. Short and actionable. - -## Security / correctness angles -- Threat-model bullets that should shape the plan or land as explicit non-goals. - (Omit this section entirely when no security lens was run.) - -## Convergence -- Where models agreed. These are usually safe assumptions for the plan. - -## Divergence (most valuable section) -- Where models disagreed. Each entry: which model said what, and the planner's - current lean — or "open question — needs user" when unresolved. - -## Open questions for the user -- Anything the brainstorm could not resolve. Surface these before drafting the plan. -``` - -### What NOT to do +If unsure for an M task, ask the user one short question. Default-no for plain +M, default-yes for L. -- **Don't run brainstorming for size S.** It's noise. -- **Don't paste raw model output into the conversation.** Files only — that's the whole point of `multi-llm.md`. -- **Don't let the brainstorm become the plan.** The planner still drafts `plan.md`. Brainstorm is option-generation; plan is decision. -- **Don't run brainstorm *and* plan-review on the same plan as a default.** They serve different stages — brainstorm before drafting, plan-review after. Doubling up is justified only when plan-review surfaces re-architecting questions that need fresh brainstorming. +### Invocation -### Future refactor (open question) +Invoke `flow:brainstorm`. It writes `brainstorm.md` (synthesis) and +`brainstorms/` (raw per-model outputs) into the same +`.planning/-/` directory, then returns. The planner then reads +`brainstorm.md` while drafting `plan.md` — **convergence** informs assumptions, +**divergence** informs explicit decisions in `## Alternatives considered` and +`## Approach`. Do not read the raw `brainstorms/*.md` files directly; the +synthesis is the planner-facing artifact. -A self-brainstorm of this section by `gemini-3.1-pro-preview` recommended an alternative shape: **extract brainstorming into a dedicated explore phase between `flow:research` and `flow:plan`**, with a hard user checkpoint after `brainstorm.md` lands. The argument is context isolation (the planner LLM never reads raw contributor output) and reversibility (the user can steer between option-generation and plan-drafting). The current sub-phase shape is a pragmatic compromise; revisit if Option A produces planner drift or if users keep wanting to weigh in between brainstorm and plan. +If `flow:brainstorm` reports an existing `brainstorm.md` from a prior session, +its own idempotency check handles the keep/regenerate/abort decision — do not +re-implement that logic here. ## Frontmatter (every generated document) @@ -447,7 +340,7 @@ Hints are **advisory and human-/reviewer-readable only**. `flow:develop` does no 1. **Read** `meta.md` and `research.md` (if it exists). Don't restart research — build on it. 2. **Read** the user's task goal in their words. If anything is ambiguous, ask one or two focused questions. Don't ask 10 questions; the plan-review step will surface anything you miss. -3. **Decide** whether to brainstorm (see "Multi-LLM brainstorming" above for the trigger criteria). If yes, dispatch providers, synthesize `brainstorm.md`, and resolve any "open questions for the user" before drafting. +3. **Decide** whether to brainstorm (see "Optional brainstorming sub-phase" above for the trigger criteria). If yes, invoke `flow:brainstorm`; it synthesizes `brainstorm.md` and surfaces "open questions for the user" — resolve those before drafting. 4. **Choose** the approach. Use `research.md` candidate approaches and `brainstorm.md` divergence as inputs. For size M/L, if two viable approaches remain close or the choice changes user-visible scope, pause once and ask the user to choose before @@ -469,5 +362,6 @@ Hints are **advisory and human-/reviewer-readable only**. `flow:develop` does no - Frontmatter schema: `../../references/frontmatter.md` - TDD policy (what gets tests, what doesn't): `../../references/tdd-policy.md` - Doc style (prefer lists over tables): `../../references/doc-style.md` -- Multi-LLM dispatch & quorum (used by brainstorming): `../../references/multi-llm.md` +- Brainstorming skill (option-generation): `../brainstorm/SKILL.md` +- Multi-LLM dispatch & quorum (used by `flow:brainstorm`): `../../references/multi-llm.md` - Model registry (lenses + IDs): `../../references/models.md` From 59ea9df39fdb995f9268aa8ad4d1787e0d7f8d34 Mon Sep 17 00:00:00 2001 From: gitgitWi Date: Sun, 17 May 2026 01:36:09 +0900 Subject: [PATCH 3/7] docs(research): note optional handoff to flow:brainstorm MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a short paragraph after the Candidate approaches template explaining when research should *suggest* /flow:brainstorm as the next step: 3+ viable shapes with comparable risk/effort, or explicit user request for option-generation. Advisory only — no auto-dispatch; the user or flow:orchestrate decides whether to fan out before flow:plan. Add flow:brainstorm to the Reference list. --- skills/research/SKILL.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index 2f74c69..e5df304 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -137,6 +137,14 @@ obvious. Use this shape: Effort: S/M/L. Risk: low/medium/high. Reuses: . ``` +If the candidate list ends up with **3+ viable shapes whose risk and effort are +genuinely comparable**, or the user explicitly asks for option-generation, +*suggest* `flow:brainstorm` as the next step in an `## Open questions` bullet — +e.g., "More than one viable shape; consider `/flow:brainstorm` before planning +to weigh them with diverse lenses." This is advisory only; research does not +auto-dispatch. The user (or `flow:orchestrate`) decides whether to fan out +before invoking `flow:plan`. See `../brainstorm/SKILL.md` for triggers. + ## What NOT to do - **Don't research the obvious.** Linking to the React docs for `useState` is noise. @@ -152,3 +160,4 @@ obvious. Use this shape: - Frontmatter schema: `../../references/frontmatter.md` - Calling other LLMs: `../../references/multi-llm.md` - Doc style (prefer lists over tables): `../../references/doc-style.md` +- Brainstorming handoff (option-generation): `../brainstorm/SKILL.md` From 2faefdc999025e3d9ba90882965a8deb8d449244 Mon Sep 17 00:00:00 2001 From: gitgitWi Date: Sun, 17 May 2026 01:37:14 +0900 Subject: [PATCH 4/7] refactor(orchestrate): show brainstorm as a peer step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reflect the brainstorm extraction in the orchestrate sequence and skip-logic table: - Sequence ASCII: brainstorm becomes step 3 (between research and plan), not a nested sub-step under plan. Note that research may *suggest* brainstorm but does not dispatch. - Skip-logic table: brainstorm gets its own row instead of an indented ↳ row under plan. Same size-based defaults (skip / ask / yes). - Prose: mention that flow:brainstorm is also invocable standalone outside the orchestrate pipeline. - Frontmatter description and Reference list updated to include flow:brainstorm. No behavior change for the default size-M/L paths — brainstorm fires at the same logical point, just rendered as a peer step. --- skills/orchestrate/SKILL.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md index 2221bf3..dc392ae 100644 --- a/skills/orchestrate/SKILL.md +++ b/skills/orchestrate/SKILL.md @@ -1,6 +1,6 @@ --- name: orchestrate -description: Run the full flow workflow end-to-end — prep → optional research → plan (with optional multi-LLM brainstorming) → optional plan-review → develop → deploy — based on a single task goal from the user. Use this when the user wants to hand off a complete task and let the workflow run, rather than driving each step manually. Skips research, brainstorming, and plan-review automatically for size S tasks; runs the full pipeline for size L. Even when the user just says "build me X", consider this skill if the task warrants the full discipline. +description: Run the full flow workflow end-to-end — prep → optional research → optional brainstorm → plan → optional plan-review → develop → deploy — based on a single task goal from the user. Use this when the user wants to hand off a complete task and let the workflow run, rather than driving each step manually. Skips research, brainstorming, and plan-review automatically for size S tasks; runs the full pipeline for size L. Even when the user just says "build me X", consider this skill if the task warrants the full discipline. --- # flow:orchestrate — End-to-end workflow runner @@ -21,34 +21,44 @@ Orchestrate is a thin sequencer. It does not reimplement any of the individual s 2. flow:research [skip if size = S, or user opted out] └── writes research.md + └── may suggest flow:brainstorm if candidate approaches list has 3+ + comparable shapes (advisory — orchestrate, not research, dispatches) -3. flow:plan [always] - └── (sub-phase) multi-LLM brainstorm if size = L, or size = M with cross-module / - security-sensitive / public-surface flag → writes brainstorm.md + brainstorms/ - └── writes plan.md, tasks.md +3. flow:brainstorm [run if size = L, or size = M with cross-module / + security-sensitive / public-surface flag; ask + otherwise; skip if size = S] + └── writes brainstorm.md (synthesis) + brainstorms/ (raw per-model output) -4. flow:plan-review [run if size = L; ask user if size = M; skip if size = S] +4. flow:plan [always] + └── writes plan.md, tasks.md (consults brainstorm.md when it exists) + +5. flow:plan-review [run if size = L; ask user if size = M; skip if size = S] └── writes code-reviews/plan-*.md and plan-summary.md └── if substantive changes: bumps plan.md → plan.v1.md, writes new plan.md -5. — Checkpoint with user — +6. — Checkpoint with user — Show plan.md, tasks.md, and plan-summary.md (if exists). Wait for go/no-go. -6. flow:develop [after user confirms] +7. flow:develop [after user confirms] └── executes tasks.md, atomic commits, all checkboxes filled -7. flow:deploy [as a separate session — see below] +8. flow:deploy [as a separate session — see below] └── pushes, opens Korean PR, runs multi-LLM review, posts inline comments ``` +`flow:brainstorm` is also invocable standalone (`/flow:brainstorm`) outside the +orchestrate pipeline — useful when the user wants to weigh options on a sketch +without committing to a plan yet. Orchestrate is one of several callers, not +the only one. + ## Size-based skip logic | Step | size = S | size = M | size = L | |---|---|---|---| | prep | yes | yes | yes | | research | skip | ask | yes | -| plan (always) | yes | yes | yes | -| ↳ brainstorm sub-phase | skip | ask (default yes if cross-module / security / public-surface) | yes | +| brainstorm | skip | ask (default yes if cross-module / security / public-surface) | yes | +| plan | yes | yes | yes | | plan-review | skip | ask | yes | | user checkpoint | skip | yes | yes | | develop | yes | yes | yes | @@ -99,6 +109,7 @@ Each individual skill is the source of truth for its own behavior. This skill on - `flow:prep` - `flow:research` +- `flow:brainstorm` - `flow:plan` - `flow:plan-review` - `flow:develop` From d300980d7a7bb5db7d90bec940fe5264e79cf1f8 Mon Sep 17 00:00:00 2001 From: gitgitWi Date: Sun, 17 May 2026 01:38:28 +0900 Subject: [PATCH 5/7] feat(plugin): register brainstorm skill and bump to 0.9.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - plugin.json: insert ./skills/brainstorm/ between ./skills/research/ and ./skills/plan/ (pipeline order); bump version 0.8.0 → 0.9.0; update description to include brainstorm in the pipeline. - marketplace.json: mirror metadata.version + plugins[0].version to 0.9.0; update plugin description to match. Both files in one commit per CLAUDE.md sync rule. Verified with jq: plugin.json .skills length == 9 and .version == "0.9.0"; marketplace.json .metadata.version and .plugins[0].version both == "0.9.0". --- .claude-plugin/marketplace.json | 6 +++--- .claude-plugin/plugin.json | 5 +++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7df8765..596100e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,14 +6,14 @@ }, "metadata": { "description": "Self-hosted marketplace for the flow plugin — opinionated multi-step development workflow.", - "version": "0.8.0" + "version": "0.9.0" }, "plugins": [ { "name": "flow", "source": "./", - "description": "Multi-step development workflow: prep → research → plan → plan-review → develop → deploy → code-review. Atomic commits, TDD-first, multi-LLM review.", - "version": "0.8.0", + "description": "Multi-step development workflow: prep → research → brainstorm → plan → plan-review → develop → deploy → code-review. Atomic commits, TDD-first, multi-LLM review.", + "version": "0.9.0", "author": { "name": "wjh", "email": "gitgitWi@gmail.com" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 648cfe5..38e48df 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "flow", - "version": "0.8.0", - "description": "Opinionated multi-step development workflow: prep → research → plan → plan-review → develop → deploy → code-review. Atomic commits, TDD-first, Multi-LLM review.", + "version": "0.9.0", + "description": "Opinionated multi-step development workflow: prep → research → brainstorm → plan → plan-review → develop → deploy → code-review. Atomic commits, TDD-first, Multi-LLM review.", "author": { "name": "wjh", "email": "gitgitWi@gmail.com" @@ -20,6 +20,7 @@ "skills": [ "./skills/prep/", "./skills/research/", + "./skills/brainstorm/", "./skills/plan/", "./skills/plan-review/", "./skills/develop/", From 53cf0d4d90bdfde1c66b129c2ec710231b5cfccf Mon Sep 17 00:00:00 2001 From: gitgitWi Date: Sun, 17 May 2026 01:38:59 +0900 Subject: [PATCH 6/7] docs(readme): list flow:brainstorm in skills table - Add brainstorm to the pipeline arrow at the top. - Insert one row between flow:research and flow:plan in the Skills table describing standalone and sub-phase invocation. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 201fd98..0c36d85 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ An opinionated multi-step development workflow for Claude Code — a small "council" of LLMs (Claude as orchestrator + Gemini + OpenCode/Kimi + OpenCode/DeepSeek) plans, reviews, and ships your changes together. ``` -prep → (research) → plan → (plan-review) → develop → deploy +prep → (research) → (brainstorm) → plan → (plan-review) → develop → deploy ``` Atomic commits. TDD-first. `.planning/-/` as the working memory. Multi-LLM review (Gemini, OpenCode/Kimi, OpenCode/DeepSeek) at plan time and review time. @@ -14,6 +14,7 @@ Atomic commits. TDD-first. `.planning/-/` as the working memory. Mul |---|---| | `flow:prep` | Create worktree, branch, `.planning/-/` folder, size estimate | | `flow:research` | Optional pre-plan investigation, writes `research.md` | +| `flow:brainstorm` | Optional multi-LLM option-generation, writes `brainstorm.md`; standalone or sub-phase of `flow:research`/`flow:plan` | | `flow:plan` | One-pager `plan.md` + GWT `tasks.md` | | `flow:plan-review` | Multi-LLM critique of the plan, Korean summary, version bump on changes | | `flow:develop` | TDD cycle per `tasks.md` checkbox, atomic conventional commits | From e89cfa42edcfbcfc1140dcd2705923e3a1d0792b Mon Sep 17 00:00:00 2001 From: gitgitWi Date: Sun, 17 May 2026 01:39:51 +0900 Subject: [PATCH 7/7] docs(references): point brainstorm types and layout to flow:brainstorm MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - directory-structure.md: brainstorm.md and brainstorms/ are now authored by flow:brainstorm (direct invocation or sub-phase from flow:research / flow:plan). Drop the size-based trigger comment — those rules live in the skill, not the layout doc. - directory-structure.md: add a Naming rules bullet for the new standalone brainstorm variant .planning/-brainstorm-/ alongside the existing pr-review precedent. Slug derivation: 4–6 kebab-cased content words; collisions get -2, -3. - frontmatter.md: update the brainstorm and brainstorm-contribution type headers to attribute authorship to flow:brainstorm. --- references/directory-structure.md | 8 +++++--- references/frontmatter.md | 4 ++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/references/directory-structure.md b/references/directory-structure.md index c5279d9..8c2b00a 100644 --- a/references/directory-structure.md +++ b/references/directory-structure.md @@ -11,9 +11,10 @@ All flow skills read and write to a single per-task directory. Predictable paths ├── plan.v1.md # previous plan version, kept only if plan-review supersedes ├── tasks.md # GWT checkbox list — single source of truth for progress ├── research.md # optional, written by `flow:research` -├── brainstorm.md # optional, multi-LLM brainstorming synthesis (size L always, -│ # size M when cross-module / security-sensitive / public-surface) -├── brainstorms/ # raw per-model brainstorming outputs, written by `flow:plan` +├── brainstorm.md # optional, multi-LLM brainstorming synthesis, written by +│ # `flow:brainstorm` (direct invocation or sub-phase of +│ # `flow:research` / `flow:plan`) +├── brainstorms/ # raw per-model brainstorming outputs, written by `flow:brainstorm` │ ├── architecture-gemini.md │ ├── risk-kimi.md │ └── security-deepseek.md # size L only by default @@ -32,6 +33,7 @@ All flow skills read and write to a single per-task directory. Predictable paths - **Date prefix**: `yyyy-mm-dd` reflecting when prep ran. Local timezone is fine. - **Task name**: kebab-case, derived from the task goal. Match the branch's name-portion (e.g. branch `feature/add-google-login` → task name `add-google-login`). - **Standalone PR review variant**: when `flow:code-review` runs on a PR that was not created through this workflow (no matching task directory), it creates `/.planning/-pr-review/code-reviews/` instead. Same internal layout (reviewer files + `code-summary.md`); the directory name encodes the PR number rather than a kebab task name. No `meta.md`, `plan.md`, or `tasks.md` is required in this variant. +- **Standalone brainstorm variant**: when `flow:brainstorm` is invoked directly (no `flow:prep` ran) on an inline task brief, it creates `/.planning/-brainstorm-/` instead. `` is a kebab-cased 4–6 word condensation of the brief (collisions get `-2`, `-3`). Same internal layout for `brainstorm.md` + `brainstorms/`; a minimal `meta.md` is generated from the inline brief. - **Versioning**: `plan-review` only renames the old plan to `plan.v1.md` when it makes substantive changes. If it just confirms the plan, no version bump. ## Frontmatter diff --git a/references/frontmatter.md b/references/frontmatter.md index c95e010..fd98c61 100644 --- a/references/frontmatter.md +++ b/references/frontmatter.md @@ -105,7 +105,7 @@ external_llm_outputs: # only when used_external_llm is true - ./code-reviews/research-gemini.md ``` -### `brainstorm` (multi-LLM brainstorming synthesis, authored by `flow:plan`) +### `brainstorm` (multi-LLM brainstorming synthesis, authored by `flow:brainstorm` — invoked directly or as a sub-phase from `flow:research` / `flow:plan`) ```yaml contributors: # models whose raw output is folded in @@ -114,7 +114,7 @@ contributors: # models whose raw output is folded in missing_contributors: [] # models that failed (mirrors plan-summary pattern) ``` -### `brainstorm-contribution` (per-model raw output under `brainstorms/`) +### `brainstorm-contribution` (per-model raw output under `brainstorms/`, authored by `flow:brainstorm`) ```yaml contributor: gemini-3.1-pro # CLI-facing model id