sb-hub

sb-hub — オンボーディングチェック · オーケストレーター · ナビゲーター

ハブです。ここでは作成作業は行わず、状態を確認して適切な先へ案内します。読み取り専用のモードが3つあります。目的に応じて選んでください。共有の用語、ストレージマップ、再開プロトコルを確認するため、CONTEXT.mdを一度読みます。

モード別の読み込み（最初に両方の参照を読み込まないでください）：

• references/runbook.md — ナビゲーターのエンジン（状態検出 → 次のステップを1つ提示）。モード0／モード2（診断／「次は何をするか」）で読み込みます。
• references/end-to-end-flow.md（約220行）—「まとまりのないアプリ → デザインシステム」のパイプライン全体を示す実例です。モード1（監査全体をオーケストレーション）でのみ読み込みます。モード0のオンボーディングチェックやモード2の次のステップの確認では読み込まないでください。それらに必要なのはrunbook.mdだけです。

正規のコンテキスト（情報源は1つ）。 バンドルにはCONTEXT.mdが1つだけあります（共有用語 · STORAGE MAP · 再開）。手作業で複製されることはありません。バンドル／プラグインのインストールでは、すべてのスキルがこのファイル（CONTEXT.md／${CLAUDE_PLUGIN_ROOT}/CONTEXT.md）を読み込みます。単体のnpx skills add <skill>では、ビルド時に組み込まれたバイト単位で同一のコピーが配布され、アップデート時に更新されます。sb-hubはオーケストレーターです。スキルを個別にインストールしている場合は、パイプラインと共有用語の権威ある情報が保たれるよう、sb-hubを経由してください。

バンドルの場所を解決する

スクリプトはシscripts/にあります。このリポジトリでは${CLAUDE_PLUGIN_ROOT}/scripts/です。 プラグインとしてインストールされている場合は、${CLAUDE_PLUGIN_ROOT}/scripts/を使います。

CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}   # shared scripts: "$CORE/scripts/<name>"

モードを選ぶ

ユーザーの意図	モード
「準備はできていますか」「どこから始めればいいですか」、新規／不明なリポジトリ	0 · オンボーディングチェック
「このアプリを監査して」「すべて実行して」「このアプリ用にStorybookを構築して」	1 · オーケストレーション
「次は何をするか」、または動詞が台帳に追加された後	2 · ナビゲーション（デフォルト）
「これは間違っています」「挙動がおかしい」「バグを報告する」、スキルが誤作動した	3 · 報告

---

モード0 — オンボーディングチェック（フェーズ0の診断、読み取り専用）

新規でまとまりのないアプリでは、動詞を実行する前に、技術スタックと準備状況を調査してレポートを出し、最初のステップを提案します。プロンプトも書き込みもなく、何度でも実行できます。

echo "━━ Phase 0 — readiness ━━"
grep -q '"react"' package.json 2>/dev/null && echo "  [ok]   React" || echo "  [warn] no React in package.json"
grep -qE '"vite"|"@vitejs' package.json 2>/dev/null && echo "  [ok]   Vite" || echo "  [info] not Vite (skill targets React+Vite)"
test -d .storybook && grep -q '"storybook"' package.json 2>/dev/null && echo "  [ok]   Storybook present" || echo "  [warn] NO_STORYBOOK → start with sb-setup"
test -d node_modules && echo "  [ok]   node_modules present" || echo "  [warn] deps not installed — run your package-manager install"
lock=$(ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null | head -1); echo "  [info] lockfile: ${lock:-none}"
grep -q '@storybook/addon-mcp' package.json 2>/dev/null && test -f .mcp.json && echo "  [info] MCP wired → sb-stories uses with-mcp" || echo "  [info] no addon-mcp → without-mcp path"
if find .storybook -maxdepth 1 -name '*.json' 2>/dev/null | grep -q .; then
  find .storybook -maxdepth 1 -name '*.json' | sed 's/^/  [ok]   discovery: /'
else echo "  [info] no discovery JSON yet → sb-inventory not run"; fi
grep -q 'storiesLocation:' .storybook/audit/status.md 2>/dev/null && echo "  [ok]   stories location decided" || echo "  [warn] stories location undecided → sb-setup must ASK (isolated .storybook/stories/ vs co-located) before sb-stories"

実例 — 移行が途中のアプリ（Storybookはインストール済み、監査はまだ未実施）：

━━ Phase 0 — readiness ━━
  [ok]   React
  [ok]   Vite
  [ok]   Storybook present
  [ok]   node_modules present
  [info] lockfile: pnpm-lock.yaml
  [info] no addon-mcp → without-mcp path
  [info] no discovery JSON yet → sb-inventory not run
  [warn] stories location undecided → sb-setup must ASK …

→ Storybookは存在しますが、discovery JSONはなく、配置場所も未決定です。そのため、いきなりsb-storiesに進まないでください。まずsb-setupを挙げて（storiesの配置場所を記録するため）、次にsb-inventoryを挙げます。この順序、つまりinventoryより先にsetup、storiesより先にinventoryこそが、このゲートの要点です。[info]／[warn]の行はノイズではなく、案内の合図です。

バンドルが書き込むものはすべて.storybook/の下にあります（CONTEXT.mdのSTORAGE MAP）。ほかの場所に出力があれば必ず指摘してください。決めることはstoriesの配置場所だけです。未決定の場合はsb-setupを挙げてください（確認が行われます）。

Discoveryは事前計算されています。 Discoveryレイヤーは.storybook/内のJSONです： project-inventory（tokens.mapとstoryCoverageを含む） · component-usage · flows · design-system-health · component-states · prop-shapes · page-patterns · runtime。 最初の4つはStorybookにレンダリングされ（autodocsの埋め込み＋ラッパー）、refresh-usage.shによってまとめて更新されます。残りは作成時の入力情報（必要に応じて再生成）です。スクリプトがすでに.storybook/*.jsonに書き出した内容を、シェルスキャンで再導出しないでください。フィールドを読み取ってください。

その後、**→ 開始：<最初の動詞>**と出力します。NO_STORYBOOKの場合はsb-setup、それ以外はsb-inventoryです。動詞は実行せず、名前を挙げて終了してください。新規プロジェクトの全行程を扱う場合は、モード1に引き継ぎます。

モード1 — オーケストレーション（監査全体を実行 → stories）

「このアプリを最初から最後まで監査して。」パイプラインを順番に、フェーズ間のゲートを守って実行します。前の成果物が存在するまで先に進まないでください（discoveryスクリプトはアトミックに書き込むため、既存のJSONは完成済みです）。兄弟スクリプトを直接実行することはありません。各処理に特化したスキルを呼び出し、その出力を確認します。

1. sb-setup — Mode 0 で NO_STORYBOOK が報告された場合、またはストーリーの配置場所が未決定の場合です。GATE：.storybook/ と package.json 内の "storybook"、さらに .storybook/audit/status.md に storiesLocation が記録されていること（sb-setup がユーザーに確認します — .storybook/stories/ に分離するか、コンポーネントと同じ場所に配置するか）、および .storybook/runtime.json が存在すること（discover-runtime.py — 共有プレビューが提供する必要のあるプロバイダーツリー／ルート CSS／ポータル／MSW）。ステップ 2 の前に満たしてください。
2. sb-inventory — 本物かスロップか、および主要なデザインシステムを確認します。GATE：.storybook/project-inventory.json が存在すること。
3. sb-health — デザインシステムの健全性を確認します。GATE：.storybook/design-system-health.json が存在すること。designSystem.mixed または生の HEX 値が多い場合は、作成に入る前に /ds-runbook への引き継ぎを提示してください。
4. sb-flows — ルートマップとナビゲーションのつながりを確認します。GATE：.storybook/flows.json が存在すること。
5. sb-stories <Component> — ストーリーが必要な各コンポーネントのストーリーを作成します。components.storyCoverage.needsStory[]（ストーリーがない独自コンポーネント。インポート数の多い順）を順に進め、各ステップで validate-stories.sh によるゲートを実施します。storyCoverage.source == "storybook-index" の場合、正確な進捗指標は storyCoverage.withRegisteredStory/ needsCount です（Storybook の index.json と照合済み — Storybook が実際に登録するストーリーを示します）。それ以外の場合は withColocatedStory/needsCount です（ヒューリスティックです。withStory は緩い上限で、モックのためにストーリーがインポートするだけのコンポーネントも数えます）。作成後に sb-inventory（または sb-audit）を再実行して、インデックスからカバレッジを更新し、needsStory[] を減らしてください。空になるまで繰り返します。
6. sb-wrappers — 各ステップの出力をビューとして表示します。ProjectInventory（ステップ 2 の後）、DesignSystemHealth／TokenMatrix（ステップ 3 の健全性確認後）、AppFlowGraph／JourneyGraph（ステップ 4 の後）、ストーリー作成中の StateGrid／StateMatrix（ステップ 5）です。データラッパーには該当ステップの JSON が先に必要です — 「When in the flow」については sb-wrappers を参照してください。
7. sb-audit — ストーリーがそろったら、定期的に差異を調査し、判断事項を提示します。refresh-usage.sh（以下）を実行します。

Figma 起点のデザインシステム（任意の分岐、ステップ 1 の後）。 上記のパイプラインはコード優先です（既存のものを監査します）。信頼できる情報源が承認済みの Figma ファイルである場合は、作成に入る前に sb-figma を挿入して、基盤トークンの整合性を確立します。Figma MCP の変数を .storybook/figma/ に取り込み、.storybook/figma-token-parity.json（色／スペーシング／タイポグラフィ、OKLCH→hex）を書き込み、Foundations/Colors|Tokens|Type のストーリーに figmaVar／figmaHex を設定して、差異を報告します。これは sb-health（ステップ 3）に情報を追加するもので、置き換えるものではありません。sb-health はコード内のトークンセットを確認し、sb-figma は sb-health では把握できないデザインとコードの整合性を確認します。Figma から承認済みのコンポーネントを提供する場合も sb-figma を使い、sb-stories で作成します。未決定のデザインを反復検討する場合は sb-explore を使います。

各フェーズの後に、.storybook/audit/findings.md に所見を 1 行追加してください。最初に失敗した GATE で停止し、修正に必要な verb をユーザーに伝えてください。（lfg のような、順序付きのハードゲート付きパイプラインのパターンです。）

レンダリングデータを最新に保つ（使用状況レイヤー）。 4 つのレンダリング用 JSON（inventory・component-usage・flows・design-system-health）は、自動生成ドキュメントの使用状況埋め込みに使われます。UsageSection を preview.ts の docs.page に一度設定すると、すべてのコンポーネントの Docs および各 Foundation（Colors/Semantic/Typography/Scales = トークンテーブル、Health = 監査結果）に「このアプリでの実際の使用状況」が追加されます。refresh-usage.sh --docs は 4 つすべてをまとめて再実行し、再ビルド後に実態を反映します。sb-audit は実行のたびにこれを行うため、storybook build の前に CI で実行してください。（セットアップでは docs.page の構成を設定します — sb-setup の install-wizard を参照してください。）

Mode 2 — Navigate（デフォルト — 次のステップを1つだけ指定）

状態と台帳を確認し、前提条件を満たした、次に実行すべき的を絞ったスキルを1つだけ提案します。

test -d .storybook && grep -q '"storybook"' package.json 2>/dev/null && echo STORYBOOK_PRESENT || echo NO_STORYBOOK
ls .storybook/*.json 2>/dev/null            # which discovery JSONs exist
cat .storybook/audit/status.md 2>/dev/null  # ledger / resume point
# DRIFT — source/story files changed since the last discovery (newer than the inventory JSON). Plain
# `find -newer` → cross-agent (no git, no Claude hook), works on uncommitted/untracked files. Lists the
# exact files that moved this session; if any, the discovery JSONs are stale → refresh before routing.
if [ -f .storybook/project-inventory.json ]; then
  find src app components .storybook/stories \( -name '*.tsx' -o -name '*.ts' \) \
    -newer .storybook/project-inventory.json 2>/dev/null | grep -v '\.storybook/.*\.json' | head -20
fi
# COVERAGE — READ the field the script already wrote (CONTEXT.md doctrine: never re-derive). Extract
# ONLY storyCoverage so the FULL object surfaces complete — never a truncated dump of the whole
# inventory. Prefer the authoritative `withRegisteredStory` (source=storybook-index, reconciled against
# index.json); fall back to the heuristic `withColocatedStory`. needsStory[] is the iterate list.
if [ -f .storybook/project-inventory.json ]; then
  python3 - <<'PY'
import json
try: c = json.load(open(".storybook/project-inventory.json"))["components"]["storyCoverage"]
except Exception: raise SystemExit
src = c.get("source", "heuristic")
done = c.get("withRegisteredStory") if src == "storybook-index" else c.get("withColocatedStory", 0)
print(f"coverage: {done}/{c.get('real',0)} components have a story [{src}] · {c.get('needsCount',0)} need one")
if c.get("needsStory"):
    extra = " …" if c.get("needsCount", 0) > 8 else ""
    print("iterate next (sb-stories): " + ", ".join(c["needsStory"][:8]) + extra)
PY
fi

DRIFT にファイルが列挙されている場合、検出用 JSON とコードが一致していません。次のステップを指定する前に、sb-inventory（または定期確認の場合は sb-audit）に振り分けて更新します。refresh-usage.sh はインベントリ／使用状況／フローを再取得し、さらに Storybook 独自の index.json（権威ある情報源であり、ベース名からの推測ではありません）と照合してストーリーのカバレッジを調整します。その後、次のステップを指定します。指定するのは必ず1つだけです。

状態	次のステップ	スキル
NO_STORYBOOK	npm create storybook@latest + npx storybook skills setup でブートストラップを後回しにし、その後調整する	sb-setup
project-inventory.json がない	実在するものと不要なものを先に見極める	sb-inventory
インベントリ完了、design-system-health.json なし	作成前に健全性を確認する	sb-health
健全性確認完了、flows.json なし	ナビゲーション + app-map を取得する	sb-flows
インベントリに問題なし、ストーリーを作成したい	コンポーネントを1つ作成する	sb-stories <Component>
新規／再設計するコンポーネントの方針が未決定 — 選択肢を試行中	サンドボックスで反復する（+ Figma ノード）	sb-explore
承認済みの Figma デザイン — 基盤トークン（色／間隔／タイポグラフィ）をマッピングする、または承認済みコンポーネントを納品する	Figma → 本番 Storybook	sb-figma
Figma とコードのトークンの一致を確認する／「デザインシステムは Figma と同期しているか」を確認する	一致状況 + ドリフトレポート	sb-figma
コンポーネントを Figma に再接続する（Code Connect）／「Figma Dev Mode でコードを表示する」	コード → デザイン（逆方向）	sb-figma
定期確認	ドリフト調査 + 判断ボード	sb-audit
Explore が卒業条件を満たした	本番環境へ反映する	sb-ship

EXPLORE と DELIVER（どちらも Figma 対応 — 「Figma を使うか」ではなくステージで振り分けます）： 方針未決定／選択肢を試行中 → sb-explore（Lab）→ sb-ship（卒業）。Figma で承認済み → sb-figma（本番へ直接納品）。sb-figma は Foundation トークンのストーリーを自ら作成します。承認済みのコンポーネントの場合は、デザインを抽出してから sb-stories のルールに従って作成します。すべての Figma MCP 出力を .storybook/figma/（マニフェスト + ツールごとのファイル）に保存するため、パイプラインは再現・反復可能であり、MCP に縛られません。

再開ルール（CONTEXT.md）： status.md を読み、どの JSON が存在するかを確認します。最初の未完了ステップから再開してください。前のセッションでファイルが途中まで書かれていても、完了したものとして扱ってはいけません。そのステップを再実行してください。

Mode 3 — Report（スキルの誤動作／不可解な動作）

スキルが誤った動作をした、予想外の動作をした、または壊れていたとユーザーが伝えた場合は、役に立つレポートの作成を支援します。単に謝るだけではありません。エージェントネイティブのレポーターで下書きを作成し、送信用のコマンドを提示します。

CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
"$CORE/scripts/report-issue.sh" --asked "<what they asked>" --observed "<what happened>" --expected "<what they wanted>"

問題の原因が sb-figma の場合は --gaps を追加します。下書きには .storybook/figma/gaps.json にある未解決のギャップが、種類ごとの件数として列挙されます（名前や値は含まれません）。

サニタイズ済みの下書き（バージョン情報と .storybook/*.json の構造／件数のみ — ソース、トークン値、コンポーネント名は含みません）を書き出し、gh issue create … コマンドと空の issue の URL を表示します。ネットワークへの接続は行いません — 送信はユーザーが行います。会話の内容から --asked/--observed/--expected を埋め、下書きのパスと gh の行を提示します。ユーザーから依頼された場合に限り、gh の実行を申し出てください。別のリポジトリを指定するには、SB_ISSUE_REPO=owner/name を設定します。優れたレポートは、再現手順 → 新しい eval ケース → 修正 → field-learnings.md のエントリーへとつながります。このループによって、次回の実行で同じバグが再発するのを防ぎます。

決してしてはいけないこと（オーケストレーションの失敗要因とその理由）

• Mode 1 では、失敗したゲートや空のゲートを決して通過してはいけません。各フェーズの .storybook/*.json は、次のフェーズの前提条件です（コンポーネントより先に基盤トークン、アプリマップより先にフロー）。どれかを飛ばすと、それ以降のフェーズは正確な情報が欠けたまま構築され、成果がひそかに不十分になります。
• スクリプトがすでに書き出した内容をシェルスキャンして、CONTEXT を決して再導出してはいけません。.storybook/*.json ファイルが状態そのものです。手作業で grep すると、スクリプトが取得した内容やラッパーが表示する内容とのずれが生じます。再計算せず、フィールドを参照してください。
• 前のセッションで途中まで書き込まれた成果物を、決して完成済みとして扱ってはいけません。ファイル単位の書き込みはアトミックですが、実行が中断されるとパイプラインの途中で停止している場合があります。status.md を確認し、最初の未完了ステップを再実行してください。
• ここで作成してはいけません。ハブの役割は調査と振り分けです。ハブからストーリーやラッパーを作成すると、専用スキル独自のチェックやアンチパターンを回避してしまいます。代わりにスキルを呼び出してください。
• CONTEXT.md を手作業で複製してはいけません。すべてのスキルは単一の正規ファイル（CONTEXT.md）を読み込みます。コピーを作ると、いずれ内容がずれてしまいます。

エージェント間の連携

• Claude：このスキルは /sb-hub です（Mode 2 の「次は何をするか」がデフォルトです。/sb-hub onboard または /sb-hub audit this app で Mode 0／1 を選択します）。
• Codex：$sb-hub what's next · $sb-hub onboard · $sb-hub audit this app。
• ループ：動詞コマンドを実行 → .storybook/audit/findings.md に追記 → もう一度 sb-hub に尋ねる（Mode 2） → 次に実行する、範囲を絞ったスキルが提示される → そのスキルを実行します。