pr-to-video - ディスパッチエントリ
入力はGitHubプルリクエスト(コード変更)で、PRのURL、<owner>/<repo>#<N>形式の参照、または開いているPRがあるリポジトリをチェックアウトしている場合は「this PR」として指定します。出力はコード変更の説明ビデオです。何が出荷され、なぜ、どのように動作するかを、差分/コミットからビフォー/アフター、差分強調、ファイルツリー、インパクトシーンとしてレンダリングします。デフォルトの長さは最大約3分(最適な長さは約30〜90秒)。本当に長い、または全てのファイルを詳細に説明するウォークスルー(5分以上)は別のレジスターとなるため、/general-videoを使用します。インジェストのためのウェブサイトスクレイピングやヘッドレスChromeはありません — インジェストはghCLIを使用します。出荷時のスタイルプリセットは常にclaude(温かみのある編集、特徴的なネイビーのコードウィンドウ)です。
Step 0の前にルートを確認してください。 このスキルはGitHubプルリクエスト(
ghを介して読み取るコード変更)を説明します。入力がマーケティング/製品サイトの場合 →/product-launch-video;一般ウェブサイトの場合 →/website-to-video;PRのないトピック/記事の場合 →/faceless-explainer;リポジトリ全体のツアーや複数PRのリリースの場合 →/general-video。対象外: ライブ/レンダリング時のデータ — PRの事実は作成時に一度だけ読み取られ、組み込まれます。PR以外の入力が渡された場合、または不明な場合は、まず/hyperframesを読んでください。
このワークフローはPR固有のフロント部分(インジェスト + ストーリーデザイン)のみを担当します。_共有_とマークされた各フェーズは、faceless-explainerから変更せずにコピーされたエンジンを再利用します(このスキル自身のscripts/ + agents/ + phases/の下に存在するため、<SKILL_DIR>はpr-to-videoに解決されます)。
すべてのアーティファクトはPROJECT_DIR = videos/<project-name>/に出力されます(Step 0で作成)。以下のすべてのパスはこれを基準とします。ディスパッチはハーネスに依存しません:最初のサブエージェントディスパッチの前に、<SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.mdを一度読んでください。これはディスパッチ動詞(パラレルファンアウト/バックグラウンド/待機)をハーネスのプリミティブにマッピングします。同時実行数の上限はN未満という意味で、上限サイズの波となり、ワーカーが減ることはありません。このファイルは背景読み物ではなく、拘束力のある実行手順書です:ステップを順番に実行し、指定されたスクリプトまたはエージェントロールですべてのフェーズアーティファクトを生成してください。自由形式のパイプラインに置き換えたり、リクエストが明確に見えるからといってポーズステップをスキップしたりしないでください。実行できないステップがある場合は、停止して報告してください。
| フェーズ | 実行 | 主要なアーティファクト | 詳細なフロー |
|---|---|---|---|
| init | Bash | hyperframes.json | Step 0 |
| ingest(独自) | Bash(gh CLI + ingest.mjs + fetch-people-avatars.mjs、エージェントなし、スクレイピングなし) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | Step 1 |
| design-system(共有) | Bash(エージェントなし、決定論的claude) | design-system/design.html + chunks/ | Step 1b |
| story-design(独自) | サブエージェント | narrator_scripts.json | agents/story-design.md |
| audio(共有) | Bash内のaudio.mjs | audio_meta.json | phases/audio/guide.md |
| visual-design(共有) | サブエージェント | section_plan.md | agents/visual-design.md |
| prep(共有) | Bash内のprep.mjs | group_spec.json | scripts/prep.mjs |
| captions(共有、詳細) | captions.mjs group -> captions.mjs html(Bash内、サブエージェントなし) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| scenes(共有) | N x サブエージェント(パラレル) | compositions/scene_*.html または compositions/group_w*.html | agents/hyperframes-scene.md |
| finalize(共有) | Bashプレリュード(wait-bgm + assemble + inject/verify-transitions + hoist-videos + sfx-verify + preflight) -> finalizeサブエージェント(発見された簡単な問題をその場で修正 + 1つのリーンなコンタクトシートルック + レンダリング) | renders/video.mp4 | Step 7 / agents/hyperframes-finalize.md |
前提条件
macOS Apple Silicon または Linux x64。システムツール:brew install [email protected] node ffmpeg(HomebrewのPythonを使用し、/usr/bin/python3は使用しないでください。使用するとPEP 668によりpip installがブロックされます)。その後、npx hyperframes doctorを一度実行します(Chromeをダウンロード — スナップショット/レンダリングに必要、インジェストには不要)。レンダリングされたオーバーラップゲート(scripts/check-overlap.mjs、ワーカーのセルフチェックとプレフライトで実行)は同じキャッシュされたChromeを再利用します。ブラウザをダウンロードすることはありません。唯一の依存関係はpuppeteer-core npmモジュールで、シーンファンアウト前に一度だけ確認されます(Step 5.5、--ensure-deps、約5秒、完全なpuppeteerインストールは不要)。CLI:gh(GitHub CLI、認証済み — gh auth statusが成功する必要あり)とhyperframes。オプションのクラウドキー(なければローカルフォールバック)— Step 0.5で注入:
| キー / 要件 | 使用用途 | デフォルト / フォールバック |
|---|---|---|
gh auth status OK | PRの読み取り(公開またはプライベート) | 必須 — 認証ヒントとともに即座に失敗 |
HEYGEN_API_KEY(またはhyperframes auth login) | TTS(クラウド、ワードレベルのタイムスタンプ) | 音声:自動(最初の英語Starfish音声;--voiceで上書き) |
ELEVENLABS_API_KEY | TTS(クラウド;pip install elevenlabsが必要) | 音声 21m00Tcm4TlvDq8ikWAM (Rachel) |
| どちらもなし、かつログインしていない | TTS | ローカルKokoro、音声 am_michael(非英語:--voiceを渡す) |
GEMINI_API_KEY / GOOGLE_API_KEY(エイリアス) | Lyria BGM | 未設定 -> ローカルMusicGen(初回実行で約300 MBダウンロード) |
フロー
Step 0.0 - ブリーフの確認(常に1ラウンド質問してから構築する)
Step 0の前に、常に一時停止して1つのメッセージでブリーフを尋ね、ユーザーの返信を待ってください。リクエストが完全に見える場合でも、これを省略しないでください。 各フィールドに推奨デフォルト値を先に提示し、ユーザーが既に指定したものは事前に入力してください(盲目的に再質問するのではなく確認する):アングル(changelog / feature reveal / fix / refactor — デフォルト:PRから推測)、オーディエンス(開発者 vs 一般ユーザー — デフォルト:開発者)、長さ(デフォルト約60-90秒)、そして—/hyperframesで設定されていない場合—アスペクト(デフォルト16:9)と言語。スタイルは常にclaudeです。ユーザーが返信してからStep 0に進んでください。「go」/「use the defaults」はすべてのデフォルトを受け入れる有効な返信です。
Step 0 - ビデオプロジェクトの初期化
cwdはエージェントのワークスペースルート(例:/tmp/pr-video-...)です。すべてのビデオアーティファクトをPROJECT_DIR = videos/<project-name>/の下に書き込みます。
<project-name>:ユーザーが指定したディレクトリを使用します(例:./videos/retry-prを使用)。それ以外の場合は、PRから派生した短いkebab-case名(<repo>-pr-<N>、例:widgets-pr-1187)を使用します。ワークスペースのベース名やタイムスタンプは使用しないでください。
$PROJECT_DIR/hyperframes.jsonがない場合のみ:
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes initは汎用のAGENTS.md/CLAUDE.mdを$PROJECT_DIRに配置します。そのままにしておいてください — これらは後で完成したプロジェクトを開く人のためのエージェントスキャフォールディングです。
制約: ワークスペースルートでhyperframes initを実行したり、AGENTS.md / CLAUDE.mdを生成したりしないでください。PROJECT_DIR内にhyperframes/をネストしないでください。すべてのBashコマンド(マスター+サブエージェント)は(cd "$PROJECT_DIR" && ...)サブシェル内で実行してください。裸のcdは使用しないでください。
Step 0.5 - APIキーガイダンス
$PROJECT_DIR/.envが存在する場合、またはcontext.logが空でない場合(=初回実行でない場合)はスキップします。それ以外の場合は、まず利用可能なものを検出し($HEYGEN_API_KEY / $HYPERFRAMES_API_KEYが設定されているか、hyperframes auth loginから~/.heygen/credentialsが存在する場合はHeyGen TTSオン;ElevenLabs / Geminiはそれぞれの環境キーが設定されている場合のみ)、その後常に一時停止してメニューを表示し、ユーザーの入力を待ってください。動作可能な設定が検出された場合でも、自分だけで先に進まないでください(ユーザーがGeminiなどのキーを追加したい場合があります)。検出された内容を伝えた後、以下のいずれかを行います:キーを貼り付ける(→ $PROJECT_DIR/.envにKEY=valueの形式で1行ずつ書き込み、同名のキーは上書き)/ 「go」(現在の設定 — env、.env、またはhyperframes auth login — で進む)/ 「skip」(設定されていないものはローカルフォールバックで進む)。その後、Step 1に進みます。
Step 1 - インジェスト(Bash、エージェントなし、スクレイピングなし)
PR参照を解決し、ghを使用して構造化された事実を取得し、共有バックエンドが期待する合成キャプチャパッケージに変換します(faceless-explainerのスクレイピングなしスキャフォールドをミラーリング)。ghはここ、オーケストレーター内で実行されるため、認証/未検出/プライベートリポジトリエラーはgh自身のstderrで表示されます。ingest.mjsは純粋なオフライン変換です。
# PR参照:完全なURL、"<owner>/<repo>#<N>"、またはチェックアウトされたリポジトリ内の"<N>"
PR="<url | owner/repo#N | N>"
# ghが認証されていない場合は即座に失敗
gh auth status || { echo "ghが認証されていません — 実行: gh auth login"; exit 1; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# pr.json + diff.patch を tokens.json(colors:[] → claudeネイティブパレット)+
# visible-text.txt(ナラティブブリーフ)+ people.json(PR作成者 + コミット作成者 カウント付き +
# レビュアー/コメンター/アサイン、ボットフィルター&重複除去、各GitHubアバターURL付き)に変換
# (PR `author`は開封者のみ;commits[].authors[]からのコミット作成者も追跡)
# ingestはOFFLINE
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# ネットワークステップ(peopleフロント唯一のもの — ingestはオフラインのまま):各コントリビューターの
# GitHubアバターをpublic/avatars/<login>.pngにダウンロード(オプションのクレジット/
# shipped-byクローズ用)。ベストエフォート — アバターがないかオフライン実行でもブロックされない(exit 0)。
# アバター+そのクローズは、pr-to-videoがfacelessデフォルトを緩和する唯一の場所です。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
検証:
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo missing
# public/avatars/ はベストエフォート — 欠落は失敗ではありません(アバター未解決 / オフライン)
ghがエラーになった場合(認証/未検出/プライベート)、正確なstderrを報告して停止してください — PRの内容をでっち上げないでください。ingest.mjsが終了…
[翻訳のため省略]