Plan to video
計画書を、ナレーション付き解説動画（ソーシャルポスト向け約60〜90秒、複数の意思決定を含む本格的な計画向け2〜2.5分）に変換します。フック、問題、提案、メカニズム、そして各未解決の意思決定に対して1フレーム（質問＋2〜4の選択肢）、最後にクロージングの呼びかけという構成です。
このスキルは HyperFrames を再実装するものではありません。ブリーフ、ストーリーの形状、セットアップを決定し、インストール済みの /faceless-explainer ワークフローをステップごとに実行し、デフォルトのパイプラインでよく壊れる箇所に修正を適用します。/hyperframes と /faceless-explainer をその指示に従って読み、このファイルは何を回答し、何をパッチするかを示します。
マシンでの初回実行時: references/setup.md を読み、その事前チェックを実行します。不足している HyperFrames スキルとローカル音声をインストールします。
設定
以下の値を最初に一度解決し、すべてのコマンドで再利用します。値が見つからない場合のみユーザーに質問してください。
| 名前 | 解決方法 | デフォルト値 |
|---|---|---|
VIDEOS_DIR | $PLAN_TO_VIDEO_DIR が設定されていればそれを使用 | カレントワーキングディレクトリ下の ./videos （faceless-explainer の慣例） |
FE_DIR | インストールされた faceless-explainer/SKILL.md が置かれているフォルダ | references/setup.md の検索方法を参照 |
MEDIA_DIR | インストールされた media-use/SKILL.md が置かれているフォルダ | 同上 |
HYPERFRAMES_PYTHON | 環境変数が設定されていればそれを使用、なければ references/setup.md の venv | ~/.hyperframes-venv/bin/python |
VOICE | ユーザーの指示、次に記憶された音声、最後にデフォルト | Kokoro am_michael （オフライン） |
1. ブリーフ（簡潔に確認、尋問はしない）
まずソース（計画書、調査メモ、チャット）を読みます。次に、以下のデフォルト値を短いメッセージで提案し、ソースから答えられない項目だけを質問します。迅速な承認はアンケートより優れています。
| フィールド | デフォルト値 | 理由 |
|---|---|---|
angle | listicle （ルートの値の1つ：concept, how-to, listicle, narrative） | 計画は「なぜ重要か、どのように機能するか、N個の意思決定」 |
ストーリーボード arc | concept-explainer with listicle | STORYBOARD.md 内の自由テキスト、ブリーフの列挙ではない |
aspect | 1920x1080 | ラップトップや通話で視聴、選択肢カードには横幅が必要 |
length | 複数の意思決定を含む本格的な計画では2〜2.5分。ソーシャルポストでは約60〜90秒。ハードキャップ180秒 | faceless-explainer の得意範囲は30〜90秒。多くの意思決定がある計画はより長くなる。意思決定1つあたり約10秒＋イントロとクロージング |
language / voice | ソースの言語。英語の場合は Kokoro am_michael | ローカルで無料。英語以外の Kokoro 音声には espeak-ng が必要 |
flow / storyboard | automation / no （自動） | 計画が重要度の高い場合はストーリーボードレビューを提案 |
| look | リポジトリに関する動画の場合はプロジェクト独自のブランド、それ以外は適切なプリセット | 動画は説明対象のように見えるべき |
music | none | ローカル MusicGen は torch が必要、HeyGen 音楽はサインインが必要 |
| project | $VIDEOS_DIR/<ケバブケースのトピック>/ | 動画1本につき1フォルダ |
最大でも、次の項目について質問します：誰が視聴するか（コピーの専門性のレベルを決定します）、そして推奨される選択肢を各意思決定にマークするかどうか（アクセントの「リーン」エッジ）。
推奨選択肢ルール：ソースが推奨する選択肢をマークします。単一の選択肢が勝っていない場合は何もマークしません。意思決定が「複数をサポート」の場合は、その回答の一部であるすべての選択肢をマークします。ソースが明示しない場合、好みをでっち上げる代わりに、このスキル自身のデフォルト（上表の値）を推奨します。
BRIEF.md はステップ0 で、npx hyperframes init の後に（init は空でないフォルダを拒否します）、/hyperframes references/brief-format.md が説明する形式で、ユーザーの発言とあなたが推測した内容を分離して記述します。
2. ストーリー形状
デフォルトのアークをソースに適応させます：
- ソースからの実数を使ったフック （「N個中M個の項目がXです」）。すべての数字はソースの一行に遡れる必要があります。統計、価格、カウントをでっち上げてはいけません。ソースに数字がない場合は、具体的な痛みで始めます。
- 2つまたは3つの名前付き原因による問題、ソースからの実際の例を用います。
- フレーム3までのテーゼまたは提案 （証拠より先に価値）。
- 1つの図フレームによるメカニズム。
- 道標 （「構築前に5つの意思決定があります」）として短いブレイク。
- 未解決の質問またはステップごとに1フレーム、すべて同じ質問ステージ（
references/question-stage.md）を使用。各フレームは質問とその2〜4つの選択肢を表示します。選択肢は音声が名前を呼ぶと同時に現れます。 - 道標を呼び戻すクロージングの呼びかけ （「これら5つに回答すれば、ステップ1は今週出荷されます」）。
ナレーションは短いキューとなるフレーズ（フレームあたり6〜25ワード）で書き、各選択肢に表示のきっかけとなる単語があるようにします。意思決定がソース内ですでに回答されている場合は、質問する代わりにアクセントで選択された回答を表示します。
3. ワークフローの実行とパッチの適用
/faceless-explainer のステップ0〜6を順に従います。各ステップで references/gotchas.md の該当するパッチを適用します。スキップすると問題が発生するパッチ：
- ステップ0: プロジェクトが
$VIDEOS_DIR/<トピック>に配置されるよう、$VIDEOS_DIRの親ディレクトリ内で init を実行し、その後BRIEF.mdを記述します。HeyGen からサインアウトしていても問題ありません。音声はローカルの Kokoro で実行されます。 - ステップ2 デザイン: リポジトリの場合、その色とフォントを
capture/extracted/tokens.jsonに配置し、実際の.woff2ファイルをassets/fonts/にステージングします。これをbuild-frame.mjsの前に行います（そうすると@font-faceブロックを自身で書き込みます）。フォントはブランド自身のサイトファイル、Google Fonts のダウンロード、またはnode_modules内のフォントパッケージから取得します。ブランドがダークでプリセットがライトの場合、frame.mdで役割を反転し、埋め込みフォントに不足している可能性のあるプリセットのグリフを置き換え、別のブランドに属するプリセットのアクセントをユーザー自身のものと交換します（references/gotchas.md、ステップ2）。 - ステップ3.1 オーディオ: デフォルトの
python3がすでにkokoro_onnxをインポートできる場合を除き、すべてのオーディオコマンドでHYPERFRAMES_PYTHONを渡します。 - タイミング: オーディオを完了させ、ステップ4 の Scene ウィンドウを記述する 前 に
audio.mjs sync-durationsを実行し、その後audio_meta.jsonの実際のワードタイミングに基づいてすべてのリビールを調整します（faceless-explainer は sync-durations をステップ5 で実行します。この順序を早めるのは意図的です）。 - 余裕の確保: sync-durations は各フレームを正確な音声長に設定するため、最後のフレームと道標が突然終わります。sync の直後に、
STORYBOARD.mdの- duration:を編集します。最終フレームは +2〜3 秒、道標とその他のブレイク用フレームは +1 秒。パケットをビルドする前に行い、ワーカーがパディングされたウィンドウに対してアニメーションを実行できるようにします。 - キャプションワード: キャプションは音声の文字起こしから生成されるため、
SCRIPT.mdからではなく、製品名が誤認識される可能性があります。キャプションがビルドされる前に、audio_meta.jsonの単語リスト（voices[].words[].text）をSCRIPT.mdと比較し、誤認識された単語をタイミングを維持したままその場で修正します。 - ステップ5 ディスパッチ前: すべてのワーカーにステップ2でステージングされた正確なフォントファイル名を渡します。パケットはストーリーボードの
## Video directionブロックと完全なワードタイミングを省略するため、両方を各ワーカーのディスパッチコンテキストに貼り付けます。質問ステージのフレームには共有仕様をそのまま貼り付けます。絵文字を禁止します。 - ステップ5: フレームごとに1ワーカー、エージェントがサブエージェントをサポートする場合は並列実行（ワーカーには高速なモデルで問題ありません）。各ワーカーに
_role.md、そのパケット、ディスパッチコンテキストを与えます。 - ワーカー後: アセットパスを正規化し、実際のシークバグである lint 警告を修正し、
checkを実行し、スナップショットを撮り、コンタクトシートを確認します。
4. 品質ゲート（すべてレンダリング前）
npx hyperframes lintでエラー0。studio_missing_editable_id警告は軽微。gsap_repeated_fromto_without_baselineは実際のバグなので修正します（references/gotchas.md、ステップ6）。npx hyperframes checkがパスすること。npx hyperframes snapshot --at <各フレームの中間点>を実行し、実際にコンタクトシートを確認します。暗い背景に暗いテキスト、フォントの欠落（セリフフォールバック）、カードのクリッピング、絵文字の tofu などがすべて表示されます。- ユーザーにハウススタイルがある場合（例：「em ダッシュは使わない」）、すべての文字列をチェックします。
- voiceover:行、SCRIPT.md行、compositions/frames/*.html内のテキスト、見出しも同様です。見出しはコロンを使って記述します（## Frame 1: Hook、## Line 1: Hook (Frame 1)）。ストーリーボードとスクリプトパーサーはこれを受け入れるため、ダッシュは一切不要です。
5. レビュー、レンダリング、引き渡し
faceless-explainer のステップ6 は、自動モードでも1つの質問を残します。npx hyperframes preview --background を開き、「今レンダリングしますか？それとも変更しますか？」と尋ねます。ユーザーがワンショットレンダリングを要求した場合は、その質問をスキップします。その後：
npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4 （--skill は匿名レンダリングテレメトリにタグを付けるだけ。high は delivery のエイリアス）
ユーザーが希望する場合のみ MP4 を開きます（macOS では open、Linux では xdg-open、Windows では start）。次の項目を報告します：MP4 のパス、実際の長さ（ffprobe -v error -show_entries format=duration -of csv=p=0 renders/video.mp4）、フレーム ID 付きのフレームリスト（compositions/frames/NN-*.html。個々のフレームを修正可能）、コンタクトシートのパス、スキップされたもの（音楽なし、誤発音された単語、ソースにないために省略された事実）。
参考ファイル
references/setup.md：新しいマシンでのインストールと事前チェック（HyperFrames スキル、Kokoro venv、ffmpeg、Chrome）。references/question-stage.md：意思決定フレームとステップフレーム用の共有レイアウト仕様。それらのワーカーのディスパッチコンテキストに貼り付けます。references/gotchas.md：ワークフローステップごとの環境およびパイプラインの修正。コマンド付き。