Generate runcat runner

Generate RunCat Runner

Outcome

Produce validated PNG frames, validation.json, a numbered contact sheet, and a review GIF. Stop for visual approval, then guide the user through RunCatNeo's official editor and ask them to confirm menu-bar playback. Complete every phase; validation alone is not completion.

Read references/runcatneo-format.md only when a rule's source, frame ordering, timing, or troubleshooting detail is needed.

Boundaries

• Treat the directory containing this file as <skill-dir> and use its absolute path in commands.
• Work only under <workspace>/runcat-runners/<slug>-<timestamp>/ plus the optional shared <workspace>/runcat-runners/.venv/.
• Read only source and reference files that the user places in scope.
• Never write to RunCatNeo's app container, saved JSON, or private runner storage.
• Keep RunCatNeo import and playback confirmation in the official UI and user-operated.
• Never install an external image provider. Install the pinned Pillow dependency only after explicit user approval.
• Never request a secret in chat or put credentials in a run directory.
• Do not claim compatibility with an installed build other than 1.0.3.
• Do not package or submit to RunnerGallery.

Workflow

Show the user progress through these phases:

1. Brief and environment
2. Source and frames
3. Validation and preview
4. RunCatNeo import and playback

1. Brief and Environment

Infer details already present. Ask only for a missing choice that changes the result: subject, motion, style, or RunCatNeo rendering mode (template for monochrome tinting, color for original color). Use a short lowercase hyphenated slug for files and preserve the user's display name separately.

Choose the frame count from the motion, not from a universal default. Estimate how far the subject moves between frames and use the smallest count that keeps the path readable. For a circular path of radius r over N evenly spaced frames, adjacent displacement is 2 * r * sin(pi / N). Prefer overlap between adjacent positions when practical. Start with these project heuristics, then verify the preview:

Motion	Starting range
Local pulse, blink, or flicker	5-8
Compact gait or body cycle	7-10
Full orbit or continuous rotation	10-15
Multi-link or complex mechanism	15-24

These ranges are project heuristics, not RunCatNeo importer requirements. At runtime speed 1, RunCatNeo displays two frames per second, so N frames take N / 2 seconds per loop. More frames reduce stepping but lengthen the loop. Stay at or below 30 frames, and never treat a passing validator as proof that the motion is smooth. Read references/runcatneo-format.md for the supporting data and motion example.

Resolve the Python executable:

1. Start with python3.

2. Verify the interpreter before loading the helper:

   python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 2)'

   Stop with the observed version if the command is missing or exits 2.

3. Run:

   python3 <skill-dir>/scripts/runner_tool.py doctor --app /Applications/RunCatNeo.app [supplied-source-paths...]

4. If the standard app path is missing, ask the user for the actual .app path and rerun doctor --app <actual-app-path>. If RunCatNeo is still unavailable, stop and point to its official App Store page: https://apps.apple.com/us/app/runcat-neo/id6757801838.

5. If Pillow is missing or is not version 12.1.1, explain that the bundled image helper is tested with Pillow 12.1.1. After approval only, run:

   python3 -m venv <workspace>/runcat-runners/.venv

   <workspace>/runcat-runners/.venv/bin/python -m pip install -r <skill-dir>/requirements.txt

   Set the runner Python to <workspace>/runcat-runners/.venv/bin/python and rerun doctor.

6. If the installed RunCatNeo build is not 1.0.3, show the warning and continue only after explicit acceptance.

Create a new timestamped run directory. Never reuse a non-empty run directory. Keep generated working files under its work/ directory, preserve supplied originals, and remind the user to use only artwork they have permission to use.

2. Source and Frames

Use the first applicable row:

Available input or capability	Route
User frame sequence or regular sheet	Preserve its order; extract a regular sheet when needed.
User transparent source	Apply local transforms to the supplied source.
Codex built-in $imagegen	Create one coherent transparent master or sheet.
Simple pixel, icon, or geometric request	Write a per-run Pillow work/render_runner.py.
User-configured external provider	Use only after naming the provider, data transfer, and possible cost and receiving explicit consent.
None of the above	Stop and ask for a source image.

Do not generate every frame independently. Prefer one coherent sheet or derive all motion from one source. Keep procedural renderer code in the run's work/ directory, use no network, fix any random seed, and make it write ordered source-frame-N.png files under work/source/ without modifying the final frames/ directory directly.

For a regular sheet run:

<runner-python> <skill-dir>/scripts/runner_tool.py extract --sheet <sheet-path> --output-dir <run-dir>/work/source --columns <columns> --rows <rows> --count <frame-count>

Pass source frames to normalization in the intended playback order:

<runner-python> <skill-dir>/scripts/runner_tool.py normalize --slug <slug> --output-dir <run-dir>/frames [--pixel-art] <ordered-source-frame-paths...>

Use --pixel-art only for intentionally hard-edged pixel/icon work. Never edit supplied originals.

3. Validation and Preview

Run validation before preview:

<runner-python> <skill-dir>/scripts/runner_tool.py validate --frames-dir <run-dir>/frames --slug <slug> --name <display-name> --mode animation --expect-transparency --output <run-dir>/validation.json

Use --mode static only when the user explicitly requested one frame. Omit --expect-transparency only when an opaque background was explicitly requested.

• Exit 0: continue and disclose warnings.
• Exit 1: create a new timestamped attempt, repair the named asset there, and rerun validation.
• Exit 2: fix the environment or I/O failure; do not treat it as an asset rejection.

Build QA media only after validation has no errors:

<runner-python> <skill-dir>/scripts/runner_tool.py preview --frames-dir <run-dir>/frames --slug <slug> --contact-sheet <run-dir>/contact-sheet.png --gif <run-dir>/preview.gif

Inspect the numbered contact sheet for order, identity, clipping, alignment, transparency, and visible motion. Do not rely on agent-side GIF inspection because some hosts expose only its first frame. Show both files to the user and ask for approval or a concrete revision.

4. RunCatNeo Import and Playback

Continue only after the user approves the frames and motion.

1. Ask the user to open RunCatNeo Settings and its Runner custom-runner editor.
2. Ask them to enter the display name and choose the agreed template/color rendering mode.
3. Ask them to add every PNG from <run-dir>/frames/.
4. Explain that source filenames do not guarantee import order. Have them compare the editor preview with the numbered contact sheet and drag frames into order if necessary.
5. Ask them to save, select the custom runner, and observe at least one complete menu-bar loop.
6. Report completion only after the user confirms playback and rendering mode.

Common Mistakes and Recovery

• An externally generated image or sheet is only a source; it never replaces normalization, validation, and approval.
• Numbered filenames do not establish RunCatNeo playback order; the official editor and real playback are authoritative.
• Preserve the run directory after every failure.
• For any validation repair or visual revision after final frames exist, create a new timestamped run directory and regenerate or copy only the needed source inputs there. Never clear or overwrite the previous attempt's frames/ directory.
• Never silently change providers or rendering mode.
• Never suppress Pillow decompression-bomb protection or process a source over 25 MiB or 20 million pixels. Ask for a smaller export.
• Let RunCatNeo report a duplicate custom-runner name; ask for a new name instead of reading private app state.
• On an untested app build, say exactly which build was observed and that the rules are pinned to 1.0.3.
• If no generation route is suitable, stop and request a source instead of fabricating image-generation capability.