pi-sprite 1.0.0

package/skills/pi-sprite-authoring/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: pi-sprite-authoring
+description: Create custom pi-sprite pets from AI-generated, reference-driven, or hand-drawn sprites. Use when making Wumpus or Petdex-inspired sprites, preparing pet.json manifests, generating GPT Image prompts or images, converting outputs into /pet import folders, or dogfooding custom pi-sprite pets.
+---
+
+# Pi Sprite Authoring
+
+Create importable `pi-sprite` pet folders from generated, reference-driven, or hand-drawn sprites.
+
+## Default workflow
+
+1. Prefer the expanded five-image format for first-time authoring:
+   `idle.png`, `thinking.png`, `working.png`, `success.png`, `error.png`, and `pet.json`.
+2. Gather the character brief and any local reference images before generating. Ask for user choice when the character direction is still open.
+3. If the user mentions Boba, Petdex, Sprite Mart, or another existing pet as inspiration, read `references/petdex-reference-to-custom-pet.md`.
+4. If the user wants GPT/OpenAI image generation or copy-paste image prompts, read `references/gpt-image-sprite-workflow.md`.
+5. If the user wants Wumpus-specific mascot prompts, read `references/wumpus-sprite-prompts.md`.
+6. Bind each reference image to an explicit role and instruction. Use references for style, scale, outline, palette, or mood; do not copy unclear-license third-party character identity.
+7. Present 3-5 direction cards before locking the character, unless the user already supplied a precise design.
+8. After the user chooses a direction, write a stable character lock and generate or select a canonical `idle` anchor before making the remaining states.
+9. Use the canonical anchor as the primary `character_reference` for `thinking`, `working`, `success`, and `error`; use Petdex or other third-party references only as secondary style/scale references.
+10. Run a character-cohesion review against the canonical anchor before packaging. Regenerate states with major drift. Read `references/character-cohesion-review.md` when a reusable review prompt would help.
+11. If generated outputs lack alpha, run local background cleanup before packaging; keep the original generated files and metadata.
+12. Ask whether the user wants an animated version. If yes, create subtle per-state frame strips and add `frame.width`/`frame.height` to `pet.json`.
+13. Ask whether the user wants optional pet personality metadata. If yes, add one short bounded `personality` sentence to `pet.json`; if no, omit it.
+14. Create a pet folder containing `pet.json` plus accepted image files or strips.
+15. Import with a single slash command, `/pet import <folder>`, then run follow-up commands separately: `/pet clear-native`, `/pet show`, `/pet size small`, and `/pet label off`.
+
+## Direction-card format
+
+Use this format before image generation when the user is still choosing a character direction:
+
+```markdown
+## Direction options
+
+1. **Short name**
+   - Character: concrete subject and silhouette
+   - Mood: emotional target
+   - Visual lock: palette, outline, scale, one or two immutable traits
+   - Why it fits: why this works as a terminal pet
+   - Risk: what may become generic or hard to read
+```
+
+Ask the user to pick one direction, combine directions, or revise the brief. Do not silently pick a final design unless the user asks for speed/autonomy.
+
+## Create a starter pet folder
+
+Run from the pi-sprite repo or installed package root:
+
+```bash
+node skills/pi-sprite-authoring/scripts/create-pet-template.mjs \
+  --id wumpus \
+  --name Wumpus \
+  --out /tmp/wumpus-sprite
+```
+
+Add generated images to the output folder as:
+
+```text
+idle.png
+thinking.png
+working.png
+success.png
+error.png
+```
+
+Then import. Run each slash command separately; do not paste the import plus follow-up commands as one multi-line command.
+
+```text
+/pet import /tmp/wumpus-sprite
+/pet choose wumpus
+/pet show
+```
+
+## Optional personality pass
+
+Personality metadata is optional. Ask after the user accepts the visual sprite set and before finalizing `pet.json`:
+
+```text
+Do you want this pet to have a short personality for explicit /btw side conversations, or should it stay visual-only?
+```
+
+If the user says yes, write one short bounded style sentence. Keep it under about 120 characters when possible and never longer than `pet.json`'s 2000-character limit. It should guide tone and concise response style only, not add operational instructions, autonomy, status behavior, main-thread commentary, or roleplay obligations.
+
+Good examples:
+
+```text
+Warm, concise, lightly mischievous, and practical. Keep BTW answers short.
+Sweet, loyal, curious, and a little goofy. Keep BTW answers short and grounded.
+```
+
+For Wendy, a good first pass would be:
+
+```json
+"personality": "Sweet, loyal, curious, and a little goofy. Keep BTW answers short and grounded."
+```
+
+Do not invent personality when the user only wants a visual pet. Do not make the personality longer than the manifest description. The personality is not injected into normal main-agent turns; it only guides explicit BTW side replies such as `/btw`, `/btw:ask`, and `/btw:new <message>`.
+
+To create a starter folder with personality already in the manifest, pass `--personality`:
+
+```bash
+node skills/pi-sprite-authoring/scripts/create-pet-template.mjs \
+  --id wendybot3000 \
+  --name WendyBot3000 \
+  --personality "Sweet, loyal, curious, and a little goofy. Keep BTW answers short and grounded." \
+  --out /tmp/wendybot3000-sprite
+```
+
+## Canonical anchor gate
+
+For generated pets, avoid generating all five states independently. First generate or choose a canonical `idle` image. Treat it as the ground-truth identity for the pet.
+
+Use this acceptance gate before final packaging:
+
+```markdown
+## Character cohesion review
+
+Canonical anchor: path/to/idle.png
+
+| State | Identity | Silhouette | Face | Ears/props | Palette/outline | State readability | Verdict |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| thinking | same/minor drift/major drift | ... | ... | ... | ... | clear/unclear | accept/regenerate |
+```
+
+Regenerate any state with major drift in identity, silhouette, face, signature props, palette, or outline thickness. Pose and expression should change; the character design should not. For a reusable human/vision-model review prompt, use `references/character-cohesion-review.md`.
+
+## Optional animation pass
+
+After the static five-state pet works, ask whether the user wants an animated version. Offer two levels:
+
+1. **Simple motion** — no image API needed. Reuse one accepted image per state and create subtle bob/shift strips. This is safest for character consistency.
+2. **Expressive keyframes** — generate or draw per-frame differences, such as eye shifts, head tilts, prop twinkles, or sprite-specific details. This is higher quality but must pass the cohesion review because identity drift is easier.
+
+Keep animation subtle; terminal pets read best when the character identity stays fixed and only a few pixels, the whole body, or one sprite-specific feature changes. Do not blindly use feature examples like leaf bob or tail wag unless that character actually has the feature.
+
+Recommended frame counts:
+
+```text
+idle:      4 frames — blink, breathing, or leaf/ear bob
+thinking:  4 frames — slight head tilt or eye shift
+working:   6 frames — paw/key tap loop
+success:   5 frames — bounce or sparkle twinkle
+error:     4 frames — worried blink or small droop
+```
+
+`pi-sprite` supports per-state horizontal strips when `pet.json` includes a frame size:
+
+```json
+{
+  "sprites": {
+    "idle": "idle-strip.png",
+    "thinking": "thinking-strip.png",
+    "working": "working-strip.png",
+    "success": "success-strip.png",
+    "error": "error-strip.png"
+  },
+  "frame": { "width": 128, "height": 128 }
+}
+```
+
+For simple motion, create a strip from one accepted state image:
+
+```bash
+uv run --with pillow python skills/pi-sprite-authoring/scripts/create_motion_strip.py \
+  --input /tmp/wumpus/clean/thinking.png \
+  --output /tmp/wumpus/pet/thinking-strip.png \
+  --metadata /tmp/wumpus/pet/thinking-strip.metadata.json \
+  --preset thinking-bob \
+  --frame-width 128 \
+  --frame-height 128
+```
+
+Useful simple presets:
+
+```text
+bob
+thinking-bob
+working-tap
+success-bounce
+error-droop
+```
+
+For expressive keyframes, generate or draw cleaned frames first, then assemble them into a strip:
+
+```bash
+uv run --with pillow python skills/pi-sprite-authoring/scripts/assemble_sprite_strip.py \
+  --frame /tmp/wumpus/frames/idle-0.png \
+  --frame /tmp/wumpus/frames/idle-1.png \
+  --frame /tmp/wumpus/frames/idle-2.png \
+  --frame /tmp/wumpus/frames/idle-3.png \
+  --output /tmp/wumpus/pet/idle-strip.png \
+  --metadata /tmp/wumpus/pet/idle-strip.metadata.json \
+  --frame-width 128 \
+  --frame-height 128
+```
+
+## Background cleanup
+
+If the image model returns a non-alpha PNG, use the local cleanup helper before packaging. It removes only edge-connected background pixels, which is safer than deleting every near-white pixel inside the sprite.
+
+```bash
+uv run --with pillow python skills/pi-sprite-authoring/scripts/remove_sprite_background.py \
+  --input /tmp/boba-sprite/generated/thinking.png \
+  --output /tmp/boba-sprite/clean/thinking.png \
+  --metadata /tmp/boba-sprite/clean/thinking.metadata.json \
+  --target-size 128 \
+  --padding 10
+```
+
+Use the cleaned images in the importable pet folder, but keep original generation outputs, prompts, and metadata for provenance.
+
+## Optional OpenAI image generation
+
+Use prompt-only mode when no image API is available. When `OPENAI_API_KEY` is available and the user approves API calls, use the bundled helper:
+
+```bash
+uv run --with openai python skills/pi-sprite-authoring/scripts/openai_sprite_image.py \
+  --prompt-file /tmp/boba-sprite/prompts/idle.txt \
+  --reference-image /tmp/boba-ref.png \
+  --reference-instruction "Use for pixel-art scale, outline thickness, and terminal readability only. Do not copy character identity." \
+  --output-dir /tmp/boba-sprite/generated \
+  --prefix idle
+```
+
+Use `--dry-run` first to validate prompt/reference wiring without making API calls:
+
+```bash
+uv run --with openai python skills/pi-sprite-authoring/scripts/openai_sprite_image.py \
+  --dry-run \
+  --prompt "Create a tiny transparent pixel-art idle sprite." \
+  --reference-image /tmp/boba-ref.png \
+  --reference-instruction "Use for silhouette scale only; do not copy identity." \
+  --output-dir /tmp/boba-sprite/generated \
+  --prefix idle
+```
+
+## Use reference sprites safely
+
+Do not commit copyrighted or unclear-license third-party sprite assets to the repo. For temporary visual references, run:
+
+```bash
+node skills/pi-sprite-authoring/scripts/download-petdex-examples.mjs --limit 12 --out examples/petdex-downloads
+```
+
+Use downloaded examples only as local reference unless the asset license is verified. The script writes provenance notes next to the downloads.
+
+## Output requirements
+
+For generated Wumpus or custom sprites, produce:
+
+```text
+custom-sprite/
+├── pet.json
+├── idle.png
+├── thinking.png
+├── working.png
+├── success.png
+└── error.png
+```
+
+Keep contact sheets, raw generations, prompts, and metadata next to the working directory, not inside the final import folder unless you intentionally want those files copied into the installed pet.
+
+```text
+working-dir/
+├── anchor/
+├── generated/
+├── prompts/
+├── clean/
+├── contact-sheet.png
+└── custom-sprite/
+    ├── pet.json
+    ├── idle.png
+    ├── thinking.png
+    ├── working.png
+    ├── success.png
+    └── error.png
+```
+
+For animated pets, use strips and record the frame size:
+
+```text
+custom-sprite/
+├── pet.json
+├── idle-strip.png
+├── thinking-strip.png
+├── working-strip.png
+├── success-strip.png
+└── error-strip.png
+```
+
+Use this manifest shape:
+
+```json
+{
+  "id": "wumpus",
+  "name": "Wumpus",
+  "author": "Alex",
+  "description": "A tiny Wumpus companion for pi-sprite.",
+  "personality": "Warm, concise, lightly mischievous, and practical. Keep BTW answers short.",
+  "sprites": {
+    "idle": "idle.png",
+    "thinking": "thinking.png",
+    "working": "working.png",
+    "success": "success.png",
+    "error": "error.png"
+  }
+}
+```
+
+## Quality checklist
+
+- Keep the character readable at `small` size.
+- Use transparent backgrounds, or run local background cleanup when the model returns non-alpha images.
+- Keep each state visually consistent: same pose scale, outline, palette, and canvas size.
+- Avoid text, shadows, busy props, and tiny facial details.
+- Add optional `personality` only when the pet should speak with a bounded voice in explicit `/btw` side conversations.
+- Record prompt files and reference instructions next to generated assets.
+- For animated strips, keep frame size consistent and verify `pet.json` has `frame.width` and `frame.height`.
+- Test in native and ANSI fallback modes when possible:
+
+```text
+/pet size small
+/pet label off
+/pet show
+```
+
+```bash
+PI_SPRITE_NATIVE_IMAGES=0 pi -e . -p "/pet show" --no-session
+```

package/skills/pi-sprite-authoring/assets/wumpus-template/pet.json

@@ -0,0 +1,14 @@
+{
+	"id": "wumpus",
+	"name": "Wumpus",
+	"author": "Alex",
+	"description": "A tiny Wumpus companion for pi-sprite.",
+	"personality": "Warm, concise, lightly mischievous, and practical. Keep BTW answers short.",
+	"sprites": {
+		"idle": "idle.png",
+		"thinking": "thinking.png",
+		"working": "working.png",
+		"success": "success.png",
+		"error": "error.png"
+	}
+}

package/skills/pi-sprite-authoring/references/character-cohesion-review.md

@@ -0,0 +1,65 @@
+# Character cohesion review
+
+Use this after generating a canonical anchor and the remaining sprite states. The goal is to catch when image generation creates five related variants instead of one character in five states.
+
+## Inputs
+
+- `anchor/canonical-idle.png` — the ground-truth character identity.
+- Candidate state images: `thinking.png`, `working.png`, `success.png`, `error.png`.
+- Optional style reference images, used only to understand intended palette, outline, and scale.
+
+## Review prompt
+
+Use this prompt with a human reviewer or a vision-capable model. Do not ask the reviewer to judge whether the art is generally cute until identity preservation is checked.
+
+```text
+You are reviewing a custom pi-sprite pet for character consistency.
+
+The first image is the canonical character anchor. Treat it as ground truth.
+The remaining images are state candidates for thinking, working, success, and error.
+
+Judge whether each state preserves the same character identity. Pose and expression may change. The character design should not change.
+
+Check these invariants:
+- overall silhouette and body proportions
+- head/body shape
+- face shape and eye style
+- signature ears, props, straw, horns, tail, clothes, or other defining features
+- palette and relative color placement
+- outline thickness and pixel-art style
+- canvas scale, baseline, and padding
+
+Return a markdown table with these columns:
+State | Identity | Silhouette | Face | Signature traits | Palette/outline | Scale/baseline | State readability | Verdict | Regeneration notes
+
+Use only these verdicts:
+- accept
+- regenerate-minor
+- regenerate-major
+
+If verdict is regenerate-minor or regenerate-major, give concrete regeneration notes that say what must be preserved from the anchor and what pose/expression should change.
+```
+
+## Manual rubric
+
+| Rating | Meaning | Action |
+| --- | --- | --- |
+| same | Clearly the same character in a new pose. | Accept if state reads clearly. |
+| minor drift | Mostly same character, but one trait moved or softened. | Accept for rough dogfood, or regenerate for final asset. |
+| major drift | Reads as a sibling/variant/new character. | Regenerate. |
+
+Reject on any major drift in identity, silhouette, face, signature traits, palette, or outline. A state can be readable and still fail if it reads as a different character.
+
+## Regeneration prompt pattern
+
+```text
+Regenerate the STATE image using the canonical anchor as the first reference.
+Preserve exact character identity from the anchor: [specific silhouette, face, props, palette, outline, scale].
+The previous attempt drifted because [specific issue].
+Change only [pose/expression/state cue].
+Do not redesign the character, change proportions, move signature props, or introduce a new variant.
+```
+
+## Packaging gate
+
+Only package/import states that pass the cohesion review or are explicitly accepted by the user for rough dogfood. Record the review notes next to the generated assets so future iterations know which traits are locked.

package/skills/pi-sprite-authoring/references/gpt-image-sprite-workflow.md

@@ -0,0 +1,181 @@
+# GPT Image Sprite Workflow
+
+Use this workflow when generating `pi-sprite` pet images with ChatGPT, GPT Image, or the bundled OpenAI helper.
+
+## Contents
+
+- First choice: five separate images
+- Prompt structure
+- Canonical anchor workflow
+- Five-state prompt set
+- OpenAI helper
+- Iteration prompts
+- Final packaging
+
+## First choice: five separate images
+
+For first-time authoring, generate five separate transparent PNGs instead of a spritesheet:
+
+```text
+idle.png
+thinking.png
+working.png
+success.png
+error.png
+```
+
+Spritesheets are useful later, but five files are easier to inspect, rename, regenerate, and import.
+
+## Prompt structure
+
+Use a character lock plus a state-specific delta.
+
+```text
+Create one transparent PNG pixel-art sprite for a terminal companion.
+
+CANONICAL CHARACTER:
+[stable character lock]
+
+STATE:
+[idle/thinking/working/success/error plus pose]
+
+STYLE AND CANVAS:
+- 128x128 square transparent canvas
+- centered with consistent feet/baseline and 6-10px padding
+- crisp pixel-art look, bold dark outline, limited palette
+- readable at small terminal size
+- no text, letters, logo, watermark, background, drop shadow, or busy props
+
+REFERENCE IMAGES:
+[explicit role/instruction for each reference]
+```
+
+## Canonical anchor workflow
+
+For better character consistency, use a ground-truth anchor image:
+
+1. Generate 3-6 `idle` candidates from the character lock and style references.
+2. Ask the user to pick the canonical anchor.
+3. Save it as `anchor/canonical-idle.png`.
+4. Generate `thinking`, `working`, `success`, and `error` with `anchor/canonical-idle.png` as the first reference and role `character_reference`.
+5. Keep Petdex or other third-party images as secondary `style_reference` or `scale_reference` only.
+6. Run the character-cohesion review before packaging. Use `character-cohesion-review.md` when you need a reusable review prompt.
+7. If accepted images lack alpha, run local background cleanup before importing.
+
+State prompts should say:
+
+```text
+Use the first attached image as the canonical character identity. Preserve the exact body shape, ear/pearl shapes, straw angle, face style, palette, outline thickness, proportions, canvas scale, and baseline. Change only the pose and expression needed for this state. Do not redesign the character or create a new variant.
+```
+
+## Five-state prompt set
+
+After the user chooses a direction and canonical anchor, create one prompt file per state:
+
+```text
+prompts/idle.txt
+prompts/thinking.txt
+prompts/working.txt
+prompts/success.txt
+prompts/error.txt
+```
+
+Use these state deltas:
+
+- `idle`: relaxed neutral pose, calm expression.
+- `thinking`: curious head tilt, small pondering gesture, no question-mark text.
+- `working`: focused and active, maybe typing on one large simple prop.
+- `success`: celebratory pose, sparkle-like body language but no text.
+- `error`: confused or worried expression, still friendly and readable.
+
+Keep all other character details identical.
+
+## OpenAI helper
+
+Dry-run first:
+
+```bash
+uv run --with openai python skills/pi-sprite-authoring/scripts/openai_sprite_image.py \
+  --dry-run \
+  --prompt-file /tmp/boba-sprite/prompts/idle.txt \
+  --reference-image /tmp/boba-ref.png \
+  --reference-instruction "Use for compact pixel-art scale and outline only; do not copy character identity." \
+  --output-dir /tmp/boba-sprite/generated \
+  --prefix idle
+```
+
+Generate when the user approves API calls and `OPENAI_API_KEY` is set:
+
+```bash
+uv run --with openai python skills/pi-sprite-authoring/scripts/openai_sprite_image.py \
+  --prompt-file /tmp/boba-sprite/prompts/idle.txt \
+  --reference-image /tmp/boba-ref.png \
+  --reference-instruction "Use for compact pixel-art scale and outline only; do not copy character identity." \
+  --output-dir /tmp/boba-sprite/generated \
+  --prefix idle
+```
+
+The helper uses image generation when no references are supplied and image edit when references are supplied. It appends reference roles/instructions to the effective prompt sent to OpenAI, so the model can distinguish the canonical `character_reference` from style/scale references. It defaults to `--background auto` because some current GPT Image models reject transparent-background requests; pass `--background transparent` only with a model that supports it. The helper writes output images, prompt copies, and metadata, and records the background setting.
+
+For anchor-based generation with multiple references, pass each reference with its own role and instruction in order:
+
+```bash
+uv run --with openai python skills/pi-sprite-authoring/scripts/openai_sprite_image.py \
+  --prompt-file /tmp/boba-sprite/prompts/thinking.txt \
+  --reference-image /tmp/boba-sprite/anchor/canonical-idle.png \
+  --reference-role character_reference \
+  --reference-instruction "Preserve exact character identity; only change pose and expression." \
+  --reference-image /tmp/boba-sprite/refs/boba-spritesheet.png \
+  --reference-role style_reference \
+  --reference-instruction "Use only for pixel-art scale and outline thickness; do not copy identity." \
+  --output-dir /tmp/boba-sprite/generated \
+  --prefix thinking
+```
+
+## Background cleanup
+
+If the accepted image lacks alpha, clean it locally before packaging:
+
+```bash
+uv run --with pillow python skills/pi-sprite-authoring/scripts/remove_sprite_background.py \
+  --input /tmp/boba-sprite/generated/thinking.png \
+  --output /tmp/boba-sprite/clean/thinking.png \
+  --metadata /tmp/boba-sprite/clean/thinking.metadata.json \
+  --target-size 128 \
+  --padding 10
+```
+
+The cleanup helper removes edge-connected background colors sampled from image edges, then places the sprite onto a square transparent canvas. Check the result in Preview or via `/pet import`; adjust `--threshold`, `--background-color`, or `--padding` if it removes too much or too little.
+
+## Iteration prompts
+
+After inspecting output, iterate with delta prompts instead of restarting.
+
+```text
+Keep: [specific successful silhouette/palette/expression].
+Change: [specific pose or readability issue].
+Remove: [text, background, extra props, over-detail, copied identity].
+Preserve: same character lock, 128x128 transparent canvas, bold pixel outline, same palette.
+```
+
+Common fixes:
+
+- Too detailed: "Simplify to one large readable silhouette; remove tiny decorative details."
+- Background not transparent: "Transparent background only; no floor, shadow, frame, or scene." If the current model rejects `--background transparent`, regenerate with a compatible model or remove the background in a separate image-editing step before final packaging.
+- Character drift: "Preserve the canonical character lock exactly; only change the pose/expression."
+- Looks copied from reference: "Make this an original character; keep only pixel-art density and readability from the reference."
+- Too large/small: "Center on 128x128 with 8px transparent padding and consistent feet baseline."
+
+## Final packaging
+
+Select the best output for each state and copy/rename into the pet folder:
+
+```text
+pet/idle.png
+pet/thinking.png
+pet/working.png
+pet/success.png
+pet/error.png
+```
+
+Keep generated prompt and metadata files in a separate dogfood workspace for provenance. Do not commit generated third-party-reference-derived assets unless licenses and provenance are acceptable.