1仕組みと動作原理
コアメカニズムはプロンプトでオーケストレーションされた「3経路ルーター＋人間による承認ゲート」です。実装前にリクエストを規模に応じて Spike / Bounded / Architectural に分類し、どの経路であってもエージェントは必ずユーザーに意図を説明し承認を得てから作業を開始します。ホストレベルのコード強制はなく、指示テキストに対するモデルの準拠のみに基づきます。
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>
「儀式の重みはタスク規模に応じて伸縮するが、承認ゲートは決して縮減しない」が本スキルの設計コアです。承認は不変であり、成果物（spec/計画ドキュメント）のみが可変です。ユーザーが覆せるように分類を声に出して宣言（"say the classification out loud"）することが義務付けられており、エージェントが自己判断で軽い経路を選ぶのを防ぐ意図が込められています。
分類自体がプロセススケジューラーとして機能します。Spike は実現可能性の調査のみを行い結果を報告（コードは保持しない）、Bounded は「リポジトリ内に既存の読みやすいフローがある軽微な変更」に限定してチャット内で短い設計を出して停止、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 の定義は意図的に「エージェントの習熟度」ではなく「リポジトリの現状」に紐づけられており（"Bounded measures the repo, not your familiarity"）、最もありがちな手抜きの言い訳を封じます。Red Flags テーブルはゲート回避の7つの言い訳を「思考 vs 現実」の対比として記載し、認知トラップを回避する設計となっています。
Architectural 経路のゴールは実装ではなく引き継ぎです。spec のセルフレビュー後にユーザーの再確認を求め、承認後に唯一呼び出しを許可される次のスキルは 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スキル）に接続する接合点です（spec → writing-plans → 実行パイプライン）。Spec Self-Review にはインラインのチェックリスト（プレースホルダー検出、整合性、スコープ、曖昧さ）を使用し、サブエージェントへの外部委託は行いません（同ディレクトリの spec-document-reviewer-prompt.md は本ピン留め版の SKILL.md からは参照されていません。verification 参照）。
唯一の実行可能アセットは任意の「Visual Companion」です。自前で実装されたサードパーティ依存関係ゼロの Node HTTP+WebSocket サーバーであり、content ディレクトリを監視して最新の HTML 画面をユーザーのブラウザにプッシュします。ユーザーのクリック選択は WS 経由で state/events ファイルに書き戻され、エージェントが次のターンで読み取ることで、「閲覧→選択→フィードバック」のループを形成します。
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 のトリガー規律は「ジャストインタイムでの提示、質問ごとの個別判断」です。最初から売り込むことは禁止されており、ある質問がテキストよりも「視覚的に見た方が明らかに分かりやすい」場合にのみ単独メッセージで提案され、ユーザーが同意するまでサーバーは起動しません。同意後もコンテンツが視覚的かテキストかに応じてブラウザかターミナルかを設問ごとに決定します。
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 に詳細なループが規定されています：画面書き込み（デフォルトは content fragment、サーバーが自動的に frame-template を適用）→ URL 通知 → 次のターンで events 読み取り＋ターミナルテキスト統合 → イテレーション。同ファイルでは "A question about a UI topic is not automatically a visual question"（UIの話題であっても概念的な質問はターミナルで行う）と明記されています。
2コア機能
01リクエストの3経路分類（Spike/Bounded/Architectural）とユーザーが覆すための口頭宣言
02実装前の強制承認ゲート（HARD-GATE）
03「単純すぎて承認不要」という認知トラップの防止（Anti-Pattern + Red Flags テーブル）
04隠れた複雑性に対する途中からの経路アップグレード（一方向ラチェット）
05明確化のための1問1答＋事前スコープチェック（詳細化の前に複数サブシステムを分解）
06複数案のトレードオフ提案＋段階的設計提示（セクションごとに確認を要求）
07設計ドキュメントのセルフレビュー → ユーザーレビューゲート → writing-plans への引き継ぎ
08ブラウザビジュアルコンパニオン（モックアップ／図／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/ポート/トークンファイルの書き出し、旧インスタンスの終了を実行可能）
- 网络端点: 外部ネットワークアクセスの宣言: ユーザーブラウザが https://primeradiant.com/brand/superpowers-visual-brainstorming-log を読み込み
- 本地工作目录: ファイルの読み書きと成果物出力: エージェントが（スキルの指示に従い）screen_dir/*.html の画面コンテンツを書き込み、docs/superpowers/specs/YYYY-MM- を書き込み
監査ノート： 行動インターフェース：純粋なプロンプトフロー（スクリプトなし、外部送信なし）＋ユーザー承認後にのみ起動するローカル Node サーバー。イエロー（警戒）判定の根拠：①予期されるサードパーティへの外部送信の存在（テレメトリが無効化されていない場合、ユーザーブラウザが primeradiant.com（作成者の独自ドメイン）からブランドロゴ画像を取得）；②Companion がローカルホストで HTTP/WS ポートを開き自動的にブラウザを起動する点（ドキュメント上はリモートコンテナ対応のため 0.0.0.0 バインドもサポート）。URL 内のセッションキーが漏洩した場合、同一ネットワーク／同一マシン上のプロセスが画面を閲覧したりクリックイベントを注入したりするリスクがある；③サーバー側の実行権限（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結論
最適な用途： obra/superpowers 開発方法論フレームワークにおける「設計フェーズのオーケストレーション」を担当：あらゆる機能、コンポーネント、新規プロジェクトに着手する前の意図の明確化、代替案の検討、文書化された spec 作成プロセス。コードを書く前にまずしっかり考える規律を必要とし、ホストがフレームワーク全体（brainstorming → writing-plans → TDD/executing-plans）をロードできるエージェントワークフローに最適。Visual Companion はユーザーとリモートで UI やアーキテクチャを議論し、環境がバックグラウンドプロセスとブラウザの自動起動を許可している場合に適しています。
不向きな用途： superpowers フレームワークから切り離した単独利用には不向き（価値の大半が他の13スキルとの連携接点にあるため）。「実装前の承認」というリズムを受け入れない迅速な実験には不向き。純粋なテキストによる要件明確化シナリオでは Companion を起動する必要はありません（ただしスキルのゲートプロセス自体は有効に機能します）。
Install Agent-Ready
① Verified Mirror 2026-09-06
Option A · Direct DownloadDownload brainstorming.tar.gz
sha256:
Option B · Copy Guide for Agent217df8a1906bc3fc…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b36e0829c6.