create-mascot-pack

Create Mascot Pack

Interactive assistant for creating and modifying pixel-art mascot packs for the claude-code-mascot-statusline plugin.

Workflow Decision

Determine the task type:

Creating a new pack? → Follow "New Pack Workflow" below Modifying an existing pack? → Follow "Existing Pack Workflow" below

New Pack Workflow

Phase 1: Requirements

Ask the user:

1. Character concept (animal, robot, invader, object, etc.)
2. Grid size — recommend 16x16 for half-block, 8x8 for simpler characters
3. Render mode — half-block (recommended for faces/characters) or bg-space (simpler)
4. Pack name (lowercase, hyphens, e.g. space-invader)
5. Install location:
6. Project-local: <project>/.claude/mascot-packs/<name>/
7. User-global: ~/.claude/plugins/claude-code-mascot-statusline/packs/<name>/

Phase 2: Palette Design

Design the color palette. Rules:

• Index 0 = null (transparent) — always required
• Index 1 = outline / dark color — defines the silhouette
• Index 2 = main body color — this is the heat target (shifts toward #ff4444 when context window usage reaches 60-85%). Choose a warm or neutral color that looks good interpolating toward red.
• Index 3+ = accent colors (eyes, mouth, effects, highlights)
• Recommend 5-10 colors total

Read references/pixel-buddy-anatomy.md for palette reference (10-color example).

Phase 3: Idle Sprite Design

The idle frame is the baseline for all other states. Get this right first.

Design approach:

1. Sketch the silhouette first — all non-zero cells form the shape
2. Place outline (index 1) at edges for clear contour
3. Fill body with index 2
4. Add face features: eyes, mouth, ears, etc.
5. Ensure left-right symmetry unless intentionally asymmetric

Critical: Half-block awareness (see "Half-Block Rendering" section below).

Write the frame as a 2D integer array in pack.yaml (preferred) or pack.json.

Phase 4: Validate and Preview

After creating the idle frame, immediately validate and preview:

# Validate pack structure
node dist/cli/validate-pack.js <pack-dir>

# Preview idle state
node dist/cli/preview-pack.js --dir <pack-dir> --state idle --color always

# Check visual metrics
node dist/cli/storybook.js --dir <pack-dir> --states idle --metrics --color always

Review visual lint warnings:

• overall center offset should be near 0 (±0.35 acceptable)
• mirror mismatch should be < 0.18 (unless intentionally asymmetric)
• top/bottom band offsets should be < ±0.5

Iterate with the user until the idle frame looks good.

Phase 5: State Variants

Read references/state-design-guide.md for the full guide on all 10 states.

Start with a minimum viable pack (4 states + fallback):

1. idle — baseline (1-2 frames)
2. thinking — active animation (2-3 frames)
3. tool_success — positive feedback (1 frame)
4. done — completion (1-2 frames)

Set fallbacks.unknown: idle_1 to cover missing states.

For each new state:

1. Copy the idle frame as starting point
2. Modify only what's needed for the expression/animation
3. Run the vertical collision check (see below)
4. Preview with node dist/cli/preview-pack.js --dir <pack-dir> --state <state> --color always

Phase 6: Full Validation

node dist/cli/storybook.js --dir <pack-dir> --color always --metrics

Review every state. Fix visual lint warnings.

Phase 7: Timing and Fallbacks

Set required fallbacks and optional timing in the pack file:

fallbacks:
  unknown: idle_1    # REQUIRED
  narrow: idle_1     # optional
timing:              # optional — defaults are sensible
  idleFramePeriodMs: 500
  thinkingFramePeriodMs: 300

Phase 8: Activate

Tell the user how to activate:

# Environment variable (temporary)
export CLAUDE_MASCOT_PACK=<pack-name>

# Project config (.claude/mascot.json)
{"pack": "<pack-name>"}

# User config (~/.claude/plugins/claude-code-mascot-statusline/config.json)
{"pack": "<pack-name>"}

Existing Pack Workflow

1. Find the pack: search packs/, ~/.claude/plugins/claude-code-mascot-statusline/packs/, .claude/mascot-packs/
2. Read the current pack manifest
3. Show current sprites: node dist/cli/storybook.js --dir <pack-dir> --color always --metrics
4. Make targeted edits to specific frames
5. Re-validate after each change
6. Run storybook for final review

Half-Block Rendering

This is the most critical knowledge for sprite editing. Read this before modifying any half-block pack.

Row Pairing

In half-block mode, consecutive row pairs render as one display line:

Row 0 + Row 1  → Display line 0  (Row 0 = upper ▀, Row 1 = lower ▄)
Row 2 + Row 3  → Display line 1
Row 4 + Row 5  → Display line 2
...

A 16-pixel-tall sprite produces 8 display lines. When editing a pixel, think about which display line it affects.

Cell Rendering

For each column in a row pair (top pixel, bottom pixel):

| Top | Bottom | Output | |-----|--------|--------| | null | null | space | | color | null | ▀ (fg = top color) | | null | color | ▄ (fg = bottom color) | | same | same | █ (fg = that color) | | colorA | colorB | ▀ (fg = top, bg = bottom) |

Vertical Collision Rule

When the same column has dark/outline colors in adjacent row pairs, they create an unwanted continuous vertical line.

Example from pixel-buddy tool_success:

• Row 4, col 4 = outline(1) — closed eye
• Row 6, col 4 = outline(1) — whisker dot
• Display lines 2 and 3 both show dark in col 4 → eyes visually connect to whiskers

Fix: Change one of the colliding cells to body color (index 2) to break the dark continuity.

Verification Procedure

After any sprite edit:

1. For each modified column, list the palette indices vertically
2. Group into row pairs: (0,1), (2,3), (4,5), ...
3. Check: does the same column have outline/dark color in consecutive display lines?
4. If yes → change one cell to body color or another lighter color
5. Preview to confirm: node dist/cli/preview-pack.js --dir <pack-dir> --state <state> --color always

Common Traps

• Closing eyes: Open eyes have white(4) that interrupts dark lines. Closed eyes remove this interruption → check for new vertical collisions at eye columns
• Widening mouth outline: May align with whisker or eye outlines in the same column
• Adding effects at sprite edges: May create unintended dark borders if outline color is used

References

• references/pack-spec-quick.md — Pack spec v2 fields, validation rules, and minimal template
• references/pixel-buddy-anatomy.md — Detailed analysis of pixel-buddy's structure, palette roles, and row layout
• references/state-design-guide.md — All 10 states with design guidelines, effect placement rules, and differentiation checklist

Read packs/pixel-buddy/pack.json in the plugin directory as a full working 16x16 reference.