---
name: wallive-pet
description: Create, repair, validate, and package Wallive Dynamic Island Pet .pet packages. Use when a user wants an AI-generated Wallive pet, a pet.json manifest, one in-place 30-frame horizontal animation strip per idle/sleep/focus/cheer/lowBattery/hide/typing/waitingApproval/celebrate/confused/peekOut state, or a custom Name.pet package that Wallive can import. This skill delegates visual generation to an installed image generation skill and uses bundled scripts for deterministic Wallive manifest validation and packaging.
---

# Wallive Pet

Create a Wallive-compatible Island Pet package from a concept, brand cue, reference image, or existing spritesheet.

Wallive is not Codex Pet compatible. Always produce Wallive's own `.pet` package:

```text
MyMascot.pet/
├── pet.json
└── states/
    ├── idle.webp
    ├── sleep.webp
    └── ...
```

`MyMascot.pet` is a macOS directory package. Wallive Settings imports that package and copies its contents into `~/Library/Application Support/Wallive/pets/current/`.

## Use Image Generation Indirectly

Use the installed `$imagegen` or `$gpt-image` skill for visual generation. Do not call image APIs directly from this skill. Pass the prompt templates below as the visual contract, then use the scripts here only for manifest creation, validation, and packaging.

If the user supplies reference art, keep it as the identity source of truth. If no reference is supplied, generate one base pet first and use it as a reference for every animation strip.

## Runtime Shape

Default strip contract:

- frame size: `192x208`
- frames per animation: `30`
- strip size per state: `5760x208`
- animation loop: `true`
- playback fps in `pet.json`: positive speed value, usually `8` to `14`
- output images: one `states/<state>.webp` or `states/<state>.png` file per state
- manifest: `pet.json`
- package: `Name.pet/`

Required state strips:

| State | Image | Frames | Suggested FPS | Loop |
|---|---|---:|---:|---|
| `idle` | `states/idle.webp` | 30 | 12 | true |
| `sleep` | `states/sleep.webp` | 30 | 8 | true |
| `focus` | `states/focus.webp` | 30 | 12 | true |
| `cheer` | `states/cheer.webp` | 30 | 14 | true |
| `lowBattery` | `states/lowBattery.webp` | 30 | 8 | true |
| `hide` | `states/hide.webp` | 30 | 1 | true |
| `typing` | `states/typing.webp` | 30 | 14 | true |
| `waitingApproval` | `states/waitingApproval.webp` | 30 | 12 | true |
| `celebrate` | `states/celebrate.webp` | 30 | 14 | true |
| `confused` | `states/confused.webp` | 30 | 12 | true |
| `peekOut` | `states/peekOut.webp` | 30 | 12 | true |

Wallive hides the view whenever state is `hide`; `states/hide.webp` may be fully transparent but still has 30 cells.

## Visual Rules

- Keep one consistent pet identity across all rows: same face, body proportions, palette, material, markings, and core props.
- Use a clean transparent or removable flat background while generating. Final strips must have transparent background.
- Center the pet inside each `192x208` cell with safe padding.
- Every visible strip is an in-place loop: the pet's body anchor, feet/belly baseline, and visual center stay at the same cell coordinates in every frame.
- The last frame of each strip must connect smoothly back to frame 0 with no visible pop.
- Motion should be clearly readable at Dynamic Island size. Use medium-amplitude local acting: visible squash/stretch, body lean around a fixed anchor, head tilt, arm/ear/tail movement, and strong expression changes.
- Do not make the animation barely perceptible. Blinking alone is not enough except as a secondary detail.
- Motion is local only: pose, expression, blink, squash/stretch, head/limb/ear/tail movement, and body lean around a fixed anchor. Do not move the whole pet across the cell.
- Use pose and expression changes rather than detached effects.
- Avoid text, letters, symbols, UI, speech bubbles, frame numbers, visible grids, shadows, halos, motion trails, loose sparkles, detached particles, walking, running, sliding, drifting, jumping travel, or camera movement.
- Make details readable at Dynamic Island size.

## Prompt Template

Use this as the base visual prompt and fill in `<...>` fields:

```text
Create one production animation strip for a small Wallive Dynamic Island desktop pet.

Character identity:
<pet name and stable visual description>

Style:
<style notes, e.g. soft sticker mascot, plush toy, pixel art, clay, flat vector, 3D toy>

Canvas contract:
Generate exactly one horizontal sprite strip for state `<state>`. The strip has 30 columns and 1 row. Each cell is 192x208 pixels. The final image should be 5760x208 pixels. This is a 30-frame animation sequence, not 30fps playback. Keep the same character in a consistent style and scale. Keep each pose centered inside its cell with safe padding. This is in-place animation only: keep the pet's body anchor, baseline, and visual center fixed at the same coordinates in every frame. Do not translate the whole character. Use medium-amplitude local acting so the motion is obvious when displayed small: visible squash/stretch, head tilt, arm/ear/tail movement, body lean around the fixed anchor, and strong expression changes. The final frame must connect smoothly back to the first frame. Use transparent background if supported; otherwise use a flat chroma key background that can be removed cleanly.

State action:
<one state description from the list below>

Hard constraints:
No text, no letters, no logos, no UI panels, no frame labels, no visible grid lines, no speech bubbles, no detached icons, no shadows, no scenery, no walking, no running, no sliding, no drifting, no travel jumps, no camera movement. Preserve the same character identity in every frame. Preserve the same anchor point and baseline in every frame. Make the strip loop cleanly from frame 29 back to frame 0. Avoid tiny micro-motions that disappear at small size.
```

State descriptions:

- `idle`: visible in-place breathing with gentle squash/stretch, occasional head bob or ear/tail sway, calm default loop.
- `sleep`: sleepy pose with clear slow breathing, head nod, drooping ears/body, closed or heavy eyes.
- `focus`: attentive work focus with noticeable forward lean around a fixed anchor, eye narrowing, small hand/ear movement.
- `cheer`: happy reaction with clear arm/ear lift and body squash/stretch while the body anchor stays fixed, no detached confetti.
- `lowBattery`: tired low-energy pose with obvious sag, slow head dip, droopy expression, anchored body.
- `hide`: empty transparent strip or minimal tucked-away pose.
- `typing`: active coding or typing energy expressed through pose only, with clearly moving paws/hands and alert expression, anchored body; no readable text or UI.
- `waitingApproval`: expectant asking pose with visible lean-in, raised hand/ear, eye movement, anchored body.
- `celebrate`: stronger success celebration than cheer with big local squash/stretch, arms/ears up, bright expression, still no loose floating effects.
- `confused`: puzzled expression with visible head tilt, body recoil, and return to starting pose for a clean loop, no punctuation marks.
- `peekOut`: fixed-position peek from behind a top island edge or border, with clear vertical bob, eyes widening, ear/head movement, no lateral movement.

Generate one strip at a time with the same identity reference. Before packaging, inspect each strip at cell level. Reject and regenerate any strip where the character shifts position, changes scale, changes anchor, ends on a pose that pops when returning to frame 0, has anything other than 30 cells, or looks nearly static at Dynamic Island size.

## Deterministic Packaging

After visual generation, place files in a working folder and run:

```bash
SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/wallive-pet"
python "$SKILL_DIR/scripts/write_manifest.py" \
  --package-dir /absolute/path/to/Name.pet \
  --pet-id "<stable-id>" \
  --pet-name "<Display Name>"
python "$SKILL_DIR/scripts/validate_manifest.py" \
  --package-dir /absolute/path/to/Name.pet
```

If this skill was installed from Wallive Settings into `~/.ai/skills/wallive-pet`, use that path for `SKILL_DIR` instead:

```bash
SKILL_DIR="$HOME/.ai/skills/wallive-pet"
```

The final deliverable should be the `.pet` directory package:

```bash
open -R /absolute/path/to/Name.pet
```

Tell the user to import the `.pet` file in Wallive Settings. Do not copy it into Wallive's active runtime folder directly unless the user explicitly asks for a developer-only manual install.

## Repair Workflow

When fixing an existing package:

1. Run `validate_manifest.py`.
2. Check that every state strip exists and has 30 cells.
3. Regenerate only broken strips when identity is otherwise good.
4. Re-run validation before reporting success.

Do not report a package as ready until `pet.json` declares all 11 Wallive states, every referenced strip file exists inside the `.pet` package, and `validate_manifest.py` passes.