# Hatch Pet > Create, repair, validate, visually QA, and package Codex-compatible v2 animated pets from character art, generated images, company or prospect brand cues, or visual references. Use for any new Codex pet, custom mascot, non-pixel pet style, brand-inspired pet, existing-pet repair, or 8x11 spritesheet workflow requiring all 9 standard animation rows, 16 look directions, deterministic assembly, QA artifacts, and spriteVersionNumber 2 packaging. - Skill: `brian861105/hatch-pet` (Agent Skill, multi-file: 34 files) - Install (CLI): `npx skillmds@latest add brian861105/hatch-pet` - Raw SKILL.md: https://api.skillmd.com/api/skills/brian861105/hatch-pet/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: brian861105 (https://skillmd.com/u/brian861105) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/brian861105/hatch-pet --- # Hatch Pet ## Overview Create a Codex-compatible v2 animated pet from a concept, brand cue, company/prospect name, one or more reference images, or any combination of those inputs. Every newly hatched pet is an 8x11 atlas with the 9 standard animation rows plus 16 clockwise look directions and is packaged with `spriteVersionNumber: 2`. The intermediate 8x9 atlas exists only to assemble and review rows 0-8; never package it as a new pet. User-facing inputs are optional. If the user omits a pet name, infer one from the concept, brand, company, or reference filenames; if that is not possible, choose a short friendly name. If the user omits a description, infer one from the concept or references. If the user omits reference images, generate the base pet from text first, then use that base as the canonical reference for every animation row. ## Existing Inputs And Upgrades Treat character art, generated images, standard or v2 atlases, contact sheets, and built-in pet art as first-class grounding inputs. - Preserve user-provided art as a generation reference; do not assume it already has final cell geometry. - For an existing valid 8x9 atlas, use it as the rows `0-8` intermediate after deterministic and visual validation, then generate rows `9-10` and package the result as v2. - For an existing 8x11 atlas, preserve approved standard rows. If a look cell fails, correct the complete containing 8-frame row before deterministic reassembly. Never package a newly generated one-off repair cell beside cells from another generation. - For a built-in pet, extract and use its atlas or neutral/idle cell as the canonical identity reference. - Include every image that defines head shape, face, palette, markings, material, flame/ears/hair, props, or look mechanics in look-direction generation. - When a renderer or source provides a dedicated neutral/front frame, pass it through `--neutral-cell`; otherwise use the approved idle/default frame. The 16 directional cells never treat `000` as neutral. ## Generation Delegation Use `$imagegen` for all normal visual generation. Before generating base art, row strips, or repair rows, load and follow the installed image generation skill: ```text ${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md ``` Do not call the Image API, image CLI, or any other image-generation path directly. Let `$imagegen` choose its own built-in-first path and fallback rules. If `$imagegen` says a fallback requires confirmation, ask the user before continuing. When invoking `$imagegen`, pass the generated pet prompt as the authoritative visual spec. Pet prompts should stay concise, state-specific, sprite-production oriented, and grounded in the listed input images. Keep longer policy and QA rules in this skill and the deterministic review scripts rather than expanding them into every image prompt. Do not wrap prompts in the generic `$imagegen` shared prompt schema. Use this skill's scripts for deterministic image work only: preparing layout guides and prompts, mirroring approved `running-left`, extracting frames, validating rows, composing the final atlas, and creating contact-sheet plus motion-preview QA media. Parent-owned shell/`jq` steps handle manifest updates, packaging, and cleanup. ## Runtime Dependencies Before running any bundled script, call `load_workspace_dependencies`. Set `PYTHON` to the exact Python executable path returned by that tool and use `"$PYTHON"` for every command below. The bundled runtime includes Pillow, which these scripts require. Do not use a bare system `python`; if workspace dependencies are unavailable, stop and report that the bundled runtime is required. ## Storage Controls The built-in `$imagegen` path stores generated PNG bytes in the rollout that invokes it, even when it also writes a file under `${CODEX_HOME:-$HOME/.codex}/generated_images`. Deleting files later reduces filesystem use, but it does not shrink an already-written rollout. Keep image generation isolated and bounded: - Use one lightweight generation worker per visual job. Do not batch multiple base/row jobs into the same worker. - Workers must return only `selected_source=...` and `qa_note=...`; they must not include Markdown image previews, base64, or extra visual attachments in their final response. - The parent must not open every generated PNG visually. Use worker QA for each job and inspect only the final contact sheet. - After copying the selected generated output into `decoded/`, remove the selected original from `${CODEX_HOME:-$HOME/.codex}/generated_images` when it lives there, then remove its now-empty generation directory if possible. - For storage-sensitive full runs, ask the user whether to use the `$imagegen` CLI fallback when available. That path requires local API credentials and explicit user confirmation, but it can avoid built-in image payloads being embedded in rollout events. ## Generation Contract ### Visual Job Graph Expect up to 13 visual jobs: 1 base pet, 9 standard row strips, 1 required four-cardinal anchor strip, and 2 required coherent look-direction row strips. The standard states are `idle`, `running-right`, `running-left`, `waving`, `jumping`, `failed`, `waiting`, `running`, and `review`. The only deterministic visual derivation is `running-left`, which may be produced by mirroring `running-right` only after `running-right` has been generated, visually inspected, and explicitly approved as safe to mirror. If mirroring is not appropriate, generate `running-left` as a normal grounded `$imagegen` row. ### Look Direction Sequence After validating rows 0–8, write qa/look-mechanics.md, then generate and approve one four-pose cardinal strip in this fixed order: 000 up, 090 screen-right, 180 down, and 270 screen-left. Generate row 9 as one coherent eight-pose family from those approved cardinal pose families, interpolating the intermediate directions as even 22.5-degree steps. Deterministically register its eight ordered pose groups, then run final-cell edge, semantic, and continuity QA immediately. Only after row 9 passes, generate row 10 as one coherent eight-pose family, using the approved cardinals for direction meaning and completed row 9 for identity, scale, registration, and boundary continuity. Run the same QA immediately after row 10. Row 9 contains 000, 022.5, 045, 067.5, 090, 112.5, 135, and 157.5; row 10 contains 180, 202.5, 225, 247.5, 270, 292.5, 315, and 337.5. 000 means up, not neutral/front. Never ask $imagegen to generate or repair a complete 8×11 atlas. ### Visual Provenance And Grounding After selecting a visual output, the parent agent copies that exact image into the job's `decoded/` path, runs its required incremental checks, and only then marks the job complete in `imagegen-jobs.json`. Do not write helper scripts that populate row outputs. The deterministic Python scripts may only process already-generated visual outputs. Only the base job may be prompt-only. Every row-strip job generated through `$imagegen` must use the input images listed in `imagegen-jobs.json`, including the canonical base reference created after the selected base output is copied. Treat any row generation without attached grounding images as invalid. ## Pet-Safe Styles Default style is `auto`: infer the pet's style from the user's prompt and references, then preserve that style across every row. If the user names a style, honor it. Supported style presets include `pixel`, `plush`, `clay`, `sticker`, `flat-vector`, `3d-toy`, `painterly`, `brand-inspired`, and `auto`. Any style is acceptable when it remains pet-safe: - compact whole-body silhouette readable inside a `192x208` cell - consistent face, proportions, material, palette, and props across all rows - clean removable chroma-key background - details large enough to read at pet size - no text, labels, UI, or readable logos unless the user explicitly provides approved reference art and asks for them Non-pixel styles are first-class. Plush, clay, sticker, vector, 3D toy, painterly mascot, ink, and brand-inspired looks should be accepted when they satisfy the atlas and readability constraints. ## Visible Progress Plan For every pet run, keep a visible checklist so the user can see where the work is up to. Create the checklist before starting, keep one step active at a time, and update it as each step finishes. Use this checklist for every v2 pet run, replacing `` with the pet's name or `your pet`: 1. Getting `` ready. 2. Imagining ``'s main look. 3. Picturing ``'s poses. 4. Hatching ``. What each step means: - `Getting ready.` Choose or confirm the pet name, description, source images, style preset, style notes, and working folder. For bare brand/product/company requests, first run the brand discovery worker and capture the compact brand brief, source URLs, and avatar seed. - `Imagining 's main look.` Generate the pet's main reference image. This becomes the visual source of truth. - `Picturing 's poses.` Generate and approve rows `0-8`, write the pet-specific look mechanics plan, then generate rows `9-10`. Only mirror `running-left` if `running-right` clearly works when flipped. - `Hatching .` Assemble the 8x11 atlas, review standard motion plus all 16 look directions, fix every failed cell or row, package `spriteVersionNumber: 2`, and report the output paths. Only mark a step complete when the real file, image, or decision exists. If this is a repair run, start from the first relevant step instead of restarting the whole checklist. ## Detailed References Load only the reference needed for the current stage: - Read [generation-policy.md](references/generation-policy.md) for brand-only discovery, visual effects policy, and retry/convergence decisions. - Read [look-directions-and-qa.md](references/look-directions-and-qa.md) after standard-row QA and before generating cardinal anchors or look rows. - Read [worker-delegation.md](references/worker-delegation.md) before assigning generation or visual-QA workers. - Read [acceptance-and-repair.md](references/acceptance-and-repair.md) before repairing failures or packaging the final pet. - Read [animation-rows.md](references/animation-rows.md), [codex-pet-contract.md](references/codex-pet-contract.md), and [qa-rubric.md](references/qa-rubric.md) when checking the atlas contract or final acceptance. ## Default Workflow 1. Prepare a pet run folder and imagegen job manifest: ```bash SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/hatch-pet" "$PYTHON" "$SKILL_DIR/scripts/prepare_pet_run.py" \ --pet-name "" \ --description "" \ --reference /absolute/path/to/reference.png \ --output-dir /absolute/path/to/run \ --pet-notes "" \ --brand-discovery-file /absolute/path/to/brand-discovery.md \ --brand-name "" \ --brand-brief "" \ --brand-source "https://example.com/source" \ --style-preset auto \ --style-notes "" \ --force ``` All arguments above are optional except any flags needed to express user constraints. For text-only requests, pass the concept through `--pet-notes` and omit `--reference`; `prepare_pet_run.py` will infer a name, description, chroma key, and output directory as needed. For brand-only requests, run the discovery worker first, save the markdown brief, then pass the brief path through `--brand-discovery-file`, `avatar_seed` through `--pet-notes`, `brand_name` through `--brand-name`, `brand_brief` through `--brand-brief`, and each source URL through repeated `--brand-source`. 2. Inspect `imagegen-jobs.json` for the next ready `$imagegen` jobs. A job is ready when its `status` is not `complete` and every id in `depends_on` is already complete. Prefer reading the manifest directly with `jq` or the editor instead of adding helper scripts for status display: ```bash 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. Generate visual jobs with lightweight workers by default: - Generate and copy `base` first, using a lightweight base worker. - Generate and copy `idle` and `running-right` next as the identity and gait check, using one lightweight worker per row. - Inspect `running-right`; mirror `running-left` only when visual identity, prop placement, markings, lighting, and direction semantics remain correct. - Generate `running-left` normally with a lightweight worker when mirroring would change meaning or identity. - Generate the remaining rows with lightweight workers, using every input image listed for each job. - After standard-row QA, generate `look-cardinals` as one four-pose strip, extract it into `decoded/look-anchors/000.png`, `090.png`, `180.png`, and `270.png`, and approve all four. The `090` and `270` anchors must be unmistakable in viewer/screen coordinates and visibly oppose each other. - Generate look row 9 as one coherent eight-pose synthesis from the approved cardinal strip, interpolating each intermediate direction as an even step between the adjacent cardinal pose families. Deterministically recover the eight ordered pose groups, crop them, normalize them with one shared scale and baseline, and then run final-cell edge diagnostics plus labeled per-direction QA immediately, before row 10 or final atlas assembly. - Only after row 9 passes, generate row 10 as one coherent synthesis using the approved cardinal strip and completed row 9. Keep up to three generation workers active whenever three independent jobs are ready and worker capacity permits. Backfill an available slot immediately instead of waiting for a fixed wave to finish. Use two or one worker when the dependency graph exposes fewer ready jobs. Do not exceed three generation workers without explicit user direction. For each ready visual job, invoke `$imagegen` with the prompt file listed in `imagegen-jobs.json`, every listed input image with its role label, and the default built-in `image_gen` path unless `$imagegen` itself routes otherwise. The parent agent must keep its own image handling minimal: do not open every generated base or row in the parent rollout. Workers return only the selected source path and a one-sentence QA note; the parent records the selected source path in the manifest. `prepare_pet_run.py` creates matching layout guides under `references/layout-guides/` for the nine standard rows, two look rows, and four-cardinal strip, and both look rows. Visual jobs attach the matching guide as a layout-only input so the model can follow the correct frame count, spacing, centering, and safe padding. Treat these guides as invisible construction references: generated strips must not include visible boxes, borders, center marks, labels, guide colors, or the guide background. When generating row strips, keep the identity lock in the row prompt authoritative. Preserve the same style, face, markings, palette, materials, prop design, body proportions, and silhouette from the canonical base. Row jobs attach the layout guide and canonical base by default; the decoded base is kept in the run folder for deterministic processing rather than sent as a redundant generation input. If `$imagegen` returns a transport-level `Bad Request` for a row, retry that same row once with its generated `retry_prompt_file`. The retry prompt preserves the row id, frame count, chroma key, canonical-base identity, and state action. Keep the canonical base attached. If the retry still fails, stop and report the failing row and prompt paths instead of switching to any other generation path. 4. After selecting a generated output for a job, copy it into the decoded output path. For `base`, also create the canonical identity reference: ```bash RUN_DIR=/absolute/path/to/run 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" ``` ```bash if [ "$JOB_ID" = "base" ]; then mkdir -p "$RUN_DIR/references"; cp "$RUN_DIR/$OUTPUT_REL" "$RUN_DIR/references/canonical-base.png"; fi ``` For every standard `row-strip` job, immediately extract and inspect only that row before marking the job complete. This overlaps deterministic QA and any repair with generation of other ready rows instead of waiting for all nine rows: ```bash ROW_QA_DIR="$RUN_DIR/qa/rows/$JOB_ID" "$PYTHON" "$SKILL_DIR/scripts/extract_strip_frames.py" \ --decoded-dir "$RUN_DIR/decoded" \ --output-dir "$ROW_QA_DIR/frames" \ --states "$JOB_ID" \ --method auto "$PYTHON" "$SKILL_DIR/scripts/inspect_frames.py" \ --frames-root "$ROW_QA_DIR/frames" \ --json-out "$ROW_QA_DIR/review.json" \ --states "$JOB_ID" \ --require-components ``` Treat errors as an immediate repair request. Inspect warnings before accepting the row; do not defer a known clipping, component, or extraction problem to final atlas QA. Chroma cleanup belongs to the deterministic post-assembly despill pass and must not trigger row regeneration. If the only failure is component extraction and the source strip itself has stable scale and placement, use the existing `stable-slots` correction with `--allow-stable-slots` instead of regenerating imagery. For `look-cardinals`, extract and validate all four anchors before marking the job complete: ```bash CHROMA_KEY=$(jq -r '.chroma_key.hex' "$RUN_DIR/pet_request.json") "$PYTHON" "$SKILL_DIR/scripts/extract_cardinal_anchors.py" \ --strip "$RUN_DIR/decoded/look-cardinals.png" \ --output-dir "$RUN_DIR/decoded/look-anchors" \ --chroma-key "$CHROMA_KEY" \ --json-out "$RUN_DIR/qa/cardinal-anchors.json" "$PYTHON" "$SKILL_DIR/scripts/compose_cardinal_anchor_strip.py" \ --anchors-dir "$RUN_DIR/decoded/look-anchors" \ --output "$RUN_DIR/decoded/look-anchors-approved.png" ``` Approve the four extracted anchors semantically at final pet size. If one cardinal fails, regenerate that individual anchor with `prompts/look-anchor-repairs/.md`, replace only its extracted file, and rerun `compose_cardinal_anchor_strip.py`. Both final look rows use the approved cardinal strip, and row 10 additionally uses completed row 9. Mark the job complete only after its required deterministic and visual checks pass: ```bash 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" ``` After `decoded/look-anchors-approved.png` exists and all four cardinals have passed semantic review, mark `look-cardinals` complete. Row 9 then becomes ready immediately. If the copied source is under `${CODEX_HOME:-$HOME/.codex}/generated_images`, delete the original generated file after the decoded copy exists: ```bash 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. Derive `running-left` only when it is visually safe: ```bash "$PYTHON" "$SKILL_DIR/scripts/derive_running_left_from_running_right.py" \ --run-dir /absolute/path/to/run \ --confirm-appropriate-mirror \ --decision-note "" ``` That script mirrors each generated frame slot in place so the leftward row preserves the rightward row's temporal order. Do not replace it with a whole-strip mirror that reverses animation timing. 6. When all nine incrementally validated standard row jobs are complete, build and review the intermediate rows `0-8`: ```bash RUN_DIR=/absolute/path/to/run mkdir -p "$RUN_DIR/final" "$RUN_DIR/qa" ``` ```bash "$PYTHON" "$SKILL_DIR/scripts/extract_strip_frames.py" \ --decoded-dir "$RUN_DIR/decoded" \ --output-dir "$RUN_DIR/frames" \ --states all \ --method auto ``` ```bash "$PYTHON" "$SKILL_DIR/scripts/inspect_frames.py" \ --frames-root "$RUN_DIR/frames" \ --json-out "$RUN_DIR/qa/review.json" \ --require-components ``` ```bash "$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" ``` ```bash "$PYTHON" "$SKILL_DIR/scripts/make_contact_sheet.py" \ "$RUN_DIR/final/spritesheet.webp" \ --output "$RUN_DIR/qa/contact-sheet.png" ``` ```bash "$PYTHON" "$SKILL_DIR/scripts/render_animation_previews.py" \ --frames-root "$RUN_DIR/frames" \ --output-dir "$RUN_DIR/qa/previews" ``` If the preview GIFs show size popping or baseline jumps caused by per-frame fit-to-cell extraction, and the original row strip itself had stable scale and placement, rerun frame extraction with the explicit row-stability mode and then re-run inspection, atlas composition, contact sheet generation, and previews: ```bash "$PYTHON" "$SKILL_DIR/scripts/extract_strip_frames.py" \ --decoded-dir "$RUN_DIR/decoded" \ --output-dir "$RUN_DIR/frames" \ --states all \ --method stable-slots ``` ```bash "$PYTHON" "$SKILL_DIR/scripts/inspect_frames.py" \ --frames-root "$RUN_DIR/frames" \ --json-out "$RUN_DIR/qa/review.json" \ --require-components \ --allow-stable-slots ``` Use `stable-slots` as a deliberate QA-driven correction, not the default. It should reduce extraction-induced motion pops without hiding clipped wide poses or bad source strips. Expected intermediate output before the required v2 look stage: ```text run/ pet_request.json imagegen-jobs.json prompts/ decoded/ frames/frames-manifest.json final/spritesheet.webp qa/contact-sheet.png qa/previews/*.gif qa/review.json ``` Inspect `qa/contact-sheet.png` and `qa/previews/*.gif` before generating look rows. `qa/review.json` plus visual motion review are the intermediate gates. The standard contact sheet intentionally predates chroma cleanup, so visible key-color fringe there is not a failure; judge chroma only on the cleaned final v2 atlas. Block progress if any standard row changes identity, style, prop handedness, or silhouette, or if playback pops, reverses cadence, faces the wrong direction, or is visually inert. Do not package or clean up yet. ## Required V2 Look-Direction Stage Before starting this stage, read and follow [look-directions-and-qa.md](references/look-directions-and-qa.md). It contains the cardinal-anchor workflow, coherent row generation, deterministic assembly, blind direction review, semantic QA, packaging, and cleanup requirements. ## Lightweight Visual Workers Before assigning any generation or visual-QA job, read and follow [worker-delegation.md](references/worker-delegation.md). Keep orchestration, manifest updates, deterministic processing, packaging, and cleanup with the parent agent. ## Repair And Acceptance Before repairing a failed row or packaging a completed pet, read and follow [acceptance-and-repair.md](references/acceptance-and-repair.md). Do not package until the deterministic validators and required visual QA pass.