Name: brainstorming
Author: obra/superpowers

1实现原理 · 为什么它能做到

核心机制是 prompt 编排的「三路径路由器 + 人类批准门」：实现前先把请求按规模分为 Spike/Bounded/Architectural，无论哪条路径都强制 agent 先向用户说明意图并获准才能动手——没有宿主级代码强制，全靠模型遵从指令文本。

skills/brainstorming/SKILL.md

<HARD-GATE> Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have told your human partner what you intend and they have approved it. This applies to EVERY task on EVERY path below — the ceremony scales with the task; the approval gate never does. </HARD-GATE>

「仪式随任务规模伸缩、批准门永不伸缩」是本 skill 的设计内核：审批是常量、产出物（spec/计划文档）才是变量。分级必须说出口（"say the classification out loud"）以便用户推翻，隐含防『agent 自行选轻路径』的意图。

分类即流程调度器：Spike 只做可行性探查并报告结论（不保留代码）；Bounded 限『仓库里已有可读 flow 的小改动』，聊天内给短设计即停；Architectural（新项目/新子系统/动接口）走完整流程到书面 spec。隐藏复杂度中途升级路径，单向棘轮不可降级。

skills/brainstorming/SKILL.md

When in doubt between two paths, take the heavier one. The ratchet is one-way: hidden complexity discovered mid-task upgrades the path — stop, say so, and step up. Nothing downgrades mid-task.

Bounded 定义刻意绑定『repo 现状』而非『agent 熟悉度』（"Bounded measures the repo, not your familiarity"），堵住最常见的偷懒归因。Red Flags 表把 7 条绕门借口写成『想法→现实』对照，属反认知陷阱设计。

Architectural 路径的终点是交接而非实现：spec 自检后请用户复核，批准后唯一允许调用的下一 skill 是 writing-plans；设计文档写入 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并 git commit。

skills/brainstorming/SKILL.md

**Terminal states are path-bound.** Architectural: the ONLY skill you invoke after brainstorming is writing-plans — never frontend-design, mcp-builder, or any other implementation skill.

这是把 brainstorming 串进 superpowers 框架（14 个 skill）的接缝：spec → writing-plans → 执行管线。Spec Self-Review 用内联清单（placeholder 扫描/一致性/范围/歧义），不再外发子代理（同目录 spec-document-reviewer-prompt.md 在本 pin 未被 SKILL.md 引用，见 verification）。

唯一可执行资产是可选「Visual Companion」：自研零第三方依赖的 Node HTTP+WebSocket 服务器，监视 content 目录、把最新 HTML 屏推给用户浏览器，用户点击选择经 WS 回写 state/events 文件供 agent 下一轮读取，形成『看图→点选→回读』闭环。

skills/brainstorming/scripts/server.cjs

function handleMessage(text) { let event; try { event = JSON.parse(text); } catch (e) { ... } touchActivity(); console.log(JSON.stringify({ source: 'user-event', ...event })); if (event && event.choice) { const eventsFile = path.join(STATE_DIR, 'events'); fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n'); } }

手写 RFC6455 帧编解码（encodeFrame/decodeFrame）、无 npm 依赖（仅 node 内置 http/fs/path/crypto/os/child_process）；getNewestScreen 按 mtime 取最新 .html。服务端不产生任何外发网络流量。

Companion 的触发纪律是「just-in-time 提供、逐问题决策」：不允许开局就推销，只在某个问题确实『看图比读文更清楚』时以单独一条消息提出，用户接受前不启动服务器；接受后仍按『内容是视觉还是文本』逐题决定走浏览器还是终端。

skills/brainstorming/SKILL.md

**Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*.

配套 visual-companion.md 详细规定 loop：写屏（content fragment 默认，服务器自动套 frame-template）→ 提醒 URL → 下一轮读 events + 终端文本合并 → 迭代；同文件明确 "A question about a UI topic is not automatically a visual question"（概念题走终端）。

2核心能力

01请求三路径分类（Spike/Bounded/Architectural）并口头声明供用户推翻

02实现前强制批准门（HARD-GATE）

03反「太简单无需批准」认知陷阱（Anti-Pattern + Red Flags 表）

04隐藏复杂度中途升级路径（单向棘轮）

05澄清式一问一答 + 范围先检（多子系统先分解再细化）

06多方案权衡提案 + 分段设计呈现（每节征求确认）

07设计文档自检→用户复核门→交接 writing-plans

08浏览器可视化协伴（mockup/图/AB 对比屏 + 点击事件结构化回传）

3外部依赖

Kind	Dependency / Endpoint
cli	node
cli	bash
cli	open / rundll32.exe / xdg-open（平台浏览器启动器）
cli	git（agent 提交设计文档）
network	primeradiant.com 品牌 logo 图（浏览器侧加载，telemetry 未禁用时）
network	github.com/obra/superpowers（品牌链接，页面展示用）
network	本地回路 http://localhost:<port> + ws://localhost（Companion 服务，非外发）
package	同仓 skill：writing-plans、elements-of-style:writing-clearly-and-concisely（prompt 级引用）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: scripts/start-server.sh（bash；启动本地 node 服务器、写 PID/端口/token 文件、可 kill 旧实例）
网络端点: 声明外部网络访问: 用户浏览器加载 https://primeradiant.com/brand/superpowers-visual-brainstorming-log
本地工作目录: 文件读写与工件输出: agent（按 skill 指令）：写 screen_dir/*.html 屏内容；写 docs/superpowers/specs/YYYY-MM-

审计说明： 。行为接触面：纯 prompt 流程（无脚本、无外发）+ 一个用户批准后才启动的本地 Node 服务器。跨到黄色档的依据：①存在可预期的第三方外发——telemetry 未禁用时用户浏览器会向 primeradiant.com（作者自有域）拉品牌图；②companion 在本机开 HTTP/WS 端口并自动拉起浏览器（文档支持 0.0.0.0 绑定以适配远端容器），若 URL 泄漏 session key，同网段/同机进程可读屏、注入点击事件；③服务端执行面（node/bash/git/浏览器启动器）由宿主权限约束。无凭证读取、无数据外发、无任意代码执行面；所有跨档行为均有触发条件（用户接受 companion 且用 --open / 手动 --host 0.0.0.0）。

5第二遍独立确认

[ok] 外发端点仅 primeradiant.com + github.com — 全目录 grep https?://|ws://|fetch 复查：仅 server.cjs:106（logo URL）与 251（github 链接）；helper.js/frame-template.html 零外链；server.cjs 无任何 http.request/fetch（只有 createServer）
[ok] 零第三方依赖声明 — server.cjs require 清单仅 crypto/http/fs/path/os/child_process 六个内置模块；scripts/ 下无 package.json，无 npm 安装步骤
[ok] 点击事件回写 state/events — handleMessage 中 fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n') 与 visual-companion.md 描述一致；新屏出现时事件文件被清空（startServer 中 knownFiles 分支 unlinkSync）
[ok] token 门控与跨站防护 — isAuthorized 用 timingSafeEqualStr 比对 ?key= 或 cookie；isAllowedWebSocketOrigin 强制 origin===http://host；安全头齐全（X-Frame-Options DENY/CORP same-origin/no-referrer）；/files/ 经 path.basename + lstat 非符号链接 + nlink===1 + realpath 前缀三重校验
[discrepancy] spec-document-reviewer-prompt.md 在 SKILL.md 中被引用（第一遍初始印象） — 出入：本 pin 的 SKILL.md 未引用该文件——Spec Self-Review 已内联化为 4 步清单（"Fix any issues inline. No need to re-review"）。文件存在但处于未接线状态；RELEASE-NOTES.md:547 描述的是早前文档审查系统（docs/superpowers/plans/2026-01-22-document-review-system.md），该设计已不被当前 SKILL.md 采用。internal_assets 已按『存在但未接线』修正
[ok] telemetry 语义 — 代码中 SUPERPOWERS_TELEMETRY_DISABLED 只控制 brandMarkup 是否渲染 primeradiant.com logo <img> 与文案前缀，无任何事件上报代码路径；三枚禁用环境变量实读存在（server.cjs:107-110）
[ok] 功能声明 vs 实际能力相符度 — description『Explores user intent, requirements and design before implementation』与实现相符，但注意：MUST 级前置声明（"You MUST use this before any creative work"）与 HARD-GATE 均为纯 prompt 约束，无宿主级强制机制——是否生效取决于宿主加载与模型遵从，属能力边界而非缺陷

6结论

把『先批准后实现』制度化为多层防绕行设计：HARD-GATE + Anti-Pattern + 7 行 Red Flags 表逐一戳穿常见借口

流程成本与任务规模严格匹配：spike/bounded/architectural 三档产出物伸缩，审批门恒定，路径单向可升级不可降级

跨 skill 交接纪律清晰：architectural 终点唯一绑定 writing-plans，防流程串味

Visual Companion 是真实可运行实现而非指南：零依赖 Node 服务器 + 手写 WS 协议，代码质量高（token 门控、常量时间比较、路径穿越防护、文件 0600）

just-in-time 交互设计克制：不推销、单条消息提议、逐问题决策、概念题强制走终端，避免浏览器噪音

适合： 在 obra/superpowers 开发方法论框架内承担『设计阶段编排』：任何功能/组件/新项目动手前的意图澄清、方案权衡与书面 spec 环节；适合需要『先想清楚再编码』纪律、且宿主能加载整套框架（brainstorming → writing-plans → TDD/executing-plans）的 agent 工作流；Visual Companion 适合与用户远程讨论 UI/架构且环境允许后台进程+浏览器自动打开的场合。

不适合： 不适合脱离 superpowers 框架单独使用（其价值大半在与其他 13 个 skill 的接缝）；不适合拒绝『实现前批准』节奏的快速实验；纯文本需求澄清场景无需启用 Companion（但 skill 的门禁流程仍会生效）。

Install Agent-Ready

① Verified Mirror 2026-09-06

Option A · Direct DownloadDownload brainstorming.tar.gz

sha256: 217df8a1906bc3fc…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b36e0829c6.