Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use only the component-row pipeline. Do not treat one-shot master sheets, fixed-grid atlas cutting, local drawing, or static fallback as a successful sprite result.
ํ์ ๊ฒ์ดํธ โ AI raw ๋ ์ต์ข ์์ ์ด ์๋๋ค (BLOCKING)
identity truth = accepted idle anchor
motion truth = layout guide + paired/basis row when needed
base truth = used only to create idle anchors, then removed from row inputs
The full reference-ownership flow (base โ idle anchors โ base ํ๊ธฐ โ basis/paired rows) and the base re-attach ban live in docs/architecture.md ยง5.
A weak idle anchor poisons every state โ proportions, style, and identity drift compound across all rows. Before any row generation, answer the gate question y/n:
Is there an image good enough to lock as the canonical base idle?
The base idle locks only when all of these hold:
Full body, nothing cropped (head to feet inside frame).
The final proportions and style the user asked for are already correct in this image (for example SD / chibi head-to-body ratio, pixel look, outline weight). The base defines the target โ do not plan to "fix it later" in the rows.
For a pixel-art run (fit.pixel_unfake): the base itself is true pixel art โ a uniform pixel-block grid is measurably present and edges are hard (no anti-aliased fringe). The style contract delegates style authority to this image, so a non-pixel base structurally produces a non-pixel row.
Identity matches the character sheet / reference (face, hair, markings, palette, props).
One clear single idle pose, facing the intended camera, readable silhouette at small size.
Background is a flat clean chroma-ready fill (or trivially keyable).
If the answer is n: generate/iterate base candidates, review each against the criteria above, and re-gate. Do not run prepare_sprite_run.py until a base is locked. "Good enough for now" is not a pass โ drift only grows once the rows start. When the answer is y, that exact file becomes the accepted idle anchor for its direction; keep the original generation so the lock decision is auditable, but do not attach it again after the idle anchors have replaced it as row identity truth.
export_aseprite.py (sprite-gen export-aseprite) โ describe the composed atlas as Aseprite-compatible JSON for Phaser or Flame; usage, mapping, and limitations: docs/engine-export.md.
preview_animation.py โ QA previews from extracted frames: contact sheets + state GIFs under qa/.
compose_selected_cycle.py โ record a human-selected frame subset as a selected-cycle manifest + QA GIF/contact sheet (reads curation.json by default; --frames overrides).
compose_sprite_gif.py โ clean transparent GIF export: single frame set, or --run-dir batch (one GIF per state from request fps + curation.json) into <run-dir>/exports/; called by the webview's Export-GIFs button and the v2 desktop app.
inspect_sprite_run.py โ deterministic row inspection for the automatic correction loop: expected vs found frame count, 64-bin RGB histogram similarity, dHash silhouette similarity, motion presence, centroid jitter, and extraction warnings.
score_sprite_run.py โ score an inspect report (0-100), preserve the best-candidate rank signal, and turn measured defects into provider-ready correction hints.
run_correction_loop.py โ bounded inspect โ score โ correction-hint loop (max 3 passes by default). It can run as a dry-run verifier without a provider, or call an explicit provider command; missing provider without --dry-run fails loudly.
gif_utils.py โ shared transparent-GIF writer.
curation.py โ curation sidecar SSoT (schema + transform math + the stamping atomic writer) shared by the compose scripts, the anchor CLI, and the webview server so they never drift.
sprite_gen/curate/anchor.py (sprite-gen anchor) โ direction-anchor SSoT: which curated instance is a direction's identity (human pin > the anchor row's sequence head), the post-processing bake of that one frame, and the references/anchors/<dir>-anchor-x8.png derived cache that row generation attaches. Reroll, the generation plan, and the curation view's anchor chip all resolve through it.
sprite_gen/spec/runio.py โ safe run-dir IO: single-writer lock (.sprite-gen.lock) + atomic writes for the extract/compose/export/unpack writers, so parallel agents cannot interleave writes into one character folder.
sprite_gen/serve/serve_curation.py (sprite-gen curation) โ standalone curation webview for one run dir (works from Claude Code Desktop, the Codex app, or any host with the skill). The -m sprite_gen.serve.serve_curation module form and the scripts/serve_curation.py wrapper reach the same declaration and the same implementation โ three live entry forms, one program (launch forms: docs/curation.md). When <run-dir>/variants/recolor.report.json is present, the view also blink-compares baked colourways and records the adopted name in curation.json.recolor.picked (detail: docs/recolor.md).
sprite_gen/effects/recolor.py (sprite-gen recolor / sprite-gen recolor-palette) โ deterministic palette-swap bake. recolor-palette drafts a frequency-ordered palette map from a base sheet; recolor takes base sheet + recolor spec and bakes N variant sheets + a per-variant substitution report into <run-dir>/variants/ (or an explicit --out-dir). Exact RGB match by default (dot-art safe); opt-in Chebyshev tolerance for soft edges. Alpha preserved, geometry untouched โ a base manifest describes every variant. No Silent Fallback: unused map sources and unmapped passthrough colours are named and counted in recolor.report.json. Detail: docs/recolor.md.
sprite_gen/compose/compose_layers.py (sprite-gen compose-layers) โ deterministic composite bake for a run that declares a rig. Stacks curated rows onto each other by integer pivot translation + arbitrary alpha masks (no resampling, rotation or scale of its own) into <run-dir>/layers/<name>.png + <name>.manifest.json + layers.report.json. Optional and opt-in: a request with no rig / track / layers is not a layer run and is refused by name rather than composed. All-or-nothing โ declaration, composition and publish: one violation reports every violation and writes nothing. Declaration schema, CLI usage, and what prepare carries: docs/layer-tracks.md.
unpack_atlas_run.py โ inverse of compose: rebuild a curator-ready run dir from a finished sheet (--grid > --manifest > auto-detect) or import a PNG folder (--pngs-dir, with sibling meta.json labels/iso grid).
export_curated_pngs.py โ export curated frames back to named PNGs with the transform baked in, into <run-dir>/curated/; the deliverable for imported still sets.
cutout.py (sprite-gen cutout) โ background remover for imported images (not pipeline output, which is already keyed). Routes on the corner background colour (--key auto|white|magenta|green): white/ivory โ position matte (corner flood-fill keeps interior highlights unholed โ decontaminated soft-alpha border + soft erode); magenta/green key โ reuse the verified extract.remove_chroma_background engine as-is (no drift โ key colours are absent from objects so its colour-only cut is safe there). --white-check writes cyan/magenta/yellow verification composites. No Silent Fallback (leftover non-zero RGB under transparency raises).
slice_sheet_cells.py โ slice a multi-figure grid sheet (same character, N expressions/variants in one image) into per-cell standing cuts: v1.13 chroma alpha + centroid cell assignment + merged-figure split/in-cell re-label + neighbour-debris drop + per-cell height normalization + shared feet baseline. For dialogue cut-in portraits (็ซใก็ตต), not animation rows. Detail: docs/sheet-slicing.md.
check_visible_magenta.py โ optional screenshot QA guard for visible chroma-key leakage.
Workflow
Pass the Base Lock Gate above. Do not start step 1 until a base idle is locked (y).
Generate one image per state with the engine's own gen command (generation is engine-owned; the image-gen skill is now a thin shuttle over this โ docs/gen.md):
Use prompts/<state>.txt as the prompt; save the selected image as raw/<state>.png. --provider is optional โ the default is codex (SPRITE_GEN_DEFAULT_PROVIDER env overrides it; an observable grok fallback kicks in only if codex is unavailable). Pass --provider grok explicitly for the faster backend; codex adheres tighter to negative constraints. Default policy: docs/gen.md. Keep the request chroma key on the background (extraction removes it). Reference attachment rules:
Generation providers are engine backends, not user-facing agents. Selecting
grok launches a headless grok -p process owned by GrokProvider; it does not
require or route through a separate user-facing skill/task. Spawning a visible
worker/agent is the caller's orchestrator concern โ out of this engine's scope.
Command chain: docs/gen.md.
Simple/default states (before direction-anchor mode exists): attach exactly two references โ base-source.<ext> (canonical identity) + references/layout-guides/<state>.png (layout only).
Direction-anchor mode: do not attach base-source.<ext> to action rows. Attach the accepted target-direction anchor (a single-pose single image โ never a multi-frame idle row) + the state layout guide; for a paired row also attach the basis row as timing/scale/motion reference only. Never choose the anchor crop by hand โ ask the pipeline, right before each generation:
$SPRITE_GEN_ROOT/.venv/bin/python -m sprite_gen.cli anchor \
--run-dir <run> --for-state <state> # prints the identity ref path (bakes it)
It returns references/anchors/<dir>-anchor-x8.png for an action row (the curated anchor frame โ pixel edits, transforms, deletions and reordering all baked, upscaled ร8 NEAREST) and base-source.<ext> for an anchor row or a non-direction run. The file is a derived cache, so re-run it every time; which frame is the anchor is the human's call (--pick <state>#<index>, or the pin button in the curation view) and defaults to the anchor row's curated sequence head. Chain details: docs/directional-anchor-workflow.md.
Hatch-pet-style locomotion may attach additional references only when they are part of the row plan, recorded in qa-notes.md: original sheet / canonical base (identity support only), a previous gait row such as raw/running-right.png (motion rhythm only), or an accepted motion-QA artifact (gait readability support only).
This removes the request chroma key, finds connected sprite components, fits each pose into a fresh transparent request-sized cell, and writes frames/<state>/frame-N.png plus frames/frames-manifest.json.
Standalone local webview: side-by-side frame compare, select/reject, drag-to-reorder play sequence, non-destructive per-frame transform saved to curation.json (originals never rewritten; no sidecar = all frames in order, an explicit default). Usage detail, finished-sheet editing via unpack_atlas_run.py, and the standalone image-candidate curation path: docs/curation.md.
manifest.json.frame_layout is the runtime SSoT. Game code must consume rectangles from the manifest and must not recover frame rectangles from alpha content at runtime.
4.5. (Optional) Bake palette-swap colourways of the finished atlas:
# draft the opaque colours of the base sheet (edit into a recolor spec)$SPRITE_GEN_ROOT/.venv/bin/sprite-gen recolor-palette \
--base <run>/sprite-sheet-alpha.png --out <run>/palette.draft.json
# bake N variants from a recolor spec (kind "sprite-gen-recolor") into <run>/variants/$SPRITE_GEN_ROOT/.venv/bin/sprite-gen recolor \
--run-dir <run> --spec <run>/recolor.spec.json
Exact RGB match by default (dot art); opt-in match: "tolerance" for soft edges. Same input โ same output bytes. The report names every unused map source and every unmapped passthrough colour โ nothing outside the map vanishes quietly. Spec schema, report fields, and curation-view adopt flow: docs/recolor.md.
4.6. (Optional, rig runs only) Bake the declared composite stacks:
Only for a run whose sprite-request.json declares rig / states.<state>.track / layers โ every other run is untouched by this feature and this step is skipped. It stacks the curated rows (integer pivot translation + alpha masks, no resampling) into <run>/layers/<name>.png + <name>.manifest.json + layers.report.json, so the same run bakes the same bytes every time. --names a,b bakes a subset and leaves the rest of layers/ alone. Declaration schema, landmark rules, track kinds, and what prepare carries: docs/layer-tracks.md.
Launch the curation webview automatically (default closing step):
After the atlas composes (and QA previews exist), launch the webview in the background and report the printed URL โ finishing a run means handing the human the open webview, not just file paths. Multi-agent launch rules (per-launch free port, one webview per run dir, .sprite-gen.lock, --no-open for headless): docs/curation.md. Skip the auto-launch only for an explicitly unattended batch run.
SSoT
Every run starts with sprite-request.json. It owns the numeric recipe used by prompts and scripts:
{"version":1,"kind":"sprite-gen-request","engine":"component-row","character":{"id":"demo-hero","description":"same character as the base image"},"cell":{"shape":"square","size":256,"safe_margin":24},"chroma_key":{"name":"magenta","hex":"#FF00FF","rgb":[255,0,255]},"states":{"idle":{"frames":4,"fps":4,"loop":true,"action":"subtle breathing and blinking"},"attack":{"frames":4,"fps":8,"loop":false,"action":"simple windup, strike, recovery attack pose sequence with no detached effects"},"jump":{"frames":4,"fps":8,"loop":false,"action":"jump arc through body position only"},"wave":{"frames":4,"fps":6,"loop":false,"action":"friendly hand wave gesture; arm changes clearly while feet stay planted"}}}
256 is a default variable, not a hidden constant. Change it through the request, then regenerate guides, prompts, extraction, and atlas from the same request.
When safe_margin is omitted, the default is proportional: 9.4% of the cell dimension per axis, floored (256 โ 24px, 128 โ 12px, rect 192ร208 โ 18/19px). An explicit request/CLI value is absolute and wins as-is.
The generated row uses the request cell shape. The final atlas is still consumed through manifest.json.frame_layout; runtime code must not assume square cells.
Prompt Contract
The generated row prompt must come from prompts/<state>.txt. Do not hand-write frame counts into a separate prompt. The prompt requires:
exact state frame count from sprite-request.json
one complete full-body pose per invisible request-sized slot
safe margin from sprite-request.json
same locked anchor identity across every frame
motion-only row responsibility: the row should solve limb/body timing, not rediscover character details
flat chroma-key background from sprite-request.json
no shadows, glows, smears, speed lines, dust, scenery, text, UI, frame numbers, guide boxes, or detached effects
If image generation produces guide boxes, visible labels, overlapping poses, backgrounds, cropped bodies, or identity drift, regenerate the row. Do not repair bad visual generation by drawing or tiling sprites locally.
Output Contract
Install from curated/, never from frames/.frames/ is pre-curation โ the human's
picks, pixel edits and transforms live in curation.json and are applied downstream. Copying
frames/ into an app silently ships the un-edited image and nothing fails. Stills โ
export_curated_pngs.py then curated/. Animation โ the composed atlas + manifest.
Contract: docs/run-contract.md ยง2-c.
One worker owns exactly one character folder. The canonical run-dir folder tree โ every input/output file and which ones drive the curation view โ is owned by docs/run-contract.md ยง2. Do not let multiple workers write the same character folder. The curation.json sidecar schema (selected/order/transforms/pixel_unfake) and its folder-collision rule: docs/curation.md.
Runtime Contract
manifest.json must contain:
game_input: "sprite-sheet-alpha.png"
degraded_static_fallback: false
animation.rows.<state> with frames, fps, durations_ms, and loop
Runtime must sample only the active rectangle. Rendering the whole atlas on one plane, guessing a grid, or showing a raw chroma row is a failed integration.
Frame timing and cell reuse (2026-07-16, Aseprite-JSON ๊ณผ ๋ํ ํจํด):
Static fallback is allowed only as explicit survival output when generation is blocked. It is not a sprite-gen pass and must not create sprite-sheet-alpha.png.
QA
Automated checks (must all pass before reporting done):
frames/frames-manifest.json.ok is true
sprite-sheet-alpha.report.json.ok is true
every state has the declared frame count
no frame is empty or near-opaque background
no frame has excessive edge pixels or chroma-adjacent pixels
browser screenshots pass scripts/check_visible_magenta.py when used in a game
This writes correction-loop.report.json, per-attempt inspect.json, score.json,
and correction-hints.txt. A real regeneration loop must pass an explicit
provider command; there is no silent fallback generator.
Use --min-attempts 2 for a live E2E that must exercise at least one provider
regeneration even when the seed candidate already clears the score gate.
Motion Continuity (BLOCKING)
Static identity QA is not enough โ a row can have the right frame count, clean alpha, and consistent identity and still animate as garbage. Build the previews and review motion as motion:
The full verdict criteria (cyclic locomotion, loop seam, non-loop gestures, humanoid per-frame anatomy review, independent second opinion) live in docs/qa-motion.md. If a row fails motion continuity, regenerate that row โ do not repair motion by drawing or re-timing frames locally. Record the per-state motion verdict in qa-notes.md.
Leaf docs are one link deep from this hub. The tree groups them by the concern
you are in โ walk down the branch that matches your task, don't scan the flat
list. Each doc owns its tables; SKILL.md and the others point rather than restate.
