hatch-pet

ハッチペット

概要

コンセプト、ブランドを示す手がかり、会社名または見込み顧客名、1 枚以上の参照画像、あるいはこれらを組み合わせて、Codex 互換のアニメーション付きペットを作成します。このワークフローでは、アトラスのジオメトリ、検証、ビジュアル QA、パッケージングには決定論的なハッチペットのパイプラインを維持しながら、状態ごとの簡潔なプロンプトを使用し、ペットに適したあらゆるビジュアルスタイルを利用できます。

ユーザー向けの入力は任意です。ユーザーがペットの名前を省略した場合は、コンセプト、ブランド、会社名、または参照ファイル名から推測してください。それができない場合は、短く親しみやすい名前を選んでください。ユーザーが説明を省略した場合は、コンセプトまたは参照画像から推測してください。ユーザーが参照画像を省略した場合は、まずテキストからベースのペットを生成し、そのベースをすべてのアニメーション行の標準参照として使用してください。

生成の委任

通常のビジュアル生成にはすべて $imagegen を使用してください。

ベースアート、行ストリップ、または修復行を生成する前に、インストール済みの画像生成スキルを読み込み、それに従ってください。

${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md

Image API、画像 CLI、その他の画像生成手段を直接呼び出さないでください。組み込みの手段を優先するパスとフォールバックのルールは、$imagegen に選択させてください。フォールバックに確認が必要だと $imagegen が伝えた場合は、続行する前にユーザーに確認してください。

$imagegen を呼び出す際は、生成したペットのプロンプトを正式なビジュアル仕様として渡してください。ペットのプロンプトは簡潔にし、状態に即したスプライト制作向けの内容とし、列挙された入力画像に基づくものにしてください。より詳細なポリシーと QA ルールは、このスキルと決定論的なレビュー用スクリプトに記載し、各画像プロンプトに過剰に盛り込まないでください。プロンプトを汎用的な $imagegen 共通プロンプトスキーマで囲まないでください。

このスキルのスクリプトは、レイアウトガイドとプロンプトの準備、承認済みの running-left の反転、フレームの抽出、行の検証、最終アトラスの合成、コンタクトシートとモーションプレビュー用 QA メディアの作成など、決定論的な画像処理のみに使用してください。マニフェストの更新、パッケージング、クリーンアップは、親プロセスがシェル／jq の手順で行います。

ストレージ制御

組み込みの $imagegen パスでは、${CODEX_HOME:-$HOME/.codex}/generated_images にファイルも書き込む場合であっても、生成された PNG のバイト列が、それを呼び出したロールアウトに保存されます。後でファイルを削除すればファイルシステムの使用量は減りますが、すでに書き込まれたロールアウトのサイズは小さくなりません。画像生成は分離し、範囲を限定してください。

• ビジュアルの各ジョブには、軽量な生成ワーカーを 1 つだけ使用してください。複数のベース／行ジョブを同じワーカーでまとめて処理しないでください。
• ワーカーが返す内容は selected_source=... と qa_note=... のみにしてください。最終応答に Markdown の画像プレビュー、base64、その他のビジュアル添付を含めてはいけません。
• 親プロセスは生成された PNG をすべて目視確認してはいけません。各ジョブの確認にはワーカーの QA を使い、最終コンタクトシートのみを確認してください。
• 選択した生成出力を decoded/ にコピーしたら、選択元が ${CODEX_HOME:-$HOME/.codex}/generated_images 内にある場合は元ファイルを削除し、可能であれば空になった生成ディレクトリも削除してください。
• ストレージに配慮が必要なフル実行では、利用可能な場合、$imagegen CLI フォールバックを使用するかユーザーに確認してください。このパスにはローカルの API 認証情報とユーザーによる明示的な確認が必要ですが、組み込み画像ペイロードがロールアウトのイベントに埋め込まれるのを避けられる場合があります。

ブランドの調査

ユーザーが具体的なアバターの説明や参照画像ではなく、ブランド、会社、製品、見込み顧客の名前を提示した場合は、ペットの実行を準備する前に、簡易調査を行うサブエージェントを実行してください。調査ワーカーはウェブ検索を使用し、ブランドのサイト、製品ページ、ドキュメント、会社概要ページ、プレスページ、ブランドページなどの公式情報源を優先してください。公式ページの情報が不足している場合に限り、信頼できる二次情報源を使用してください。検索範囲は絞り、ビジュアルとパーソナリティの手がかりを抽出するのに十分な範囲にとどめ、市場調査の概要にはしないでください。

ユーザーが具体的なマスコット／アバターの説明や参照画像をすでに提供している場合は、ユーザーが明示的にブランド調査を求めない限り、調査を省略してください。

調査ワーカーの責務：

• ウェブを検索し、公式ページを優先して、関連する情報源を2〜4件探す
• 固定的な項目の羅列ではなく、状況に応じた Markdown の概要を作成する
• アイデンティティ／カテゴリ、対象ユーザー／利用状況、ビジュアルシステム、パーソナリティ／トーン、製品／分野のモチーフ、マスコットへの反映の手がかり、避けるべき要素、根拠／確度を扱う
• 情報源から推測したマスコットのガイダンスには、推測であることを明記する
• ロゴ、判読可能なマーク、UI のスクリーンショット、スローガン、テキストの複製を避ける
• brand_name、brand_brief、avatar_seed、avoid、brand_sources のみを含む簡潔な Generation handoff セクションで締めくくる
• 画像の生成、実行フォルダーの準備、無関係なファイルの編集は行わない

この調査ワーカーのプロンプトを使用してください：

Research a brand for hatch-pet mascot creation.

Brand/product/prospect: <brand name>
User context: <short user request>
Output file: <absolute path to brand-discovery.md>

Use web search. Prefer official brand, product, docs, about, press, or brand pages. Use reputable secondary sources only if official sources are too thin. Write an adaptive markdown brief to the output file. Headings may flex by brand, but the brief must cover:
- identity/category: canonical name, product type, what it does
- audience/use context: who it serves and where it appears
- visual system: palette, shapes, line quality, materials, typography feel, iconography, patterns
- personality/tone: emotional traits, energy, formality, playfulness
- product/domain motifs: objects, workflows, verbs, metaphors, environments
- mascot translation cues: candidate forms, signature traits, props, what must read at pet size
- avoidances: logos/text, trademark-sensitive elements, misleading cues, competitor confusion, poor mascot fits
- evidence/confidence: source URLs plus notes where evidence is weak or inferred

Do not copy logos, readable marks, UI screenshots, slogans, or text. Clearly label mascot guidance that is inferred rather than directly sourced.

End the brief with a `Generation handoff` section containing exactly:
- brand_name=<canonical brand/product name>
- brand_brief=<one sentence, max 45 words, covering palette/tone/domain motifs/personality>
- avatar_seed=<short mascot-safe visual idea, no logo copying>
- avoid=<short comma-separated list>
- brand_sources=<comma-separated source URLs>

Return exactly:
brand_discovery_file=<absolute output file path>
brand_name=<canonical brand/product name>
brand_brief=<same compact sentence from Generation handoff>
avatar_seed=<same short seed from Generation handoff>
avoid=<same short avoid list from Generation handoff>
brand_sources=<same comma-separated URLs from Generation handoff>

親エージェントは、実行を準備する前に Markdown の概要を保存し、--brand-discovery-file とともに --brand-name、--brand-brief、繰り返し指定する --brand-source、およびユーザーがより適切なアバターの説明を提供していない場合は avatar_seed を基にした簡潔な --pet-notes の値を prepare_pet_run.py に渡してください。概要全体はレビュー用に保持し、プロンプトの形成には簡潔な引き継ぎ項目のみを使用してください。ウェブ検索が利用できず、ユーザーがブランド名だけを提示した場合は、生成前にブランドの手がかりを尋ねてください。

通常のペット実行では、ビジュアル生成ジョブは最大10件です。内訳はベースのペット1件と、行ストリップジョブ9件です。Codex アプリの仕様では、現在、idle、running-right、running-left、waving、jumping、failed、waiting、running、review の9つの状態をすべて使用します。決定論的なビジュアル派生は running-left のみです。running-right の生成、目視確認、安全にミラーリングできるという明示的な承認がすべて完了した後に限り、running-right を反転して生成してもかまいません。ミラーリングが適切でない場合は、通常の接地した $imagegen 行として running-left を生成してください。

ビジュアル出力を選択した後、親エージェントはその画像そのものをジョブの decoded/ パスにコピーし、imagegen-jobs.json でジョブを完了済みにします。行の出力を生成するヘルパースクリプトを作成しないでください。決定論的な Python スクリプトで処理できるのは、すでに生成されたビジュアル出力のみです。

プロンプトのみでよいのはベースジョブだけです。$imagegen で生成するすべての行ストリップジョブには、選択したベース出力をコピーした後に作成される正規のベース参照を含め、imagegen-jobs.json に記載された入力画像を使用してください。接地用画像を添付せずに生成された行は、無効として扱ってください。

ペットに安全なスタイル

デフォルトのスタイルは auto です。ユーザーのプロンプトと参照画像からペットのスタイルを推測し、すべてのコマでそのスタイルを保ちます。ユーザーがスタイルを指定した場合は、それに従ってください。利用可能なスタイルプリセットには、pixel、plush、clay、sticker、flat-vector、3d-toy、painterly、brand-inspired、auto があります。

ペットに安全な状態を保てるのであれば、どのスタイルでもかまいません。

• 192x208 のセル内で全身のシルエットが読み取れる、コンパクトな形状
• すべてのコマで統一された顔、プロポーション、素材、配色、小道具
• きれいに除去できるクロマキー背景
• ペットのサイズでも読み取れる大きさのディテール
• ユーザーが承認済みの参照アートを明示的に提供し、それらを含めるよう求めない限り、テキスト、ラベル、UI、判読可能なロゴを含めない

ピクセル以外のスタイルも同等に扱います。プラッシュ、クレイ、ステッカー、ベクター、3D トイ、絵画調のマスコット、インク、ブランド風のスタイルは、アトラスと視認性の制約を満たす場合に受け入れてください。

透明度とエフェクト

ペットのコマは透明な 192x208 セルに加工されるため、生成されるすべてのピクセルはペットのスプライトに属するか、きれいに除去できるクロマキー背景でなければなりません。装飾的なエフェクトより、ポーズ、表情、シルエットの変化を優先してください。

透明度の不変条件は決定論的なラスターパイプラインで管理します。完全に透明になるピクセルは、隠れた RGB の残留値が残らないよう正規化されます。また、書き出されたファイルがこの不変条件に違反している場合は、アトラスの検証を失敗させてください。色付きのハローや透明ピクセルの残留値を、見た目に一貫性のない出力を許容することで取り繕わないでください。

エフェクトを使用する場合は、次の条件をすべて満たしてください。

• 状態に関連し、アニメーションの説明に役立つこと。
• ペットのシルエットに物理的に付着する、触れる、または重なること。近くに浮かべないでください。
• ペットと同じフレーム枠内に収まり、独立したスプライト要素を作らないこと。
• 不透明で、きれいに切り出せる程度に輪郭がはっきりしており、クロマキー色を使わないこと。
• ごちゃつかず、192x208 でも読み取れる大きさであること。

透明背景のクリーンアップや要素の切り出しを妨げることが多いため、原則として次のものは避けてください。

• 波線、動きを示す弧、スピード線、アクションの軌跡、残像、ぼかし、にじみ
• 離れた星、散らばったきらめき、浮かぶ句読点、浮かぶアイコン、落ちる涙、離れた煙の雲、散らばったほこり
• キャストシャドウ、接地影、ドロップシャドウ、楕円形の床の影、床のパッチ、着地マーク、衝撃の破裂、光彩、ハロー、オーラ、または半透明のエフェクト
• テキスト、ラベル、フレーム番号、表示されるグリッド、ガイドマーク、吹き出し、思考吹き出し、UI パネル、コードスニペット、透明を示す市松模様、白背景、黒背景、風景
• ペット、小道具、エフェクト、ハイライト、影に使われる、クロマキー色に近い色
• 孤立したピクセル、つながっていない輪郭の断片、斑点やノイズ、切れた体の一部、重なり合うポーズ、または隣のフレーム枠にはみ出すポーズ

状態ごとのガイダンス：

• idle：落ち着いていて、気が散らない状態にします。控えめな呼吸、小さなまばたき、頭や体のわずかな上下、素材のごく小さな揺れなど、ペットらしさを保つ静かな動きだけを使用してください。ループには、目に見える微細な変化を含めてください。実質的に同じ画像を6枚並べたものは認められません。手を振る、歩く、走る、跳ぶ、話す、作業する、確認する、感情を表す、大きく身振りをする、アイテムに触れる、新しい小物を加えるといった表現はしないでください。
• waving：前足、手、翼、または四肢のポーズだけで手を振る様子を表現してください。ジェスチャーの周囲に、波線、動きの弧、線、きらめき、記号、浮遊するエフェクトを描かないでください。
• jumping：体の位置だけで垂直方向の動きを表現してください。影、ほこり、着地跡、衝撃の閃光、バウンスパッド、床を示す手がかりは描かないでください。
• failed：許可されているエフェクトのルールに従う場合、涙、体に付いた煙、体に付いた星は使用できます。赤いバツ印、浮遊する記号、体から離れた煙や星、独立した涙のしずくは使用しないでください。
• waiting：期待して尋ねるポーズで、Codex が承認、支援、またはユーザーの入力を必要としていることを示してください。通常の idle や review とは明確に区別してください。
• running：タスクに取り組む、処理する、考える、スキャンする、入力する、集中して作業するといった様子を示してください。文字どおりに足を動かして走る、ジョギングする、全力で走る、トレッドミル上で動く、膝を高く上げる、大股で歩く、腕を振る、特定の方向へ移動する、スピード線、砂ぼこり、床の影、動きの軌跡、体から離れた動きのエフェクトは表現しないでください。
• review：前傾、まばたき、目線、頭の傾き、前足や手の位置で集中を表現してください。拡大鏡、紙、コード、UI、句読点、記号、その他の新しい小物は、ベースとなるペットのアイデンティティにすでに含まれていない限り、追加しないでください。
• running-right と running-left：体、四肢、小物の動きだけで、方向を伴う移動を表現してください。running-right は右を向き、右へ移動する必要があります。running-left は左を向き、左へ移動する必要があります。ループ全体で動きのリズムが目に見えて交互に変化するようにし、ほとんど静止した歩幅を繰り返さないでください。スピード線、砂ぼこり、床の影、動きの軌跡、体から離れた動きのエフェクトは描かないでください。

進捗計画の表示

ペットの作成を実行するたびに、作業の進捗がユーザーにわかるよう、チェックリストを表示してください。作業を始める前にチェックリストを作成し、一度にアクティブにするステップは1つだけにして、各ステップが完了するたびに更新してください。

通常のペット作成では、以下のチェックリストを使用し、<Pet> をペットの名前または your pet に置き換えてください。

1. <Pet> を準備する。
2. <Pet> の主な見た目を考える。
3. <Pet> のポーズをイメージする。
4. <Pet> を誕生させる。

各ステップの内容：

• Getting <Pet> ready. ペットの名前、説明、ソース画像、スタイルプリセット、スタイルに関するメモ、作業フォルダーを選択または確認します。ブランド、製品、企業のみの依頼の場合は、まずブランド探索ワーカーを実行し、簡潔なブランド概要、ソースURL、アバターのシードをまとめます。
• Imagining <Pet>'s main look. ペットのメイン参照画像を生成します。これを視覚的な情報源として使用します。
• Picturing <Pet>'s poses. 軽量ワーカーを使ってポーズ行を生成します。まず idle と running-right を作成し、アイデンティティと歩き方を確認します。running-right が反転しても明確に機能する場合に限り、running-left を反転して作成します。
• Hatching <Pet>. 承認されたポーズを最終的なペットファイルにします。コンタクトシート、プレビュー、検証結果を確認し、問題があれば修正してから、pet.json と spritesheet.webp を保存し、出力パスを報告します。

実際のファイル、画像、または決定が存在する場合にのみ、ステップを完了としてマークしてください。修復作業の場合は、チェックリスト全体をやり直すのではなく、最初に該当するステップから開始してください。

既定のワークフロー

1. ペット作成用の作業フォルダーと画像生成ジョブのマニフェストを準備します。

SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/hatch-pet"
python "$SKILL_DIR/scripts/prepare_pet_run.py" \
  --pet-name "<Name>" \
  --description "<one sentence>" \
  --reference /absolute/path/to/reference.png \
  --output-dir /absolute/path/to/run \
  --pet-notes "<stable pet description>" \
  --brand-discovery-file /absolute/path/to/brand-discovery.md \
  --brand-name "<optional researched brand name>" \
  --brand-brief "<optional compact researched brand cue sentence>" \
  --brand-source "https://example.com/source" \
  --style-preset auto \
  --style-notes "<optional freeform style notes>" \
  --force

上記のすべての引数は、ユーザーの制約を表すために必要なフラグを除き、省略可能です。テキストのみのリクエストでは、コンセプトを --pet-notes に渡し、--reference は省略します。必要に応じて、prepare_pet_run.py が名前、説明、クロマキー、出力ディレクトリを推測します。 ブランドのみのリクエストでは、最初にディスカバリーワーカーを実行し、Markdown のブリーフを保存します。次に、ブリーフのパスを --brand-discovery-file に、avatar_seed を --pet-notes に、brand_name を --brand-name に、brand_brief を --brand-brief に渡し、各ソース URL を繰り返し指定する --brand-source に渡します。

2. imagegen-jobs.json を調べて、次に実行可能な $imagegen ジョブを確認します。status が complete ではなく、かつ depends_on 内のすべての ID が完了済みであれば、ジョブは実行可能です。ステータス表示用のヘルパースクリプトを追加するよりも、jq またはエディターでマニフェストを直接読むことを優先してください。

jq '.jobs[] | {id, kind, status, depends_on, prompt_file, retry_prompt_file, input_images, output_path, derivation_policy}' /absolute/path/to/run/imagegen-jobs.json

3. デフォルトでは、軽量ワーカーを使ってビジュアルジョブを生成します。

• 軽量のベースワーカーを使い、最初に base を生成してコピーします。
• 次に、アイデンティティと歩容を確認するため、各行に軽量ワーカーを1つ使って idle と running-right を生成してコピーします。
• running-right を確認します。ビジュアル上のアイデンティティ、プロップの配置、模様、ライティング、方向の意味が正しく保たれる場合に限り、running-left を反転して作成します。
• 反転によって意味やアイデンティティが変わる場合は、軽量ワーカーを使って通常の手順で running-left を生成します。
• 軽量ワーカーを使い、各ジョブに記載されたすべての入力画像を使用して、残りの行を生成します。

実行可能な各ビジュアルジョブでは、imagegen-jobs.json に記載されたプロンプトファイル、役割ラベル付きのリスト内のすべての入力画像、そして $imagegen 自体が別の経路を選択しない限り、デフォルトの組み込み image_gen 経路を使って $imagegen を呼び出します。親エージェント自身の画像処理は最小限に抑えます。親のロールアウト内で、生成されたすべてのベースや行を開かないでください。ワーカーは、選択したソースパスと1文の QA メモのみを返します。親エージェントは、選択したソースパスをマニフェストに記録します。

prepare_pet_run.py は、アニメーション状態ごとに1つ、references/layout-guides/ の下に9つの行固有のレイアウトガイド画像を作成します。行ジョブは、一致するガイドをレイアウト専用の入力として添付し、モデルが正しいフレーム数、間隔、中央揃え、安全な余白に従えるようにします。これらのガイドは、見えない構成用の参照として扱います。生成された行ストリップに、ボックス、枠線、中央マーク、ラベル、ガイドの色、ガイドの背景が見えてはいけません。

行ストリップを生成する際は、行プロンプト内のアイデンティティロックを最優先します。正規ベースと同じスタイル、顔、模様、配色、素材、プロップのデザイン、体の比率、シルエットを維持します。行ジョブには、デフォルトでレイアウトガイドと正規ベースが添付されます。デコード済みのベースは、決定論的な処理に使うため実行フォルダーに保持し、冗長な生成入力としては送信しません。

$imagegen が行に対してトランスポートレベルの Bad Request を返した場合は、生成された retry_prompt_file を使って同じ行を1回再試行します。再試行プロンプトでは、行 ID、フレーム数、クロマキー、正規ベースのアイデンティティ、状態アクションを維持します。正規ベースは添付したままにします。再試行も失敗した場合は、他の生成経路には切り替えず、失敗した行とプロンプトのパスを報告して停止します。

4. ジョブの生成出力を選択したら、それをデコード済み出力パスにコピーし、ジョブを完了としてマークします。base については、正規アイデンティティ参照も作成します。

RUN_DIR=/absolute/path/to/run
JOB_ID=<job-id>
SOURCE=/absolute/path/to/generated-output.png
OUTPUT_REL=$(jq -r --arg id "$JOB_ID" '.jobs[] | select(.id == $id) | .output_path' "$RUN_DIR/imagegen-jobs.json")
mkdir -p "$(dirname "$RUN_DIR/$OUTPUT_REL")"
cp "$SOURCE" "$RUN_DIR/$OUTPUT_REL"

if [ "$JOB_ID" = "base" ]; then mkdir -p "$RUN_DIR/references"; cp "$RUN_DIR/$OUTPUT_REL" "$RUN_DIR/references/canonical-base.png"; fi

UPDATED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
TMP_MANIFEST=$(mktemp)
jq --arg id "$JOB_ID" --arg source "$SOURCE" --arg at "$UPDATED_AT" '(.jobs[] | select(.id == $id)) += {status: "complete", source_path: $source, completed_at: $at}' "$RUN_DIR/imagegen-jobs.json" > "$TMP_MANIFEST"
mv "$TMP_MANIFEST" "$RUN_DIR/imagegen-jobs.json"

コピー元が ${CODEX_HOME:-$HOME/.codex}/generated_images の下にある場合は、デコード済みのコピーが作成された後に、元の生成ファイルを削除します。

GENERATED_ROOT="${CODEX_HOME:-$HOME/.codex}/generated_images"
case "$SOURCE" in
  "$GENERATED_ROOT"/*)
    rm -f "$SOURCE"
    rmdir "$(dirname "$SOURCE")" 2>/dev/null || true
    ;;
esac

5. 視覚的に安全な場合に限り、running-left を派生させます。

python "$SKILL_DIR/scripts/derive_running_left_from_running_right.py" \
  --run-dir /absolute/path/to/run \
  --confirm-appropriate-mirror \
  --decision-note "<why mirroring preserves this pet's identity>"

このスクリプトは、各生成フレームスロットをその場で反転させるため、左向きの行でも右向きの行と同じ時間順序が保たれます。アニメーションのタイミングが逆転する、ストリップ全体の反転に置き換えないでください。

6. すべてのジョブが完了したら、画像処理スクリプトを直接実行します。

RUN_DIR=/absolute/path/to/run
mkdir -p "$RUN_DIR/final" "$RUN_DIR/qa"

python "$SKILL_DIR/scripts/extract_strip_frames.py" \
  --decoded-dir "$RUN_DIR/decoded" \
  --output-dir "$RUN_DIR/frames" \
  --states all \
  --method auto

python "$SKILL_DIR/scripts/inspect_frames.py" \
  --frames-root "$RUN_DIR/frames" \
  --json-out "$RUN_DIR/qa/review.json" \
  --require-components

python "$SKILL_DIR/scripts/compose_atlas.py" \
  --frames-root "$RUN_DIR/frames" \
  --output "$RUN_DIR/final/spritesheet.png" \
  --webp-output "$RUN_DIR/final/spritesheet.webp"

python "$SKILL_DIR/scripts/validate_atlas.py" \
  "$RUN_DIR/final/spritesheet.webp" \
  --json-out "$RUN_DIR/final/validation.json"

python "$SKILL_DIR/scripts/make_contact_sheet.py" \
  "$RUN_DIR/final/spritesheet.webp" \
  --output "$RUN_DIR/qa/contact-sheet.png"

python "$SKILL_DIR/scripts/render_animation_previews.py" \
  --frames-root "$RUN_DIR/frames" \
  --output-dir "$RUN_DIR/qa/previews"

プレビュー GIF で、フレームごとのセルへのフィットによる抽出が原因のサイズの跳ねやベースラインのずれが見られ、元の行ストリップ自体はスケールと配置が安定していた場合は、明示的な行安定化モードでフレームを再抽出し、その後、検査、アトラスの合成、検証、コンタクトシートの生成、プレビューの作成を再実行します。

python "$SKILL_DIR/scripts/extract_strip_frames.py" \
  --decoded-dir "$RUN_DIR/decoded" \
  --output-dir "$RUN_DIR/frames" \
  --states all \
  --method stable-slots

python "$SKILL_DIR/scripts/inspect_frames.py" \
  --frames-root "$RUN_DIR/frames" \
  --json-out "$RUN_DIR/qa/review.json" \
  --require-components \
  --allow-stable-slots

stable-slots は、QA に基づく意図的な修正として使用し、デフォルトにはしないでください。抽出による動きの跳ねを抑えつつ、幅広のポーズの切れや、問題のある元ストリップを見逃さないようにします。

クリーンアップ前の想定出力：

run/
  pet_request.json
  imagegen-jobs.json
  prompts/
  decoded/
  frames/frames-manifest.json
  final/spritesheet.webp
  final/validation.json
  qa/contact-sheet.png
  qa/previews/*.gif
  qa/review.json
  qa/run-summary.json

パッケージ出力は、デフォルトでは実行ディレクトリの外に書き込まれます。CODEX_HOME が設定されている場合はそれを使用し、設定されていない場合は $HOME/.codex を使用します。

${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
  pet.json
  spritesheet.webp

シェルと jq でパッケージ化します：

RUN_DIR=/absolute/path/to/run
PET_ID=$(jq -r '.pet_id' "$RUN_DIR/pet_request.json")
DISPLAY_NAME=$(jq -r '.display_name' "$RUN_DIR/pet_request.json")
DESCRIPTION=$(jq -r '.description' "$RUN_DIR/pet_request.json")
PET_DIR="${CODEX_HOME:-$HOME/.codex}/pets/$PET_ID"
mkdir -p "$PET_DIR"
cp "$RUN_DIR/final/spritesheet.webp" "$PET_DIR/spritesheet.webp"
jq -n --arg id "$PET_ID" --arg displayName "$DISPLAY_NAME" --arg description "$DESCRIPTION" '{id: $id, displayName: $displayName, description: $description, spritesheetPath: "spritesheet.webp"}' > "$PET_DIR/pet.json"

パッケージ化後に qa/run-summary.json を書き込みます：

jq -n --arg run_dir "$RUN_DIR" --arg spritesheet "$RUN_DIR/final/spritesheet.webp" --arg validation "$RUN_DIR/final/validation.json" --arg contact_sheet "$RUN_DIR/qa/contact-sheet.png" --arg review "$RUN_DIR/qa/review.json" --arg package "$PET_DIR" '{ok: true, run_dir: $run_dir, spritesheet: $spritesheet, validation: $validation, contact_sheet: $contact_sheet, review: $review, package: $package}' > "$RUN_DIR/qa/run-summary.json"

決定論的な画像処理の後、ペットを受け入れる前に、軽量なビジュアル QA ワーカーで qa/contact-sheet.png と qa/previews/*.gif を確認します。決定論的な検証は必要ですが、それだけでは不十分です。いずれかの行で、種類や体型、顔、模様、パレット、素材、小道具のデザイン、スタイル、小道具の側が予期せず変わっている場合、または全体のシルエットが変わっている場合は、受け入れを見送ります。モーションプレビューでは、意図しないサイズの跳ね、方向のリズムの逆転や停滞、向きの間違い、技術的には異なっていても視覚的には変化のないアイドルループも却下します。

モデルによるビジュアル QA でコンタクトシートが承認されたら、中間の実行アーティファクトを削除します：

pet_request.json、final/spritesheet.webp、final/validation.json、qa/contact-sheet.png、qa/previews/、qa/review.json、qa/run-summary.json は保持します。生成されたプロンプトファイル、レイアウトガイド、デコード済みの行ストリップ、抽出済みフレーム、final/spritesheet.png、画像生成ジョブのマニフェストは削除します。ユーザーがデバッグ用アーティファクトを必要としている場合や、実行の修正がまだ必要な場合は、クリーンアップをスキップします。

軽量ビジュアルワーカー

画像を多用する作業では、デフォルトで軽量なサブエージェントを使用します。これにより、各 $imagegen の実行で選択される画像を 1 枚に限定し、コンタクトシートの画像認識ペイロードが親スレッドに含まれないようにして、9 状態のアプリ契約全体を維持しながらコストを削減できます。

サブエージェントへの委任

ユーザーが明示的に禁止していない限り、この実行ではサブエージェントを使用してください。ユーザーがサブエージェントの使用を許可していない場合、またはサブエージェントの使用意図が曖昧な場合は、作業を並行して進めるためにサブエージェントを起動してよいか、ユーザーに確認してください。

親エージェントの責任：

• ユーザーがブランド／製品／会社／見込み客の名前だけを提示した場合は、準備の前にブランド調査ワーカーを実行する
• 実行の準備をし、imagegen-jobs.json を確認する
• ベースジョブ、行ジョブ、最終コンタクトシートの QA を軽量ワーカーに割り当てる
• 選択されたワーカーの出力をデコード後のパスにコピーし、imagegen-jobs.json でジョブを完了としてマークする
• 選択されたベース出力から references/canonical-base.png を作成する
• 適切な場合は、承認済みの running-left ミラー派生処理を実行する
• 決定論的な画像処理、パッケージ化、修復の再生成、クリーンアップを実行する

ベースワーカーの責任：

• base ジョブのみを担当する
• prompts/base-pet.md を読み、記載されている参照画像を使用する
• $imagegen のみを使用する
• プロンプト内の簡潔なブランドの着想に関する記述を、幅広いビジュアル／パーソナリティの指針として尊重し、ロゴ、判読可能なマーク、UI スクリーンショット、スローガン、テキストをコピーしない
• selected_source=/absolute/path/to/selected-output.png と qa_note=<one sentence> のみを返す

行ワーカーの責任：

• 行ジョブを正確に 1 つ担当する
• 行のプロンプトを読み、記載されているすべての入力画像を使用する
• $imagegen のみを使用する。ローカルでスプライトを描画、編集、タイル化、合成しない
• フレーム数、同一性、クロマキー背景、間隔、クリッピング、分離したエフェクトについて、簡易的な目視確認を行う
• 行のプロンプトにある透明度とエフェクトのルールを遵守する。分離したエフェクト、waving の波線、方向性のある走行行のスピード線や砂ぼこり、方向性のない running 行での文字どおりの足の走行表現は禁止し、状態プロンプトで許可されている場合に限り、スプライトに付随する不透明な涙／煙／星のみを使用する
• selected_source=/absolute/path/to/selected-output.png と qa_note=<one sentence> のみを返す

最終ビジュアル QA ワーカーの責任：

• qa/contact-sheet.png と qa/previews/ 内の行 GIF を確認し、必要に応じて qa/review.json と final/validation.json をテキストの参考情報として参照する
• 9 行すべてが Codex アプリの状態契約と同一のペットの同一性に一致することを確認する
• 簡潔な結果として visual_qa=pass または visual_qa=fail を返し、不合格の場合は行ごとの修復メモも返す
• ファイルの編集、修復のキュー登録、パッケージ化、クリーンアップは行わない

ワーカーに使用するモデル：

• ブランド調査では、オーケストレーションではなく簡潔な調査概要を作成するため、より小型で能力のあるモデルを優先する
• ビジュアルワーカーでは、モデルの上書きが可能な場合、medium reasoning の gpt-5.4-mini など、より小型のモデルを優先する
• オーケストレーションの場合、または小型のワーカーモデルが利用できない場合に限り、親／デフォルトのモデルを使用する
• ユーザーがより高い並列度を明示的に求めていない限り、生成ワーカーは同時に最大 2 つまでとする。決定論的な画像処理の後、最終ビジュアル QA は単一のワーカーとして実行する。結果を使用したらワーカーを終了する

次のベースワーカープロンプトを使用してください：

Generate the hatch-pet base image.

Run dir: <absolute run dir>
Job id: base
Prompt file: <absolute base prompt file>
Input images:
- <absolute path> — <role>

Use $imagegen only. Read the base prompt and attach every listed input image. If the prompt contains brand inspiration, use it only as broad mascot-safe guidance; do not copy logos, readable marks, UI screenshots, slogans, or text. Before returning, visually check that the result is one centered full-body pet on a flat chroma background, with no text, scenery, shadows, or detached effects.

Do not edit manifests, copy into decoded, mark jobs complete, generate rows, run image-processing scripts, repair, package, or open unrelated files.
Do not include Markdown image previews, base64, or extra attachments in the final response.

Return exactly:
selected_source=/absolute/path/to/selected-output.png
qa_note=<one sentence>

次の行ワーカープロンプトを使用してください：

Generate one hatch-pet row.

Run dir: <absolute run dir>
Row id: <row-id>
Prompt file: <absolute prompt file>
Retry prompt file: <absolute retry prompt file>
Input images:
- <absolute path> — <role>
- <absolute path> — <role>

Use $imagegen only. Read the row prompt and attach every listed input image. If imagegen returns Bad Request, retry once with the retry prompt and the same input images.

Before returning, visually check: exact frame count, same pet identity as canonical base, flat chroma background, complete separated unclipped poses, and no detached effects or guide marks. The prompt's transparency and effects rules are mandatory: no detached effects, no wave marks for `waving`, no speed lines or dust for directional running rows, no literal foot-running for the non-directional `running` row, and only attached opaque sprite-like tears/smoke/stars when allowed by the state prompt.

Do not edit manifests, copy into decoded, mark jobs complete, mirror rows, run image-processing scripts, repair, package, or open unrelated files.
Do not include Markdown image previews, base64, or extra attachments in the final response.

Return exactly:
selected_source=/absolute/path/to/selected-output.png
qa_note=<one sentence>

次の最終ビジュアル QA ワーカープロンプトを使用してください：

Visually QA one finalized hatch-pet contact sheet.

Run dir: <absolute run dir>
Contact sheet: <absolute run dir>/qa/contact-sheet.png
Preview dir: <absolute run dir>/qa/previews
Review JSON: <absolute run dir>/qa/review.json
Validation JSON: <absolute run dir>/final/validation.json

Inspect the contact sheet and the preview GIFs visually. Confirm the same pet identity, style, palette, silhouette, face, proportions, and props across all rows:
0 idle, 1 running-right, 2 running-left, 3 waving, 4 jumping, 5 failed, 6 waiting, 7 running, 8 review.

Fail rows with identity drift, missing/blank frames, copied guide marks, white/nontransparent backgrounds, cropped bodies, slot overlap, detached effects, shadows/glows/smears/dust, chroma-key artifacts, motion that does not match the row state, unintended size popping, wrong facing direction, reversed or non-alternating gait, or idle loops that are effectively static.

Do not edit files, queue repairs, package, clean up, or inspect unrelated files.

Return exactly:
visual_qa=pass|fail
qa_note=<one sentence summary>
repair_rows=<comma-separated row ids, or none>
repair_notes=<short row-specific notes, or none>

修復ワークフロー

フレーム検査または最終ビジュアル QA に失敗した場合は、qa/review.json を読み込み、失敗した最小範囲を再生成して、差し替えた行を同じデコード済み出力パスにコピーし、新しい source_path と completed_at を設定してそのジョブを完了状態のままにします。シート全体ではなく、失敗した行を修復してください。

アイデンティティを修復する場合は、正規のベース画像、元の参照画像、コンタクトシート、および行ごとの正確な失敗メモを根拠として使用してください。行ワーカーには既存の行プロンプトと qa/review.json の簡潔な修復メモを渡し、正規のペットのアイデンティティと選択したスタイルを維持してください。

抽出によって動きにポッピングが発生した場合は、まず画像を再生成しないでください。ソースストリップがすでに行単位のスケールとベースラインを維持している場合は、--method stable-slots を指定して決定論的なパイプラインを再実行し、--allow-stable-slots を指定して検査した後、プレビュー GIF を再確認してください。元のストリップ自体が切り取られている、不安定である、または意味的に誤っている場合に限り、行を再生成してください。

ルール

• 主要な生成レイヤーとして $imagegen を維持してください。
• 具体的なアバターの説明または参照画像がないブランド／製品／企業／見込み客のリクエストでは、ベースを生成する前にブランドの調査を行い、簡潔なブリーフのみを実行に渡してください。
• 唯一のビジュアル生成レイヤーとして $imagegen を使用してください。このスキルから画像 API、画像 CLI、ローカルのラスター生成ツール、または単発の生成スクリプトを呼び出さないでください。
• 選択した方法で参照画像を利用できる場合は、$imagegen に参照画像を添付し、表示された状態にしてください。
• 各行ストリップのジョブに、その行の references/layout-guides/<state>.png 画像をレイアウト専用ガイドとして添付し、ガイドのピクセルをコピーした出力は受け入れないでください。
• デフォルトでは、ベース生成、行ストリップのビジュアル生成、最終コンタクトシートの QA に軽量なビジュアルワーカーを使用してください。親プロセスがマニフェストの更新、決定論的な画像スクリプト、パッケージング、クリーンアップを担当します。
• running-left のミラー派生として明示的に承認されたものを除き、すべての通常のビジュアルジョブ（ベースとすべての行ストリップ）を $imagegen で生成してください。
• プロンプトのみで生成できるのはベースジョブだけです。すべての行ジョブには、指定された根拠画像を添付してください。
• running-left をミラーできるかどうか判断する前に、running-right を生成してください。
• running-left をミラーする場合は、フレーム順序とタイミングの意味を維持し、ストリップ全体をそのままミラーするのではなく、決定論的なスクリプトで派生させてください。
• waiting、running、failed、review、jumping、waving を別の状態から派生または再利用しないでください。それぞれアプリ内での意味が異なるため、各状態を独立した行として生成する必要があります。
• 不足している $imagegen の出力を、ローカルで描画、タイル化、変換、またはコード生成した行ストリップで代用しないでください。
• 選択した出力がデコード済み出力パスにコピーされた後に限り、ビジュアルジョブを完了としてマークしてください。
• 正確なアトラスのジオメトリには生成画像を使用せず、このスキルの決定論的な画像スクリプトを使用してください。
• pet_request.json に記録されたクロマキーを使用してください。固定のグリーンスクリーンを強制しないでください。
• すべての行で、ペットのシルエット、顔、素材、配色、スタイル、持ち物に一貫性を保ってください。
• qa/review.json と final/validation.json にエラーがなくても、ビジュアル上のアイデンティティまたはスタイルの不一致はブロッカーとして扱ってください。
• 参照画像が切り取られている、タイルが繰り返されている、セルの背景が白い、またはスプライトではない断片が表示されているコンタクトシートは失敗として扱ってください。
• 抽出によるサイズのポッピング、方向のタイミングの逆転、誤った向き、または動きのないアイドルループが表示されるプレビュー GIF は失敗として扱ってください。
• 分離された禁止エフェクト、クロマキーに隣接するアーティファクト、影、光彩、かすれ、ほこり、着地跡、手を振った跡、スピード線、または残像は、失敗した行として扱ってください。
• qa/review.json のエラーはブロッカーとして扱ってください。警告には目視での確認が必要です。

受け入れ基準

• 最終的なアトラスは PNG または WebP 形式で、サイズは 1536x1872、透明度に対応し、192x208 のセルを基準にしていること。
• 使用するセルは空ではなく、使用しないセルは完全に透明であること。
• アトラスが references/animation-rows.md に記載された行数とフレーム数に従っていること。
• コンタクトシートと行ごとのモーションプレビューが作成され、軽量なビジュアル QA ワーカーによって確認されていること。
• qa/review.json にエラーがないこと。
• 行ごとのレビューにより、アニメーションのサイクルが Codex アプリで使うのに十分な状態まで完成していることを確認すること。
• モーションプレビューに、意図しないサイズの変化、方向のリズムの逆転、または行の意味の誤りがないこと。
• ピクセルアート以外のスタイルも、ペットの表示サイズで見やすく、各行で一貫していれば許容されます。
• カスタムペットでは、${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/pet.json と ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/spritesheet.webp をセットで配置すること。