hatch-fighter-pet

name	hatch-fighter-pet
description	Create, repair, validate, preview, and package Codex-compatible animated fighter pets: compact 2D arcade fighting-game sprites with combat stances, dashes, taunts, jumps, hit-stun, charge-ups, rushes, and special powers. Use when a user wants a Codex pet that feels like an original Tekken/Mortal-Kombat-inspired sprite fighter while still loading as a normal Codex custom pet.

Hatch Fighter Pet

Overview

Create a Codex-compatible animated custom pet that looks and behaves like a small original fighting-game character. This is a fork of $hatch-pet: it keeps the exact Codex pet atlas/package contract, but reinterprets the nine Codex animation rows as fighter moves.

The skill supports two motion sources:

• $imagegen row strips: default path, inherited from $hatch-pet.
• Video-derived rows: optional LayrKits-style intake for hard motion such as dashes, jumps, charge-ups, hit-stun, rushes, and special powers. The user or agent supplies a chroma-keyed video, then this skill extracts/selects/processes frames into Codex row strips.

The final output is still a normal Codex custom pet:

${CODEX_HOME:-$HOME/.codex}/pets/<fighter-name>/
  pet.json
  spritesheet.webp

Row Semantics

The Codex app still reads the same fixed rows and frame counts. Do not change row order, atlas size, cell size, or package shape.

Row	Codex state	Fighter meaning	Frames
0	idle	combat stance / breathing guard	6
1	running-right	dash right	8
2	running-left	dash left	8
3	waving	taunt / stance flourish	4
4	jumping	leap / aerial pose	5
5	failed	hit-stun, KO, or defeated	8
6	waiting	charge-up / power idle	6
7	running	forward rush loop	6
8	review	special power / finisher loop	6

Visual Style

The fighter must be original. "Tekken/Mortal Kombat style" means arcade fighter energy: strong silhouette, combat-ready stance, readable outfit/weapon/power identity, dramatic pose language, and bold sprite timing. Do not reproduce protected characters, logos, names, signature costumes, or exact moves.

Default style:

• compact 2D fighting-game sprite, readable inside 192x208
• full-body character with strong silhouette and clear limb separation
• thick dark 1-2 px outline, sprite-like hard edges, limited palette, flat cel shading
• original costume, weapon, power, and face design
• no scenery, floor, shadows, UI, text, watermarks, speech bubbles, or copied layout guides

Powers And Effects

Effects are allowed more often than in $hatch-pet, but only when they remain usable in a tiny Codex cell.

Allowed:

• flame fists touching the hands
• lightning wrapped around a weapon or gauntlet
• aura tightly hugging or overlapping the body
• impact sparks touching the body, weapon, or guarded limb
• small hard-edged smoke or crackle attached to the silhouette

Rejected:

• detached particles, floating icons, text, UI marks, loose symbols
• broad transparent glow haze, bloom, soft aura clouds, motion blur, smears
• cast shadows, floor shadows, scenery, backgrounds, camera shake, zoom, cuts
• effects crossing into a neighboring frame slot
• chroma-key-adjacent colors in the fighter or power VFX

Power rows such as waiting and review may be more dramatic, but the fighter identity must stay consistent.

Generation Delegation

Use $imagegen for normal visual generation. Before generating base art or imagegen row strips, load:

${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md

Do not call image APIs directly for the normal path. The base job may be prompt-only. Every $imagegen row-strip job must use the listed grounding images from imagegen-jobs.json, including the canonical base reference and the row layout guide.

For video-derived rows, do not use $imagegen to draw missing frames. Use supplied video frames only, through this skill's deterministic scripts.

Default Workflow

1. Prepare a run:

SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/hatch-fighter-pet"
python "$SKILL_DIR/scripts/prepare_pet_run.py" \
  --pet-name "<Name>" \
  --description "<one sentence>" \
  --pet-notes "<original fighter concept>" \
  --style-notes "<optional power/style notes>" \
  --output-dir /absolute/path/to/run \
  --force

2. Generate and record the base with $imagegen, then inspect ready jobs:

python "$SKILL_DIR/scripts/pet_job_status.py" --run-dir /absolute/path/to/run

3. Complete rows by either path:

• $imagegen path: generate the row strip from its prompt and input images, then record with record_imagegen_result.py.
• Video path: process an external chroma-keyed clip into a completed decoded row:

python "$SKILL_DIR/scripts/extract_video_frames.py" \
  --input /absolute/path/to/source-video.mp4 \
  --output-dir /absolute/path/to/run/video/extracted/review \
  --overwrite

python "$SKILL_DIR/scripts/select_video_frames.py" \
  --source-dir /absolute/path/to/run/video/extracted/review \
  --output-dir /absolute/path/to/run/video/selected/review \
  --indices "1,8,15,22,29,36" \
  --frame-prefix review \
  --beat-labels "ready,charge,release,impact,follow-through,recover"

python "$SKILL_DIR/scripts/process_power_frames.py" \
  --run-dir /absolute/path/to/run \
  --state review \
  --source-frames-dir /absolute/path/to/run/video/selected/review \
  --source-video /absolute/path/to/source-video.mp4 \
  --background-mode chroma \
  --chroma-key '#00FF00' \
  --selection-note "video-derived special power beats"

process_power_frames.py writes decoded/<state>.png, frame cells, preview/report files, and marks that job complete with source_provenance: video-derived-row.

4. For running-left, mirror running-right only when the fighter design is safe to mirror. Otherwise generate or process a left-facing row normally.

5. Finalize:

python "$SKILL_DIR/scripts/finalize_pet_run.py" --run-dir /absolute/path/to/run

Review qa/contact-sheet.png, qa/review.json, final/validation.json, and qa/videos/ before accepting the fighter.

Subagent Row Generation

After the base job has been recorded, row-strip visual generation via $imagegen should use subagents unless the user explicitly says not to. The parent owns manifests, recording, video processing, finalization, repairs, and packaging.

Subagents may only generate image rows and return the selected original $CODEX_HOME/generated_images/.../ig_*.png source path plus a short QA note. They must not edit manifests, copy into decoded/, run video scripts, record results, mirror rows, finalize, repair, or package.

Video-derived rows stay with the parent because they mutate the manifest and decoded outputs deterministically from supplied clips.

Repair Workflow

If finalization fails, use the smallest repair scope:

python "$SKILL_DIR/scripts/queue_pet_repairs.py" --run-dir /absolute/path/to/run

Regenerate only failed $imagegen rows, or rerun only the failed video-derived row with a better source clip or frame selection.

Acceptance Criteria

• Final atlas is PNG/WebP 1536x1872, transparent-capable, with 192x208 cells.
• Used cells are non-empty and unused cells are transparent.
• Row/frame counts match references/animation-rows.md.
• qa/review.json has no errors.
• Preview videos and contact sheet exist unless explicitly skipped.
• The fighter identity, palette, face, costume, weapon, and power identity stay consistent across rows.
• Powers are attached, hard-edged, readable, and contained inside each frame slot.
• No copied guide marks, text, UI, scenery, detached VFX, broad glow haze, clipping, slot overlap, or background artifacts.