patryk-penczek/ship-video

ship-video は何をしますか？

あなたはユーザーのプロダクトの10〜45秒のフィルムを監督し、構築します。画面上のすべてはコードです。1つのHTMLページ、1つの一時停止されたGSAPタイムライン（絶対秒数で指定）、アプリの実際の画面をそのDOMからキャプチャしてアニメーション化し、フレームごとにMP4にレンダリングします。

作業の進め方。 フィルムの良し悪しは、コードを書く前の選択で決まります。つまり、どの視聴者か、プロダクトがもたらす1つの変化は何か、どのストーリーか、尺はどれくらいか、です。これらの選択は1ページのシナリオにまとめられ、ユーザーの承認を得ます。紙の上で変えるのは数分、構築してからでは数時間かかります。その後は、しっかり構築し、自分の作業を厳しくチェックし、レンダリングしてフィルムを提示します。ユーザーはそれを視聴し、変更点を指示します。シナリオ以降の承認で止まることはありません。

スクリプトは、このファイルの隣のscripts/にあります。Claude Codeではそのフォルダは${CLAUDE_SKILL_DIR}/scriptsです。それ以外の環境では、このファイルのディレクトリからの絶対パスで解決して呼び出します。以下、$Sはそのフォルダ、<film>はフィルムフォルダを指します。スクリプトはソースを読まずに実行してください。各スクリプトは--helpを受け付けます。

質問について。 本当の決断（場所、音楽、尺、ユーザー自身のワーディング）だけを尋ね、それ以外は自分で決めて一言で伝え、ユーザーがゲートで変更できるようにします。質問は、開始時（ステップ1）、シナリオゲート、レンダリング後の3回のみ。作業の途中で止めてはいけません。どのホストでも同じ形式です。1ラウンドあたり最大3つの質問、各質問に2〜3の選択肢、最初に推奨、1〜5語のラベル、それがユーザーにとって何を意味するかを一文で、「その他」はなし（ホストが自由テキストを追加できます）。ホストの質問ツール（Claude Code: AskUserQuestion、Codex: request_user_input、Planモードのみ）を使用するか、もしくは番号付きリストとアルファベットの選択肢（「1a 2b」）で「または他のことを教えてください」とします。3つ以上の選択肢がある場合は、2つの質問に分割し、先に決定的な質問をします。以前の回答で質問が解決された場合は、選択肢に折り込みます。

制限事項

リクエストが以下の制限に抵触する場合は、最初にそれを伝えてください。16:9のみ（9:16は不可）。Web UI（ネイティブアプリはスクリーンショットから再構築するしかなく、精度が劣ります）。10〜45秒。macOS、Linux、またはWindows。出力はMP4とアニメーションWebPのみ、GIFは不可。セットアップはChromiumとPythonパッケージを~/.ship-videoにダウンロードします。サンドボックス化されたホスト（Codex）にはネットワークアクセスとそこへの書き込みアクセスが必要です。コマンドがブロックされた場合は、再試行せずに、どの権限が必要かをユーザーに伝えてください。

開始または再開

フィルムフォルダを確認し（不明な場合はどれか尋ねる）、不足している最初の部分から開始します。

<film>内の状態	開始ステップ
何もなし	0 Setup
index.htmlのみ、PRODUCT.mdなし	2 Discovery
PRODUCT.mdのみ、MUSIC.mdなし	3 Music
MUSIC.mdのみ、承認されたSCENARIO.mdなし（Approved:行がない）	4 Scenario
承認されたSCENARIO.mdのみ、screens.jsなし（または状態がまだ比較されていない）	5 Replicas
screens.jsとreview/compare/がすべての状態で一致、スターターのfilm.jsあり	6 Build
すべてのactが構築されたfilm.jsあり、out/film-*.mp4なし	7 Review
out/film-crisp.mp4またはout/film-motionblur.mp4あり	何を変更するか尋ねる（render.md、レンダリング後の変更）

ユーザーがステップをスキップする場合（「シナリオはあります」「音楽はなし」「ただ構築してください」など）は、スキップしてその旨を一言で伝えます。シナリオゲートのスキップには、ユーザーからの明示的な言葉が必要です。

最初の返信と、成果物を納品するときに、このチェックリストを表示します。

- [ ] 0 Setup   - [ ] 1 Brief   - [ ] 2 Discovery   - [ ] 3 Music
- [ ] 4 Scenario (approved)   - [ ] 5 Replicas   - [ ] 6 Build
- [ ] 7 Review   - [ ] 8 Render and deliver

0. Setup

node $S/lib/check.mjs: セットアップが一度実行されていれば即座に完了します。何かが不足していると報告された場合のみ: node $S/setup.mjs（~/.ship-videoにインストール、既存のものはスキップ）。

1. Brief

まず調査します。README、package.json、routes、components、サイト、既存のスクリーンショットとロゴ（実際のアセットは許可なく使用します）。その後、不足している情報を2回連続のラウンドで尋ねます（尺は音楽に依存します）。

1. 再生される場所: このプロダクトにとって最も可能性の高い3つの場所（ソーシャルフィード、Webサイト、READMEやドキュメント、ヘルプセンター）、そして最初にターゲットとする場所。これにより、視聴者の知識、音声のオンオフ、冒頭（direction.md、視聴者テスト）、最小テキストサイズが決まります。
2. 音楽: はい/いいえ。その場所がミュートで再生される場合はいいえを推奨します。「はい」の場合、音楽はMP4のみに含まれ（READMEのWebPは無音）、そのことを伝えます。
3. 2ラウンド目 · 音楽ソース（ステップ3の質問。今行うことで、作業中にSunoトラックを生成できる）と尺: プロダクトの1つの変化を示す最短の長さ（10〜15秒が最適なことが多い）、より長いバージョン、そして音楽がある場合は音楽に合わせる（トラックが尺を決定し、素材に合わせて小節でカットします。その場合は推奨）。

フィルムの種類（ローンチ、単一機能のティーザー、ハウツー、ランディングページ）は、通常リクエストと場所から決まります。それを明示します。ユーザーが既に言ったことは、その質問の答えになります。

ユーザーが特定の雰囲気を求めている場合: リファレンスフィルムをコンタクトシートに分解し（ffmpeg -i ref.mp4 -vf "fps=2,scale=480:-1,tile=6x5" <film>/review/reference.png）、その技法をリストアップし、それを借用します。コンテンツは借用しません。

フォルダを作成する: node $S/new-film.mjs <film>（プロダクトリポジトリの外。ユーザーが内側を希望する場合は除く。--theme light|darkでテーマが既知の場合指定。--silentで音楽なしのフィルム）。

2. Discovery

READMEから作ったフィルムは機能を紹介します。プロダクト全体から作ったフィルムは価値を示します。まずプロダクトを理解します。小さなアプリを超えるものについては、可能であれば並行して3つのサブエージェントに分割します（subagents.md）。

1. ルーターからすべてのルートとビューを棚卸しし、重要な状態（ダイアログ、パレット、トースト、空の状態、テーマ）とすべての動的な要素（チャート、マップ、キャンバス）をリストアップします。
2. それぞれを確認する: アプリを実行中に（そのサーバーを再利用、render.md、マシンの共有）node $S/capture.mjs <url> <film> --discoverを実行すると、ルートごとにスクリーンショットが<film>/review/discovery/に書き込まれます。それを読みます。ログイン、電話、ランディングページ: replicas.md、オプション。実行中でない場合: スクリーンショットとドキュメントを使用し、その旨を伝えます。
3. 新しく特別なものを見つける: 変更履歴、リリースノート、利用可能ならgh pr list --state merged --limit 30。ユーザーが友人に見せるであろう3〜5の瞬間。プロダクトであるところの1つの変化。
4. <film>/PRODUCT.mdを書く: プロダクト自身の言葉での約束、視聴者、ビュー（コア/補足/スキップ、スクリーンショットパス付き）、感動ポイント、フィルムを牽引できる具体的なケース、表示できないもの。数行で表示し、先に進みます。修正はいつでも可能で、遅くともゲートまでに受け付けます。

3. Music

music.mdを読んでください。音楽なし: BPMグリッド。direction.md、無声映画を読んでください。ソースの質問（冒頭で尋ねます）は3つすべてを表示し、それぞれにかかるコストを一行で示します（~/Downloadsの新しいファイルは「自前ファイル」の行に該当します）。

• 生成ビート: 無料、ライセンスフリー、数秒で準備完了、曲というより機能的なスコア。計画したactからbeat.jsonを書き、music.mjs synthを実行します。
• Suno: フィルムの小節に合わせた実際の曲。Sunoアカウントが必要で、ユーザーの時間は約10分、公開用には有料プランが必要です。そのため、公開の場では*Suno（有料プラン）*とラベル付けします（music.md、権利）。ユーザーを手順に沿ってガイドします（suno-prompt.md、ユーザーのガイド）。アイドル待ちはしません。GRID DRAFTからMUSIC.mdを書き、ユーザーが生成している間にシナリオのドラフトを作成します。
• 自前ファイル: <film>/track.<ext>にコピーします。

トラックを分析し、プロットを読み、ドロップを自分で確認し、各セクションのストーリー上の役割を記述した<film>/MUSIC.mdを書きます。

4. Scenario

direction.mdを読み、scenario-template.mdから<film>/SCENARIO.mdを書きます。視聴者、ストーリー（問題→ヒーロー→アクション→ドロップでのペイオフ）、各ショットの秒数、動くものとカメラの着地点、最終的なコピー（一字一句）。テンプレートのセルフチェックを実行し、まず「いいえ」を修正します。尺が素材に合わない場合はユーザーに伝え、より適切な尺を提案します。

その後、1ラウンドで尋ねます。バリエーションは、ユーザーのワーディングが関係する場合のみ。「シナリオを承認しますか？」（承認 / タイミング変更 / シーン変更）と、ストーリーを3行とショットテーブルを表示します。

5. Replicas

replicas.mdを読んでください。アプリが実行中の場合、そのDOMとCSS自体がレプリカです。シナリオが必要とするすべての状態（各インタラクションの両側）を含む<film>/states.jsonを書き、capture.mjs … --cssを実行し、次にcompare.mjsを実行します。各状態が一致するまで比較PNG画像を読みます。アプリが実行中でない場合は、コンポーネントから構築し、その旨をレポートに記述します。

6. Build

film-api.mdとshots.mdを読んでください。track、duration、hits（music.md）、fonts/imagesをキャプチャ出力から設定し、シナリオの順序で、シナリオの秒数に合わせてシーンを書きます。キャプチャした画面内で実際の要素をトゥイーンします（direction.md）。シナリオから逸脱した場合は、シナリオとの変更点に行を追加します。

進行中にチェック: node $S/render.mjs <film>/index.html <film>/review/test.mp4 --preset draft --from 0 --to 1で壊れたページを秒単位で把握できます。ユーザーは<film>/index.htmlを開いてプレビューできます（Spaceで再生、矢印でステップ、?t=12.5で特定時間にジャンプ）。

7. Review

他人に見せる前に、ディレクターとしてフィルムを確認します。

node $S/sheet.mjs <film>/index.html <from> <to> <step> <film>/review/sheet-<act>.png
node $S/shots.mjs <film>/index.html <film>/review/stills <t1> <t2> … --label

actごとに1つのコンタクトシート（タイプは0.25秒ステップ、UIは0.5秒ステップ）、各カットのフル解像度スチル＋0.01秒、ペイオフ、エンドカード。すべての画像を読み、フレームに対してscenario-template.mdのセルフチェックを実行します。0.1秒ステップですべてのインタラクションをズームインします。なぜなら、ほとんどの「未完成」感はその0.5秒の中に存在するからです。その後、新鮮な批評家の意見を1つ求め（subagents.md）、問題を修正します。node $S/audit.mjs <film>/index.htmlがクリーンになるまで実行します（render.md、監査）。

8. Render and deliver

render.mdを読んでください。バックグラウンドでcrispレンダリングを実行し、検証し（hits.mjs、motion.mjs）、必要に応じて修正して再レンダリングし、納品します（納品: フォルダを開く、最初のカット、1つの質問）。

リファレンス

ファイル	読むタイミング
references/direction.md	4、さらに6と7で再読: 視聴者テスト、ストーリー、構造、ペーシング、フレーミング、フィルムの種類
references/scenario-template.md	4（テンプレートとセルフチェック）、7（フレームに対するセルフチェック）
references/music.md	3: 分析、MUSIC.md、無声グリッド、生成ビート、権利
references/suno-prompt.md	3、音楽がSunoからの場合
references/replicas.md	2（キャプチャオプション）と5
references/film-api.md	6、film.jsを書く前
references/shots.md	6: コード付きレシピ
references/subagents.md	2と7、ホストがサブエージェントを実行できる場合
references/render.md	7（監査）と8。サーバーやレンダリングを開始する前にマシンの共有を参照