HyperFrames のインストール
HyperFrames をビデオプロバイダーとして追加する統合を、CLAUDE.md に記載された3ステップ「新しいプロバイダーの追加」契約に従って、1パスで再現します。存在すべきすべてのアーティファクトの自己完結型チェックリストであり、不足しているものだけを検証して作成します。
このスキルは、統合をゼロから再導出する代わりに実行してください。このリポジトリにおいて「HyperFrames が配線されている」という状態の正規の記録です。
呼び出すタイミング
- HyperFrames サポートがまだない新しいマーケティングエンジンクローン。
- リベースまたはマージで、以下のアーティファクトのいずれかが欠落した場合(
router:checkが警告を出す、ビデオルーティングがタイポグラフィタスクでhiggsfieldにフォールバックする、.skills/hyperframes*/が存在しないなど)。 - 新しいクライアントがプログラム的なショート動画、モーションタイポグラフィ、データビジュアライゼーションリールを必要とし、マトリクスに3つのタスク種別を配線する必要がある場合。
- 新しいオペレーターをオンボーディングする際に、3つのコミットを読む代わりに単一のコマンド可能なプレイブックが必要な場合。
入力
repo_root: 文字列。マーケティングエンジンクローンの絶対パス。デフォルトはprocess.cwd()。branch: 文字列、オプション。コミットするブランチ。デフォルトはclaude/install-hyperframes。ブランチが存在しない場合は作成します。mainには決してコミットしません。dry_run: ブール値、オプション。true の場合、計画された変更を出力して終了し、書き込みは行いません。
プロセス
各ステップを順番に実行します。各ステップは冪等です。すでに統合済みのリポジトリで再実行しても、そのステップは何も行いません。
ステップ 1 — 事前確認
repo_rootにCLAUDE.mdが含まれ、その中に行## How to Add a New Providerが存在することを確認します。存在しない場合は実行を拒否します。これはマーケティングエンジンリポジトリではありません。lib/providers/video.ts、lib/providers/matrix.ts、lib/providers/types.ts、lib/providers/__mocks__/video.tsが存在することを確認します。いずれかが欠けている場合は実行を拒否します。- アクティブなブランチが
mainではないことを確認します。mainにいる場合は、最初にbranchを作成してチェックアウトします。
ステップ 2 — 3つのランタイムスキルを追加
以下の3つのディレクトリを SKILL.md ファイルとともに作成します。各ファイルはツリー内の正規バージョンとしてすでに存在しています。以下の「参考アーティファクトセット」セクションからそのままコピーしてください。ファイルがすでに存在し、そのフロントマターの name が一致する場合はスキップします。
.skills/hyperframes/SKILL.md— コンポジションオーサリングルール(レイアウト優先アニメーション、一時停止してwindow.__timelinesに登録されたタイムライン、Math.random()/時間ベースのロジック禁止、data-composition-variables経由で宣言される変数)。.skills/hyperframes-cli/SKILL.md—npx hyperframesの lint → inspect → render 開発ループ。常に--strict --strict-variablesでレンダリングします。.skills/hyperframes-prompt-builder/SKILL.md— マトリクスがhyperframesに解決されたときにvideo-prompt-builderによって呼び出されるスペシャリスト。clients/<slug>/design.mdからブランドトークンを読み込み、task_kindごとにテンプレートを選択し、コンポジション仕様とレンダリング引数を返します。
ステップ 3 — ディスパッチャースキルを更新
.skills/video-prompt-builder/SKILL.md において:
- 冒頭の段落と「関連スキル」セクションのスペシャリストリストに
hyperframes-prompt-builderを追加します。 task_kind入力列挙型にmotion_typography、data_viz_reel、programmatic_shortを追加します。- 環境変数を検証する「プロセス」ステップで、リストに
HYPERFRAMES_ACTIVEを追加します。 - プロバイダー→スペシャリストマッピングに行
Hyperframes -> hyperframes-prompt-builderを追加します。 - 例を追加します:
task_kind: programmatic_shortで HyperFrames にルーティングされる週次 KPI リール。
ターゲット文字列がすでに存在するサブステップはスキップします。
ステップ 4 — プロバイダーレイヤーを拡張
lib/providers/types.ts において、VideoTask ユニオンに3つのメンバーを追加します:
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
lib/providers/matrix.ts において:
EMBEDDED_DEFAULTS.videoに3行を追加します:motion-typography、data-viz-reel、programmatic-short– それぞれデフォルトでhyperframesになります。TASK_LABEL_MAPにラベルエイリアスを追加します:"motion typography"、"kinetic typography"、"data viz reel"、"data-viz reel"、"programmatic short"、"parametrized short"。
lib/providers/video.ts において:
RealVideoBaseを拡張し、process.env.HYPERFRAMES_ACTIVE === "true"でガードされるHyperframesVideoProviderクラスを追加します。realGenerateからは「呼び出し元コンテキストでローカル CLI レンダリングが必要;スタブ」エラーをスローします(既存の higgsfield/topview スタブパターンと同様)。REAL_VIDEO_REGISTRYにhyperframes: () => new HyperframesVideoProvider()を登録します。
lib/providers/__mocks__/video.ts において:
BaseMockVideoを拡張し、name = "hyperframes"を持つMockHyperframesVideoProviderを追加します。MOCK_VIDEO_REGISTRYにhyperframes: () => new MockHyperframesVideoProvider()を登録します。
ステップ 5 — ルーティングマトリクスファイルを更新
.specs/architecture/PROVIDERS.md において、「ビデオルーティング」テーブルに3行を追加します:
| モーションタイポグラフィ | hyperframes | HTML/GSAP キネティックタイプ、ブランド忠実、決定論的 |
| データビズリール | hyperframes | 宣言された変数 → 再レンダリング可能なチャート(NYT スタイル) |
| プログラマティックショート | hyperframes | パラメータ化された HTML コンポジション;バイト同一の再レンダリング |
ステップ 6 — .env.example を更新
WAVESPEED_API_KEY= の後に追加します:
# HyperFrames はローカル HTML→MP4 レンダラーです。API キーは不要です。
# ローカルで `npx hyperframes doctor` が成功したら HYPERFRAMES_ACTIVE=true を設定します
# (Node >= 22、FFmpeg が PATH に必要)。https://github.com/wesleysimplicio/hyperframes を参照
HYPERFRAMES_ACTIVE=false
ステップ 7 — CLAUDE.md を更新
- 「スタック」テーブルで、「ビデオ」行のプロバイダーセルに
hyperframes (ローカル HTML→MP4)を含めるように変更します。 - 「利用可能なスキル」で、
wavespeed-batchの後に3行を挿入します:hyperframes— HTML を真実のソースとするモーションコンポジションオーサリング。hyperframes-cli—npx hyperframesの lint/inspect/preview/render を実行します。hyperframes-prompt-builder— マトリクスがhyperframesに解決されたときにvideo-prompt-builderによって選択されます。
ステップ 8 — 検証
- 以下のテストを使用して
.specs/architecture/PROVIDERS.mdを解析し、motion-typography、data-viz-reel、programmatic-shortがすべてhyperframesに解決されることをアサートします。 npm run typecheckを実行します — 変更とは無関係な既存の失敗(例:@types/nodeの欠落)は許容しますが、プロバイダーレイヤーを参照する新しい TS エラーがあれば失敗とします。- リポジトリに
.envが存在する場合はnpm run router:checkを実行します。それ以外はスキップします(スクリプトは.envを必要とし、統合の形状とは無関係です)。 git statusが期待されるファイルのみを示すことを確認します。
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
console.error('MISSING:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
ステップ 9 — コミットしてプッシュ
- このスキルが触れたファイルだけをステージングします。
git add -Aは絶対に行わないでください。 - 正規のメッセージでコミットします:
さらに、3ステップ契約の実行を説明するボディを追加します(マージされた参照コミットの文言を参照)。feat(skills): HyperFrames をビデオプロバイダーとして配線 origin <branch>にプッシュします。ブランチにドラフト PR が存在しない場合は作成します。
出力
branch: 文字列。コミットを保持するブランチ。pr_url: 文字列。作成されたかすでに存在した場合のドラフト PR の URL。files_written: 実際に作成または変更された相対パスの配列。files_skipped_idempotent: すでに正しかったためにスキップされた相対パスの配列。verification:{ providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }。
絶対的なルール
- 冪等。 すでに統合済みのリポジトリで再実行しても、ファイルには触れません。
mainには決してコミットしない。 最初にフィーチャーブランチを作成します。エンジンのブランチポリシーは上流で強制されます。- スキル本文では契約外で
hyperframesに言及しない。 プロバイダー選択は依然としてPROVIDERS.md+lib/router.tsを通じて行われます。このスキルはブートストラップです。ランタイム選択はプロバイダーに依存しません。 - レンダリングされた MP4 や
outputs/以下のファイルは編集しない。 このスキルはエンジンの配管のみを変更します。 - 既存の
compliance-<アクティブなクライアント>スキルやクライアント固有のアーティファクトは決して削除しない。 統合は追加的なものです。
障害モード
- ステップ1の事前確認が失敗した場合(マーケティングエンジンリポジトリではない):不足しているファイルを表示し、停止します。「修正」しようとしないでください。
- 競合するコンテンツを持つファイルがすでに存在する場合(例:
.skills/hyperframes/SKILL.mdが手動編集された):正規のコンテンツとの差分を表示し、上書きする前にオペレーターに確認します。 npm run typecheckがlib/providers/に新しい TS エラーを報告した場合:停止し、エラーを表示し、コミットしません。git pushがネットワーク以外の理由で失敗した場合:停止します。ネットワーク障害はプロジェクトの git ポリシー(2秒、4秒、8秒、16秒のバックオフ、最大4回)に従って再試行されます。
関連スキル
hyperframes: ランタイムオーサリング(このスキルによってステップ2でインストールされます)。hyperframes-cli: ランタイム lint/inspect/render(このスキルによってステップ2でインストールされます)。hyperframes-prompt-builder: ランタイムスペシャリスト(このスキルによってステップ2でインストールされます)。video-prompt-builder: このスキルによってステップ3で更新されるディスパッチャー。llm-router: 無関係。LLM プロバイダールーティングは並行したディスパッチャーです。
参考アーティファクトセット
このスキルが書き込むすべてのファイルの正規の内容は、main のマージされたコミットにあります:
- スキル:
.skills/hyperframes/SKILL.md、.skills/hyperframes-cli/SKILL.md、.skills/hyperframes-prompt-builder/SKILL.md - プロバイダーレイヤー:
lib/providers/types.ts、lib/providers/matrix.ts、lib/providers/video.ts、lib/providers/__mocks__/video.ts - ルーティングマトリクス:
.specs/architecture/PROVIDERS.md - 環境設定:
.env.example - 憲章:
CLAUDE.md
疑問がある場合は、origin/main のマージされた参照コミットとの差分を確認し、正規のバージョンをそのままコピーしてください。記憶から再入力しないでください。
上流参照
- HyperFrames: https://github.com/wesleysimplicio/hyperframes
- プロジェクトスキルカタログ: https://github.com/wesleysimplicio/hyperframes/tree/main/skills