hatch-pet-collection

name	hatch-pet-collection
description	Orchestrate multi-pet Codex custom pet collections with the installed hatch-pet skill. Use when a user wants to create a set of Codex pets one at a time, pilot the first pet, generate base art and animation rows, use subagents for row generation, run QA/contact sheets/videos, package to ~/.codex/pets, or continue a pet collection after a first successful pet.

Hatch Pet Collection

Overview

Use this skill to run a reliable one-pet-at-a-time collection workflow on top of $hatch-pet. It preserves a token-saving pilot pattern: create one pet, pass a two-row quality gate, finalize and QA it, then ask before starting the next pet.

Always load and follow ${CODEX_HOME:-$HOME/.codex}/skills/hatch-pet/SKILL.md before creating or repairing pets. If hatch-pet is missing, install it with $skill-installer hatch-pet, tell the user to restart or reload skills, and stop.

This skill shares process only. Do not include or redistribute third-party character artwork, generated spritesheets, or copyrighted reference images unless the user has rights to do so.

Collection Setup

When the user names a collection, define each pet with:

• display name
• pet id slug
• one-sentence description
• stable pet notes
• risk notes for parts that may not fit inside 192x208

For public or shared outputs, prefer original mascot designs over direct copies of existing characters. If the user provides references, use them only when they have appropriate rights or the work is local/private.

Good public-safe examples:

1. Wingbean / wingbean
   • Description: A compact orange-and-cream wing-eared digital pet.
   • Pet notes: compact chibi orange flying mammal mascot: round orange body, large wing-like ears, cream face and belly, bright blue eyes, tiny claws, small happy mouth, friendly brave expression; original mascot design simplified for Codex digital pet style.
   • Risk: wide ear-wings; enforce safe padding in every row.
2. Longhop / longhop
   • Description: A compact white-and-green long-eared digital pet.
   • Pet notes: compact chibi white rabbit-dog mascot: round white body, long floppy ears with purple tips, bright blue eyes, small forehead horn, oversized green mitten-like paws with dark claw tips, tiny feet, calm cute expression; original mascot design simplified for Codex digital pet style.
   • Risk: long ears and paw gloves; scale down and simplify claws.
3. Dinobit / dinobit
   • Description: A compact orange dinosaur digital pet.
   • Pet notes: compact chibi orange dinosaur mascot: small rounded orange reptile body, large expressive teal eyes, cream belly and lower jaw, short rounded snout, tiny arms, three white claws on hands and feet, small tail, confident brave expression; original mascot design simplified for Codex digital pet style.
   • Risk: claws, snout, and tail; keep the silhouette compact.
4. Cactubox / cactubox
   • Description: A compact green cactus boxer digital pet.
   • Pet notes: compact chibi green cactus boxer mascot: small round cactus body with vertical ribs, black oval eyes and mouth, tiny feet, attached red-orange boxing gloves, small orange flower tuft, cute tough expression; original mascot design simplified for Codex digital pet style.
   • Risk: needles, flower, and gloves; avoid tiny spikes and keep gloves attached to the body.

Workflow

Keep a visible checklist for each pet:

1. Getting <Pet> ready.
2. Imagining <Pet>'s main look.
3. Picturing <Pet>'s poses.
4. Hatching <Pet>.

Use a stable run directory:

RUN_DIR="${CODEX_HOME:-$HOME/.codex}/output/hatch-pet/<pet-id>-pilot"
SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/hatch-pet"

Prepare the run:

python "$SKILL_DIR/scripts/prepare_pet_run.py" \
  --pet-name "<Display Name>" \
  --pet-id "<pet-id>" \
  --display-name "<Display Name>" \
  --description "<one sentence>" \
  --pet-notes "<pet notes>" \
  --style-notes "Codex digital pet sprite style, low-detail readable mascot, thick dark pixel outline, flat cel shading, limited palette, no text, no scenery, no shadows, no detached effects, generous padding, flat #FF00FF chroma-key background for removal." \
  --chroma-key "#FF00FF" \
  --output-dir "$RUN_DIR" \
  --force

Generate the base job first using $imagegen through the built-in image generation path. Record only the original $CODEX_HOME/generated_images/.../ig_*.png source:

python "$SKILL_DIR/scripts/record_imagegen_result.py" \
  --run-dir "$RUN_DIR" \
  --job-id base \
  --source /absolute/path/to/generated_images/.../ig_*.png

Visually inspect decoded/base.png. Reject and regenerate if it has text, scenery, shadows, non-flat background, missing whole body, or a silhouette that will not fit in 192x208.

Row Generation Gate

Use subagents for row-strip generation only when the user has explicitly authorized subagents in the current session. If not authorized, ask once before row generation.

First delegate only:

• idle
• running-right

Each row subagent must:

• read the exact row prompt file from prompts/rows/<row>.md
• attach the row layout guide, references/canonical-base.png, and decoded/base.png
• use $imagegen only
• return only selected_source=/absolute/path/to/generated_images/.../ig_*.png and qa_note=...
• never edit manifests, copy decoded files, finalize, repair, mirror, or package

Record returned sources with record_imagegen_result.py, then visually inspect decoded/idle.png and decoded/running-right.png. The gate passes only when frame counts are correct, identity is consistent, the chroma key is usable, frames are separated, no parts are clipped, and there are no forbidden effects.

If the pet has no text, handed prop, asymmetric side marking, or side-specific accessory, derive running-left:

python "$SKILL_DIR/scripts/derive_running_left_from_running_right.py" \
  --run-dir "$RUN_DIR" \
  --confirm-appropriate-mirror \
  --decision-note "<why mirroring preserves identity and direction semantics>"

Otherwise delegate running-left as a normal grounded row job.

After the gate passes, delegate the remaining rows:

• waving
• jumping
• failed
• waiting
• running
• review

If a subagent times out for a single remaining row, it is acceptable for the parent to generate that row with the same prompt and grounding images, then record the original built-in imagegen output.

QA And Packaging

When all 10 jobs are complete, finalize:

python "$SKILL_DIR/scripts/finalize_pet_run.py" --run-dir "$RUN_DIR"

Acceptance checks:

• pet_job_status.py reports complete: 10, ready: 0, blocked: 0
• final/validation.json has no errors or warnings
• qa/review.json has no errors or warnings
• qa/contact-sheet.png shows the same pet identity in every row
• qa/videos/*.mp4 exists for all nine animation states
• ${CODEX_HOME:-$HOME/.codex}/pets/<pet-id>/pet.json and spritesheet.webp exist
• packaged spritesheet.webp is WebP, RGBA, 1536x1872

Report the package path, QA paths, which rows were delegated, which rows were mirrored, whether any row was generated by the parent, and whether repairs were needed. Tell the user to refresh Settings > Appearance > Pets, select the pet, and use /pet.

Only start the next pet after the user accepts the current pet or asks for a specific repair.