hatch-pet-v2

# Hatch Pet v2 ## 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. ## Brand Discovery If the user provides a brand, company, product, or prospect name rather than a concrete avatar description or reference image, run a lightweight discovery subagent before preparing the pet run. The discovery worker must use web search and prefer official sources such as the brand site, product pages, docs, about pages, press pages, or brand pages. Use reputable secondary sources only when official pages are too thin. Keep the search narrow: enough to extract visual and personality cues, not a market-research brief. Skip discovery when the user already provides a concrete mascot/avatar description or reference images, unless the user explicitly asks for brand research. Discovery worker responsibilities: - search the web for 2-4 relevant sources, preferring official pages - write an adaptive markdown brief rather than a rigid field dump - cover identity/category, audience/use context, visual system, personality/tone, product/domain motifs, mascot translation cues, avoidances, and evidence/confidence - mark mascot guidance that is inferred from sources as inference - avoid copying logos, readable marks, UI screenshots, slogans, or text - end with a compact `Generation handoff` section containing only `brand_name`, `brand_brief`, `avatar_seed`, `avoid`, and `brand_sources` - do not generate images, prepare run folders, or edit unrelated files Use this discovery worker prompt: ```text 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> ``` The parent should save the markdown brief before preparing the run, then pass it to `prepare_pet_run.py` as `--brand-discovery-file` together with `--brand-name`, `--brand-brief`, repeated `--brand-source`, and a concise `--pet-notes` value based on `avatar_seed` when the user did not provide a better avatar description. Keep the full brief for review; only the compact handoff fields should shape prompts. If web search is unavailable and the user gave only a bare brand name, ask for brand cues before generating. ## 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 - real transparent alpha background for every newly generated image - 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. ## Transparency And Effects Pet rows are processed into transparent `192x208` cells. For new v2 pets, require real RGBA transparency from `$imagegen` for the base, every standard row, the cardinal strip, and both look rows. The default `--background-mode transparent` rejects opaque outputs; never silently switch to green/magenta chroma or clean an opaque generation into compliance. Retry an opaque visual source with a stronger transparent-background prompt, then report a blocker if native alpha remains unavailable. Prefer pose, expression, and silhouette changes over decorative effects. For every new visual job, call the built-in `image_gen` tool with `transparent_background: true` and a prompt requiring real transparency. If an explicitly approved API/CLI path is used, set `background=transparent` and output PNG or WebP. In either path, verify the returned image's alpha before accepting it; the parameter is a request, not proof of a valid source. `--background-mode auto` (transparent preferred, chroma allowed) and `--background-mode chroma` exist only for an explicitly chosen legacy/source-compatibility run. The deterministic raster pipeline owns background detection and transparency invariants. In strict `transparent` mode it rejects any source without usable native alpha. In explicit legacy `auto` mode it preserves native alpha when present and runs color removal only for an opaque source. The detected mode is recorded per row and propagated into the final atlas manifest. Native-alpha cleanup clears hidden RGB under fully transparent pixels without changing any visible color. Legacy chroma cleanup retains the existing single edge-local spill-suppression pass. Never run chroma suppression on an all-native-alpha atlas because a legitimate pet color may match the fallback key. For chroma rows only, when visual QA confirms opaque key-colored residue inside the silhouette or negative-space openings, use `--reject-key-similarity` on the pre-despill atlas. This deliberately clears matching pixels and reports `alpha_preserved: false` plus the rejected count. Mixed atlases retain native-alpha rows unchanged. Fully transparent pixels are allowed outside the sprite silhouette, in unused cells, and in intentional negative-space openings that are part of the pet's design, such as loops or holes in a ribbon body. Reject any generated or repaired cell with accidental 100%-transparent holes inside a filled body, including horizontal bands, seam rows, scanline-like gaps, sliced-tile boundaries, or "see-through" interior stripes. Inspect suspect cells on a high-contrast background or alpha mask before accepting them; ordinary atlas validation is not enough when the hole is inside the silhouette. Allowed effects must satisfy all of these conditions: - The effect is state-relevant and helps explain the animation. - The effect is physically attached to, touching, or overlapping the pet silhouette, not floating nearby. - The effect is inside the same frame slot as the pet and does not create a separate sprite component. - The effect is opaque or cleanly antialiased, hard-edged enough for component extraction, and does not rely on a background matte. - The effect is small enough to remain readable at `192x208` without clutter. Avoid these by default because they usually break transparent-background cleanup or component extraction: - wave marks, motion arcs, speed lines, action streaks, afterimages, blur, or smears - detached stars, loose sparkles, floating punctuation, floating icons, falling tear drops, separated smoke clouds, or loose dust - cast shadows, contact shadows, drop shadows, oval floor shadows, floor patches, landing marks, impact bursts, glow, halo, aura, or soft transparent effects - text, labels, frame numbers, visible grids, guide marks, speech bubbles, thought bubbles, UI panels, code snippets, checkerboard transparency, white backgrounds, black backgrounds, or scenery - chroma-key-adjacent colors in the pet, prop, effects, highlights, or shadows when a row actually uses the chroma fallback - stray pixels, disconnected outline bits, speckle/noise, cropped body parts, overlapping poses, or any pose that crosses into a neighboring frame slot State-specific guidance: - `idle`: keep this calm and low-distraction. Use only subtle breathing, a tiny blink, a slight head or body bob, a very small material sway, or another quiet persona-preserving motion. The loop must still contain visible micro-variation; do not accept six effectively identical copies. Do not show waving, walking, running, jumping, talking, working, reviewing, emotional reactions, large gestures, item interactions, or new props. - `waving`: show the wave through paw, hand, wing, or limb pose only. Do not draw wave marks, motion arcs, lines, sparkles, symbols, or floating effects around the gesture. - `jumping`: show vertical motion through body position only. Do not draw shadows, dust, landing marks, impact bursts, bounce pads, or floor cues. - `failed`: tears, attached smoke puffs, or attached stars are allowed if they obey the allowed-effects rules; do not use red X marks, floating symbols, detached smoke, detached stars, or separate tear droplets. - `waiting`: show that Codex needs approval, help, or user input through an expectant asking pose. Keep it distinct from ordinary idle and review. - `running`: show active task work, processing, thinking, scanning, typing, or focused effort. Do not show literal foot-running, jogging, sprinting, treadmill motion, raised knees, long steps, pumping arms, directional travel, speed lines, dust clouds, floor shadows, motion trails, or detached motion effects. - `review`: show focus through lean, blink, eyes, head tilt, or paw/hand position. Do not add magnifying glasses, papers, code, UI, punctuation, symbols, or other new props unless they already exist in the base pet identity. - `running-right` and `running-left`: show directional drag movement through body, limb, and prop movement only. `running-right` must face and travel right; `running-left` must face and travel left. Their cadence must visibly alternate across the loop rather than repeating one nearly static stride. Do not draw speed lines, dust clouds, floor shadows, motion trails, or detached motion effects. ## 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 `<Pet>` with the pet's name or `your pet`: 1. Getting `<Pet>` ready. 2. Imagining `<Pet>`'s main look. 3. Picturing `<Pet>`'s poses. 4. Hatching `<Pet>`. What each step means: - `Getting <Pet> 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 <Pet>'s main look.` Generate the pet's main reference image. This becomes the visual source of truth. - `Picturing <Pet>'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 <Pet>.` 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. ## Time Budget And Convergence Aim to complete a normal pet run within 30 minutes while preserving every mandatory acceptance criterion. Treat this as a planning target and an incentive to maximize validated progress per minute, not as permission to weaken QA or package a failing pet. At the start of the run, allocate an approximate budget: - preparation: 2 minutes - base image: 3 minutes - standard rows: 10 minutes - look directions: 8 minutes - final QA and packaging: 5 minutes - buffer: 2 minutes Run independent generation jobs concurrently up to the worker limit, start deterministic checks as soon as each dependency is ready, and record actual stage plus repair time. Prefer character and prop constructions that naturally satisfy cell geometry, transparency, component connectivity, and direction semantics; identify likely conflicts such as open interior gaps, detached parts, thin connectors, asymmetric props, or ambiguous faces before row generation. After every failed attempt: 1. Classify the failure as visual semantics, identity, source-edge geometry, component connectivity, extraction, chroma, continuity, or final visual QA. 2. State the concrete evidence and the root condition the next action will change. 3. Use a deterministic correction for deterministic failures before regenerating imagery. 4. Regenerate only when the source visual is genuinely wrong, and preserve every property that already passed. 5. Compare the new result with the previous one. A repair counts as progress only when it reduces the number or severity of failures without breaking a previously passing gate. If the same root failure recurs twice, stop varying the prompt and change strategy: strengthen the cardinal pose families or row-level direction instructions, simplify the pose or prop construction, change the deterministic extraction method, or redesign the problematic visual feature. If a repair merely moves a failure to another cell or gate, treat that as a cycle and change strategy immediately. Use elapsed-time checkpoints: - At 15 minutes, verify the run is on pace and that the remaining dependency path is bounded. - At 25 minutes, prioritize the shortest quality-preserving path through remaining blockers and avoid optional polish. - At 30 minutes, continue only when the remaining work is clearly converging and bounded, such as final validation, one targeted repair, or packaging. - Keep recording elapsed time, retries, validation failures, and QA cost throughout the run, but do not pause or stop solely because elapsed time crosses 45 or 60 minutes. Continue until the pet passes, the user cancels, or a genuine external blocker prevents further progress. Never use the time target to skip blind direction QA, labeled semantics, continuity review, atlas validation, final background-cleanup validation, final visual QA, or any other acceptance criterion. ## Default Workflow 1. From the repository root, prepare a pet run folder and imagegen job manifest: ```bash SKILL_DIR="$(pwd -P)/.agents/skills/hatch-pet-v2" BACKGROUND_MODE=transparent "$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>" \ --background-mode "$BACKGROUND_MODE" \ --force ``` The script defaults to `--background-mode transparent` even when the flag is omitted. Keep `BACKGROUND_MODE=transparent` through every generation and extraction command. Set it to `auto` or `chroma` only when the user explicitly requests a legacy key-color workflow; record that choice in the run. For text-only requests, pass the concept through `--pet-notes` and omit `--reference`; `prepare_pet_run.py` will infer a name, description, compatibility 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. Set `transparent_background: true` on every built-in call in a strict run, including repairs and retries. 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.