技能概述
Hatch Pet 係一個完整嘅 Codex 數字寵物孵化技能，可以從概念描述、參考圖片或兩者同時創建一個 Codex 兼容嘅動畫精靈圖寵物。輸出係一個 1536×1872（192×208 × 8列×9行）嘅 atlas spritesheet，包含 9 種動畫狀態（idle、running-right、running-left、waving、jumping、failed、review 等），附 QA 聯絡表、預覽視頻同 pet.json 配置。
默認風格匹配 Codex 內置寵物：小型 pixel-art-adjacent mascot，chibi 比例，粗 1-2px 深色輪廓，有限色板，flat cel shading，簡單表情同細小手腳。
觸發關鍵字
- hatch a pet、hatch pet、codex pet
- spritesheet pet、animated pet
- 孵化寵物、電子寵物
什麼時候用
- 想創建一個自定義動畫寵物作為 Codex companion
- 需要從角色設計稿生成對應嘅動畫精靈圖
- 想要修復已有寵物嘅動畫行（repair workflow）
- 需要打包
pet.json+spritesheet.webp供 Codex 導入
使用方法
可見進度計劃
整個孵化過程用 4 步進度清單追蹤：
- Getting
<Pet>ready — 確認寵物名稱、描述、參考圖、工作目錄 - Imagining
<Pet>'s main look — 生成主參考圖（新寵物必需，即使用戶冇提供圖） - Picturing
<Pet>'s poses — 創建 pose rows，先生成 idle 同 running-right 確認一致性 - Hatching
<Pet>— 將批准嘅 poses 轉為最終文件，審查聯絡表、預覽、驗證結果
標準工作流程
- 準備 run 目錄同 manifest — 用
prepare_pet_run.py創建工作目錄、生成 9 個 row 嘅 prompt 文件同 layout guides - 檢查 ready jobs — 用
pet_job_status.py查看下一個可用嘅$imagegen任務 - 生成基礎寵物 — 用
$imagegen生成 base job，記錄結果後寫入decoded/base.png同references/canonical-base.png - 逐行生成動畫 — 用 subagent 並行生成 9 個 animation row（除 running-left 可能由 running-right 鏡像派生）
- 記錄結果 — 用
record_imagegen_result.py將$imagegen輸出複製到正確解碼路徑 - Finalize — 跑
finalize_pet_run.py輸出完整結構：
run/
├── pet_request.json
├── imagegen-jobs.json
├── prompts/
├── decoded/
├── frames/frames-manifest.json
├── final/spritesheet.png + spritesheet.webp + validation.json
├── qa/contact-sheet.png + review.json + run-summary.json
└── qa/videos/*.mp4
- 打包 — 寫入
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/pet.json+spritesheet.webp
Subagent 並行生成
Parent 負責 manifest 同 package writes，row-strip 視覺生成用 subagent 並行執行：
- Parent 先 spawn idle 同 running-right 嘅 subagent（身份同步態檢查）
- 檢查 running-right 是否適合鏡像 → running-left（對稱、無手寫道具、無方向依賴）
- 其餘 row 各自 spawn subagent
- 每個 subagent 收到：row id、prompt file、所有 input image path
- Subagent 只返回選定嘅 source path + 一句 QA note
透明度同特效規則
所有效果必須同時滿足：
- 與寵物剪影相連/接觸/重疊（唔好飄浮）
- 同一 frame slot 內，唔會產生獨立 sprite component
- 不透明、硬邊、pixel-style
- 唔用 chroma-key 相近色
禁止效果： wave marks、speed lines、afterimages、detached stars、drop shadows、glow、halo、文字/標籤/格線/棋盤格、白色/黑色背景。
修復工作流程
如果 finalization 因為 row QA 失敗而停止：
python scripts/queue_pet_repairs.py --run-dir /path/to/run
只重新生成失敗嘅 row，唔係整張 atlas。
輸出
- Primary:
final/spritesheet.png（1536×1872） - Secondary:
final/spritesheet.webp、pet.json、qa/contact-sheet.png - 打包到：
~/.codex/pets/<pet-name>/
驗收標準
- 最終 atlas 係 PNG 或 WebP，1536×1872，支持透明
- 使用單元非空，未使用單元完全透明
qa/review.json無 errors- Contact sheet 同預覽視頻已生成
- 每行身份一致（物種/臉/標記/色板/道具/剪影不變）
硬規則
$imagegen係主要生成層，唔好用本地 Python/Pillow/SVG/canvas 代替- 每個 row job 必須 attach grounding images
- Running-right 先生成，running-left 只係喺鏡像安全時由 mirror 派生
- 唔手動修改
imagegen-jobs.json去聲稱 visual job 完成 - 視覺身份漂移係 blocker，即使
validation.json無 errors