Create Clean Codex Pet

Create Clean Codex Pet

Compose the installed $hatch-pet workflow for production, add a lightweight character-motion pass before row generation, then enforce a mandatory edge-quality gate. Treat motion design, structural validation, and visual edge validation as separate requirements.

Workflow

1. Read and follow the installed $hatch-pet skill. Use its current atlas geometry, state semantics, generation, repair, validation, packaging, and cleanup rules as authoritative.
2. For a new pet or motion repair, write a compact references/action-brief.md before preparing row prompts. Define one personality contradiction, one motion signature, one idle micro-action, and a distinct intention for every state. Read references/action-design.md only for this motion-design work; skip it for edge-only repair, packaging, or unchanged reinstallation.
3. Keep one canonical full-body identity image. Generate each required state from that reference and the action brief. Add only the matching state cue to each row prompt; do not paste the full brief into every prompt. Repair only the smallest failing row.
4. Use the chroma key stored in pet_request.json. Choose a key that does not conflict with the character; magenta is usually safer for blue characters.
5. Finish the normal hatch-pet pipeline before edge cleanup. Require the expected atlas dimensions, state rows, frame counts, alpha channel, and zero structural errors.
6. Inspect contact sheets and motion previews for personality, readable intent, and state separation before accepting visual generation.
7. Run the edge-quality gate below on the finalized atlas.
8. Promote and install only the cleaned candidate that passes motion, structure, and dark/light edge inspection. Keep the prior atlas as a backup.
9. When the user mentions a showcase or display GIF, create and directly show the large transparent GIF defined below from the accepted cleaned atlas.

Motion-quality gate

Keep movement readable inside a 192x208 cell. Prefer silhouette, gaze, weight shift, timing, asymmetry, anticipation, and follow-through over detached effects or new props.

Require:

• one consistent motion language across all rows: rhythm, weight, amplitude, reaction speed, and use of space
• a recognizable motion signature that appears with restrained variation rather than in every frame
• visible micro-variation in idle
• clearly different intentions for waiting, task-active running, and review
• readable directional gait in running-right and running-left
• action-result or recovery character in expressive rows such as jumping and failed, when frame count permits
• no row that could be transferred unchanged to an unrelated character without losing meaning

Do not force a five-beat story into every loop. Use the fuller motivation-preparation-action-result-aftereffect arc only when it improves the state at pet scale. If motion fails but identity and edges pass, repair the smallest affected row; do not treat technical validity as motion acceptance.

Showcase GIF default

When the user asks to show, display, preview, or share the pet as a GIF, default to one large transparent montage GIF instead of only separate state GIFs:

• 1280x800, looping for 6 seconds
• five simultaneous actions: idle, waving, running-right, jumping, and failed
• three sprites on the top row and two centered on the bottom row
• fully transparent background using GIF binary alpha
• no text, labels, borders, scenery, shadows, or decorative background
• preserve each state's native timing while sampling them on one shared timeline

Generate it only from the promoted clean atlas:

python3 "$SKILL_DIR/scripts/render_pet_showcase_gif.py" \
  --atlas "$RUN_DIR/final/spritesheet.webp" \
  --output "$RUN_DIR/showcase/pet-showcase-transparent.gif" \
  --qa-output "$RUN_DIR/showcase/pet-showcase-transparent-qa.png" \
  --report-output "$RUN_DIR/showcase/pet-showcase-transparent.json" \
  --force

Require the report to have ok: true. Inspect the QA image on dark and light backgrounds, then embed the absolute GIF path in the final response so the animation is visible in conversation; do not provide only a filesystem link. A user's explicit request for separate GIFs, a solid background, labels, another layout, or another size overrides this default.

Read references/showcase-gif.md only when tuning, diagnosing, or changing the showcase GIF contract.

Edge-quality gate

Never accept a transparent atlas from a checkerboard preview or alpha statistics alone. Composite a representative frame over a dark background and a light background at 4x nearest-neighbor scale. Look for key-colored halos, pale outlines, dark contamination, broken whiskers, missing outline pixels, and silhouette erosion.

Run the bundled cleaner non-destructively:

SKILL_DIR=/absolute/path/to/create-clean-codex-pet
RUN_DIR=/absolute/path/to/pet-run
KEY=$(jq -r '.chroma_key.hex' "$RUN_DIR/pet_request.json")

python3 "$SKILL_DIR/scripts/clean_pet_edges.py" \
  --input "$RUN_DIR/final/spritesheet.webp" \
  --output "$RUN_DIR/final/spritesheet-clean.webp" \
  --key-color "$KEY" \
  --qa-output "$RUN_DIR/qa/edge-before-after.png" \
  --report-output "$RUN_DIR/qa/edge-clean-report.json"

The cleaner must:

• preserve the 1536x1872 Codex atlas and every animation cell
• remove chroma contamination from semi-transparent edge pixels
• avoid alpha contraction by default so thin outlines and whiskers survive
• normalize fully transparent pixels to RGBA zero
• encode WebP losslessly with exact transparent RGB handling
• produce a before/after dark/light QA image and JSON report

Read references/edge-quality.md when diagnosing a failed edge gate or tuning thresholds.

Acceptance

Require all of the following:

• the hatch-pet atlas validator reports no errors
• the cleaner report has ok: true
• width is 1536, height is 1872, and mode is RGBA
• fully transparent pixels with non-zero RGB residue equal 0
• the before/after QA image shows no key-colored fringe on dark or light backgrounds
• outlines, whiskers, paws, tail, and other thin features are not eroded
• animation identity, frame count, scale, baseline, direction, and state semantics remain unchanged
• the motion-quality gate passes and the nine states share one character-specific movement language
• pet.json still points to spritesheet.webp
• the installed atlas checksum matches the accepted project atlas
• when a showcase GIF was requested, its report is ok: true, its QA image passes dark/light inspection, and the GIF is embedded in the final response

Repair decisions

• If only semi-transparent pixels contain the key color, clean the assembled atlas; do not regenerate poses.
• If cleanup removes outline pixels, restore the backup and reduce cleanup strength. Do not add edge contraction as the first response.
• If the key is also a real character color, regenerate the failing source row with a non-conflicting key instead of applying aggressive cleanup.
• If the source has gradients, shadows, glow, blur, or scenery mixed into the key background, regenerate the smallest failing row. Deterministic cleanup cannot reliably infer the intended silhouette.
• If one row fails identity or motion QA, repair that row through $hatch-pet; edge cleanup is not a substitute for visual generation repair.
• If the motion is technically correct but generic, revise that state's action cue from references/action-brief.md and regenerate only that row.
• If waiting, running, and review read as the same pose, clarify intention and timing before changing props or adding effects.

Promotion

After acceptance:

1. Copy the current atlas to spritesheet-before-edge-clean.webp.
2. Replace the project spritesheet.webp with the accepted cleaned candidate.
3. Re-run the installed hatch-pet atlas validator on the promoted file.
4. Copy pet.json and spritesheet.webp together to ${CODEX_HOME:-$HOME/.codex}/pets/<pet-id>/ only when the user requested installation.
5. Compare SHA-256 checksums between project and installed atlases.
6. Report the atlas, backup, QA image, JSON report, validation result, and install path.