Workflow & Core Tools · obra/superpowers

brainstorming

Name: brainstorming
Author: obra/superpowers

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author obraGitHub obra/superpowers ↗Stars 282289License MITCommit b36e0829c6

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The core mechanism is a prompt-orchestrated 'three-path router + human approval gate': before implementation, requests are classified by scope into Spike, Bounded, or Architectural. Regardless of the path, the agent is strictly required to state its intent to the user and obtain approval before writing code—without host-level code enforcement, relying entirely on the model following instructions.

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>

'Ceremony scales with task scope, but the approval gate never scales down' is the core design philosophy of this skill: approval is constant, while artifacts (specs/plan documents) are variable. The classification must be stated out loud ('say the classification out loud') so the user can override it, inherently designed to prevent the agent from unilaterally choosing the lighter path.

Classification acts as the workflow scheduler: Spike only probes feasibility and reports findings (retaining no code); Bounded is restricted to 'small changes within an existing readable flow in the repo,' stopping after providing a brief design in chat; Architectural (new projects, new subsystems, modifying interfaces) undergoes the full process leading to a written spec. Hidden complexity upgrades the path mid-flight via a one-way ratchet that cannot be downgraded.

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.

The definition of Bounded is intentionally tied to the 'current state of the repo' rather than 'agent familiarity' ('Bounded measures the repo, not your familiarity'), closing off the most common excuse for cutting corners. The Red Flags table juxtaposes 7 excuses for bypassing the gate in a 'thought vs. reality' format, serving as an anti-cognitive trap design.

The endpoint of the Architectural path is handoff rather than implementation: after a self-review of the spec, it is submitted for user review; once approved, the only permitted next skill to invoke is writing-plans. The design document is written to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and committed to git.

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.

This serves as the integration seam connecting brainstorming into the superpowers framework (14 skills): spec → writing-plans → execution pipeline. Spec Self-Review uses an inline checklist (placeholder scan, consistency, scope, ambiguity) instead of dispatching to a sub-agent (the sibling spec-document-reviewer-prompt.md is not referenced by SKILL.md in this pin; see verification).

The sole executable asset is the optional 'Visual Companion': a custom Node HTTP+WebSocket server with zero third-party dependencies that monitors the content directory, pushes the latest HTML screen to the user's browser, and writes user clicks/selections back to state/events files via WS for the agent to read in subsequent turns, forming an inspect-click-feedback loop.

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'); } }

Features hand-written RFC6455 frame encoding/decoding (encodeFrame/decodeFrame) and zero npm dependencies (using only Node built-in http, fs, path, crypto, os, child_process); getNewestScreen selects the latest .html file by mtime. The server generates no outbound network traffic.

The triggering discipline for the Companion is 'just-in-time offering, decided per question': pushing it at the start is forbidden; it is proposed in a standalone message only when a question is genuinely 'clearer when seen than read', and the server is not started until the user accepts; even after acceptance, whether to use the browser or terminal is evaluated per question depending on whether the content is visual or text.

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*.

The accompanying visual-companion.md details the loop: write screen (content fragment by default, wrapped automatically in frame-template by the server) → prompt URL → read events + merge terminal text in the next turn → iterate. The same document makes clear that 'A question about a UI topic is not automatically a visual question' (conceptual questions remain in the terminal).

2Core Capabilities

01Three-path request classification (Spike/Bounded/Architectural) declared verbally for user override

02Mandatory approval gate (HARD-GATE) prior to implementation

03Countermeasures against 'too simple to need approval' cognitive traps (Anti-Pattern + Red Flags table)

04Mid-flight path escalation upon discovering hidden complexity (one-way ratchet)

05Clarifying one-at-a-time Q&A + upfront scope check (decompose multiple subsystems before detailing)

06Multi-option trade-off proposals + sectional design presentation (requesting confirmation per section)

07Design document self-review → user review gate → handoff to writing-plans

08In-browser Visual Companion (mockups, diagrams, A/B comparison screens + structured click event callbacks)

3External Dependencies

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 级引用）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local scripts or commands: scripts/start-server.sh (bash; starts local Node server, writes PID/port/token files, can kill previous instances)
网络端点: Declared external network access: user browser loads https://primeradiant.com/brand/superpowers-visual-brainstorming-log
本地工作目录: File read/write and artifact output: agent (per skill instructions) writes screen_dir/*.html screen content; writes docs/superpowers/specs/YYYY-MM-

Audit Notes: Behavioral surface: pure prompt workflow (no scripts, no outbound calls) + a local Node server started only after user approval. Basis for yellow tier: ① Expected third-party outbound traffic—when telemetry is not disabled, the user's browser fetches a brand image from primeradiant.com (author's domain); ② Companion opens a local HTTP/WS port and automatically launches the browser (docs support 0.0.0.0 binding for remote containers); if the session key in the URL leaks, processes on the same machine/LAN could view screens or inject click events; ③ Server-side execution surface (node/bash/git/browser launcher) is bounded by host permissions. No credential harvesting, no data exfiltration, no arbitrary code execution surface; all elevated behaviors require explicit triggers (user accepts companion with --open / manual --host 0.0.0.0).

5Second-Pass Verification

[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 约束，无宿主级强制机制——是否生效取决于宿主加载与模型遵从，属能力边界而非缺陷

6Verdict & Scenarios

Institutionalizes 'approve before implementing' into a multi-layered anti-bypass design: HARD-GATE + Anti-Pattern + 7-row Red Flags table debunking common excuses one by one

Process overhead strictly matches task scope: artifacts scale across spike/bounded/architectural tiers, approval gates remain constant, and paths can only ratchet up, never down

Clear inter-skill handoff discipline: the architectural endpoint uniquely binds to writing-plans, preventing workflow blurring

Visual Companion is a real runnable implementation rather than a guideline: zero-dependency Node server + hand-written WS protocol, high code quality (token gating, constant-time comparison, path traversal protection, 0600 file permissions)

Restrained just-in-time interaction design: no unsolicited promotion, proposed via a single message, decided per question, forces conceptual questions to the terminal, avoiding browser noise

Best for: Orchestrating the 'design phase' within the obra/superpowers development methodology framework: clarifying intent, weighing alternatives, and drafting written specs prior to touching code for any feature, component, or new project. Best suited for agent workflows requiring strict 'think before coding' discipline where the host can load the entire framework (brainstorming → writing-plans → TDD/executing-plans). Visual Companion is suitable for remote UI/architecture discussions with users where the environment permits background processes and auto-opening browsers.

Not for: Not suitable for standalone use decoupled from the superpowers framework (much of its value lies in seams with the other 13 skills); not suitable for rapid experimentation that rejects an 'approve before implement' cadence; pure text clarification scenarios do not need Companion enabled (though the skill's gating process remains active).

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

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b36e0829c6.