devlyn-cli 1.9.0 → 1.9.1

package/bin/devlyn.js

@@ -138,6 +138,7 @@ ${g}                v${PKG.version} ${COLORS.dim}· ${k}🍩 by Nocodecat @ Donu
 
 const OPTIONAL_ADDONS = [
   // Local optional skills (copied to .claude/skills/)
+  { name: 'asset-creator', desc: 'AI pixel art game asset pipeline — generate, chroma-key, catalog', type: 'local' },
   { name: 'cloudflare-nextjs-setup', desc: 'Cloudflare Workers + Next.js deployment with OpenNext', type: 'local' },
   { name: 'generate-skill', desc: 'Create well-structured Claude Code skills following Anthropic best practices', type: 'local' },
   { name: 'prompt-engineering', desc: 'Claude 4 prompt optimization using Anthropic best practices', type: 'local' },

package/optional-skills/asset-creator/CATALOG-SCHEMA.md

@@ -0,0 +1,99 @@
+# Asset Catalog Schema
+
+The manifest.json file catalogs all generated assets with metadata that supports both runtime rendering and future marketplace features.
+
+## manifest.json structure
+
+```json
+{
+  "version": "1.0",
+  "style": "gather-town",
+  "generatedWith": "gemini-3-pro-image-preview",
+  "assets": {
+    "furniture/desk-basic": {
+      "file": "furniture/desk-basic.png",
+      "category": "furniture",
+      "width": 765,
+      "height": 746,
+      "anchorX": 0.5,
+      "anchorY": 1.0,
+      "tags": ["workspace", "desk", "monitor"],
+      "theme": "default",
+      "tier": "free",
+      "price": 0,
+      "animation": null
+    },
+    "characters/char-research-sitting": {
+      "file": "characters/char-research-sitting.png",
+      "category": "character",
+      "width": 342,
+      "height": 500,
+      "anchorX": 0.5,
+      "anchorY": 1.0,
+      "tags": ["research", "sitting", "typing"],
+      "theme": "default",
+      "tier": "free",
+      "price": 0,
+      "animation": {
+        "frameWidth": 342,
+        "frameCount": 1,
+        "fps": 0
+      }
+    }
+  }
+}
+```
+
+## Field reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | string | yes | Relative path from asset root |
+| `category` | enum | yes | `tile`, `furniture`, `character`, `pet`, `decoration`, `background` |
+| `width` | number | yes | Pixel width after trim |
+| `height` | number | yes | Pixel height after trim |
+| `anchorX` | number | yes | 0-1, horizontal anchor for positioning (0.5 = center) |
+| `anchorY` | number | yes | 0-1, vertical anchor (1.0 = bottom for isometric depth sort) |
+| `tags` | string[] | yes | Searchable keywords |
+| `theme` | string | yes | Theme pack ID (`"default"`, `"cyberpunk"`, `"nature"`, etc.) |
+| `tier` | enum | yes | `"free"`, `"premium"`, `"exclusive"` |
+| `price` | number | yes | 0 for free, positive integer for paid (currency unit TBD) |
+| `animation` | object\|null | no | Spritesheet info if animated |
+
+## Animation field
+
+For spritesheet assets (multiple frames in one image):
+
+```json
+{
+  "frameWidth": 64,
+  "frameCount": 4,
+  "fps": 8
+}
+```
+
+The renderer reads left-to-right, each frame `frameWidth` pixels wide, cycling at `fps` frames per second.
+
+## Anchor conventions
+
+| Asset type | anchorX | anchorY | Reason |
+|------------|---------|---------|--------|
+| Most assets | 0.5 | 1.0 | Bottom-center — standard for isometric depth sorting |
+| Ceiling items (lights, plants) | 0.5 | 0.0 | Top-center — hangs from above |
+| Wall items (clock, frame) | 0.5 | 0.5 | Center — placed on wall surface |
+| Floor tiles | 0.5 | 0.5 | Center — aligned to grid |
+
+## Theme packs
+
+A theme is a set of assets that share a visual style. The `"default"` theme ships free with the product. Premium themes are sold as packs.
+
+```
+assets/
+├── themes/
+│   ├── default/     → symlinks or copies of base assets
+│   ├── cyberpunk/   → neon-tinted variants
+│   ├── nature/      → wood-and-leaf variants
+│   └── cozy-night/  → warm lamp-lit variants
+```
+
+When a user switches themes, the renderer swaps asset paths: `furniture/desk-basic.png` → `themes/cyberpunk/desk-basic.png`. Assets not overridden by the theme fall back to `default`.

package/optional-skills/asset-creator/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: asset-creator
+description: >
+  Generate consistent pixel art game assets using AI image generation + meta-prompting
+  for style lock + HSL chroma-key background removal. Produces transparent PNGs ready
+  for PixiJS, Phaser, or any 2D game engine. Use when building pixel art games, creating
+  game sprites, generating isometric assets, making character sprites, or when user says
+  "create asset", "generate sprite", "make game art", "pixel art asset", or "에셋 만들어".
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+argument-hint: "[category] [name] \"[description]\" or batch [category] or list or init"
+---
+
+# Asset Creator — AI-Powered Game Asset Pipeline
+
+Generate production-ready pixel art game assets with consistent style, transparent backgrounds, and catalog metadata.
+
+Reference files in this skill directory:
+- `STYLE-GUIDE.md` — Art direction defaults, per-category templates, predefined asset batches
+- `CATALOG-SCHEMA.md` — manifest.json structure and marketplace metadata
+
+## Pipeline overview
+
+```
+0. STYLE LOCK    Meta-prompt one reference asset → extract style DNA (once per project)
+1. GENERATE      Swap [SUBJECT] in meta prompt → Gemini 3.0 Pro Image
+2. BG REMOVE     HSL flood fill (Pillow) — magenta + near-white removal
+3. NORMALIZE     Auto-crop + category-based size normalization
+4. CATALOG       manifest.json auto-registration with marketplace metadata
+```
+
+This pipeline was validated through iterative testing. The meta-prompting approach extracts the "style DNA" from one good asset and replicates it precisely — more consistent than reference images (which the AI may reinterpret) and more token-efficient (264 chars vs 2MB image per call).
+
+## Prerequisites
+
+```bash
+# Python 3 with Pillow — required for HSL background removal
+python3 -c "from PIL import Image; print('OK')"
+
+# API key — required for AI image generation
+grep GEMINI_API_KEY .env
+```
+
+ImageMagick is NOT required — the pipeline uses pure Python (Pillow) for background removal.
+
+## Usage
+
+```
+/asset-creator init                              — Set up project + extract meta prompt from reference
+/asset-creator [category] [name] "[description]"  — Generate one asset
+/asset-creator batch [category]                   — Generate all predefined assets in a category
+/asset-creator list                               — Show current asset inventory
+/asset-creator gallery                            — Generate visual review HTML
+```
+
+## Workflow
+
+### Parse the command
+
+Read `$ARGUMENTS` and determine the mode:
+
+| Input | Mode | Action |
+|---|---|---|
+| `init` | **Init** | Set up directories + extract meta prompt from reference asset |
+| `[category] [name] "[desc]"` | **Single** | Generate one asset |
+| `batch [category]` | **Batch** | Generate all predefined assets for category |
+| `list` | **List** | Show asset inventory from manifest.json |
+| `gallery` | **Gallery** | Generate review HTML |
+| Empty | **Interactive** | Ask what to create |
+
+Valid categories: `tile`, `furniture`, `character`, `pet`, `decoration`, `background`
+
+### Step 0: Style Lock (init mode, or first run)
+
+This is the foundation of style consistency. Run once per project.
+
+**If no meta prompt exists** (`{asset-root}/style-prompt.txt` missing):
+
+1. Check if the project has a reference asset. If not, generate one "hero asset" (a character or prominent furniture piece) using the default style from `STYLE-GUIDE.md`.
+
+2. Send the reference asset to Gemini for meta-prompt extraction:
+
+```python
+# Send image + extraction prompt to Gemini (text model, not image gen)
+prompt = """Look at this pixel art game asset. Reverse-engineer the EXACT image 
+generation prompt that would recreate this STYLE. Replace the specific subject 
+with [SUBJECT]. Capture: pixel density, outline thickness, shading technique, 
+color palette warmth, perspective angle, proportions, and the solid magenta 
+#FF00FF background. Output ONLY the prompt text, max 3 sentences, be precise."""
+```
+
+Use `gemini-2.5-flash` (text model) for extraction — it's fast and cheap. NOT the image model.
+
+3. Save the extracted meta prompt to `{asset-root}/style-prompt.txt`.
+
+4. **Validate**: Generate a test asset using the meta prompt. Show it to the user alongside the reference. If the style matches, the meta prompt is locked. If not, regenerate with adjusted extraction prompt.
+
+**If meta prompt exists**: Read `{asset-root}/style-prompt.txt` and use it for all generation.
+
+### Step 1: Locate project asset directory
+
+Look for existing asset directories in order:
+1. `dashboard/public/assets/office/` (Pyx Org)
+2. `public/assets/game/` (generic game)
+3. `assets/` (fallback)
+
+If none exists, create:
+```
+{asset-root}/
+├── tiles/
+├── furniture/
+├── characters/
+├── pets/
+├── decorations/
+├── backgrounds/
+├── raw/              # AI originals (magenta bg, never delete)
+├── manifest.json
+└── style-prompt.txt  # Meta prompt (style DNA)
+```
+
+### Step 2: Generate the asset
+
+Read the meta prompt from `{asset-root}/style-prompt.txt`.
+
+Construct the final prompt by replacing `[SUBJECT]`:
+```
+{meta_prompt with [SUBJECT] replaced by user's description}
+
+Generate a pixel art IMAGE.
+```
+
+Call Gemini 3.0 Pro Image API (`gemini-3-pro-image-preview`):
+
+```python
+import json, base64, urllib.request
+
+api_key = os.environ.get("GEMINI_API_KEY") or read_from_dotenv()
+
+payload = {
+    "contents": [{"parts": [{"text": full_prompt}]}],
+    "generationConfig": {
+        "responseModalities": ["IMAGE", "TEXT"],
+        "temperature": 0.3
+    }
+}
+
+url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent?key={api_key}"
+req = urllib.request.Request(url, data=json.dumps(payload).encode(),
+                             headers={"Content-Type": "application/json"}, method="POST")
+
+with urllib.request.urlopen(req, timeout=120) as resp:
+    result = json.loads(resp.read().decode())
+
+# Extract image from response
+for part in result["candidates"][0]["content"]["parts"]:
+    if "inlineData" in part:
+        data = base64.b64decode(part["inlineData"]["data"])
+        with open(f"{asset_root}/raw/{name}.jpg", "wb") as f:
+            f.write(data)
+        break
+```
+
+### Step 3: Remove background (HSL flood fill)
+
+This is the optimized approach — uses HSL color space instead of RGB for robust chroma-key removal that handles JPG compression artifacts.
+
+```python
+from PIL import Image
+import colorsys
+from collections import deque
+
+def remove_background(input_path, output_path):
+    img = Image.open(input_path).convert("RGBA")
+    pixels = img.load()
+    w, h = img.size
+
+    def should_remove(r, g, b):
+        rn, gn, bn = r/255.0, g/255.0, b/255.0
+        h_val, l_val, s_val = colorsys.rgb_to_hls(rn, gn, bn)
+        hue_deg = h_val * 360
+        # Magenta hue range (robust against JPG compression)
+        if 250 <= hue_deg <= 340 and s_val > 0.2:
+            return True
+        # Near-white (catches desaturated magenta from JPG artifacts)
+        if r > 230 and g > 230 and b > 230:
+            return True
+        # Very light + low saturation
+        if l_val > 0.9 and s_val < 0.15:
+            return True
+        return False
+
+    # Phase 1: Flood fill from all edges (only removes connected background)
+    visited = set()
+    queue = deque()
+    for x in range(w):
+        queue.append((x, 0)); queue.append((x, h-1))
+    for y in range(h):
+        queue.append((0, y)); queue.append((w-1, y))
+
+    while queue:
+        x, y = queue.popleft()
+        if (x, y) in visited or x < 0 or x >= w or y < 0 or y >= h:
+            continue
+        visited.add((x, y))
+        r, g, b, a = pixels[x, y]
+        if should_remove(r, g, b):
+            pixels[x, y] = (0, 0, 0, 0)
+            for dx, dy in [(-1,0),(1,0),(0,-1),(0,1),(-1,-1),(1,-1),(-1,1),(1,1)]:
+                nx, ny = x+dx, y+dy
+                if 0 <= nx < w and 0 <= ny < h and (nx, ny) not in visited:
+                    queue.append((nx, ny))
+
+    # Phase 2: Edge cleanup (remove remaining pink fringe)
+    for y in range(1, h-1):
+        for x in range(1, w-1):
+            r, g, b, a = pixels[x, y]
+            if a == 0: continue
+            rn, gn, bn = r/255.0, g/255.0, b/255.0
+            h_val, l_val, s_val = colorsys.rgb_to_hls(rn, gn, bn)
+            hue_deg = h_val * 360
+            if (250 <= hue_deg <= 340 and s_val > 0.1) or (l_val > 0.85 and s_val < 0.2):
+                for dx, dy in [(-1,0),(1,0),(0,-1),(0,1)]:
+                    if pixels[x+dx, y+dy][3] == 0:
+                        pixels[x, y] = (0, 0, 0, 0)
+                        break
+
+    # Auto-crop to content
+    bbox = img.getbbox()
+    if bbox:
+        img = img.crop(bbox)
+    img.save(output_path)
+    return img.size
+```
+
+Why HSL instead of RGB:
+- JPG compression shifts RGB values but barely affects Hue
+- Magenta has a distinctive hue (~300°) that's stable across compression levels
+- Saturation check prevents false positives on gray/white pixels
+- Flood fill from edges ensures interior light pixels are preserved
+
+### Step 4: Register in manifest
+
+Read `{asset-root}/manifest.json`. Get dimensions from the processed PNG. Add entry:
+
+```json
+{
+  "{category}/{name}": {
+    "file": "{category}/{name}.png",
+    "category": "{category}",
+    "width": W,
+    "height": H,
+    "anchorX": 0.5,
+    "anchorY": 1.0,
+    "tags": ["inferred", "from", "description"],
+    "theme": "default",
+    "tier": "free",
+    "price": 0
+  }
+}
+```
+
+See `CATALOG-SCHEMA.md` for full field reference and anchor conventions.
+
+### Step 5: Show result
+
+Display the generated PNG using the Read tool. Report:
+- File path and size
+- Dimensions (W × H)
+- Category, tags, tier
+- Manifest status
+
+If unsatisfied, offer to regenerate with an adjusted subject description.
+
+## Batch Mode
+
+Read predefined asset lists from `STYLE-GUIDE.md`. Generate each sequentially with 1.5s delay (rate limiting). Show progress. Generate gallery at end.
+
+## List Mode
+
+Read manifest.json, group by category, display inventory table with dimensions, tier, and file size.
+
+## Gallery Mode
+
+Generate `{asset-root}/gallery.html` showing all assets on checkered transparency background, grouped by category. Suggest `python3 -m http.server 8888` to view.
+
+## Adapting to other AI generators
+
+The pipeline is model-agnostic. To swap generators:
+1. Replace the API call in Step 2
+2. Keep the meta prompt + magenta background instruction
+3. HSL background removal works identically regardless of source
+4. If your model outputs PNG with native transparency, skip Step 3

package/optional-skills/asset-creator/STYLE-GUIDE.md

@@ -0,0 +1,174 @@
+# Asset Creator — Style Guide
+
+This document defines the art direction defaults and per-category templates. In production, the meta prompt (extracted from a reference asset) overrides the default style prefix.
+
+## Style System: Meta Prompting
+
+The best way to ensure style consistency is **meta prompting** — extracting the "style DNA" from one good reference asset, then using that exact prompt for all subsequent generations with only the `[SUBJECT]` swapped.
+
+### How it works
+
+1. Generate or find one "hero asset" that nails the visual style you want
+2. Send it to Gemini text model to reverse-engineer the prompt
+3. Save the extracted prompt as `style-prompt.txt` in the asset root
+4. Every subsequent generation uses this prompt, replacing `[SUBJECT]` only
+
+### Why meta prompting beats alternatives
+
+| Approach | Consistency | Token cost | Reliability |
+|---|---|---|---|
+| Fixed text prefix (old approach) | Medium — AI interprets loosely | Low | Medium |
+| Reference image every call | High — but AI may reinterpret | Very High (~2MB/call) | Medium |
+| **Meta prompt (current)** | **High — exact reproduction** | **Low (264 chars)** | **High** |
+| Fine-tuned model (Scenario.gg) | Highest | Setup cost | Highest |
+
+### Default style prefix (fallback)
+
+If no `style-prompt.txt` exists yet (first run / init), use this as the initial generation prompt:
+
+```
+Gather Town / Habbo Hotel style pixel art game asset, isometric 3/4 view, bright cheerful warm colors, clean pixel outlines, highly detailed pixel art
+```
+
+Then extract the meta prompt from the first successful generation.
+
+## Background Instruction (always appended)
+
+Regardless of meta prompt, ALWAYS append this to every generation prompt:
+
+```
+on a solid bright magenta #FF00FF background. The ENTIRE background must be exactly #FF00FF magenta, with NO gradients or shadows on the background. ONLY the single isolated object, nothing else in the scene.
+```
+
+This is required by the HSL chroma-key removal pipeline. Magenta (#FF00FF) is the game industry standard chroma-key color — it never appears in natural pixel art palettes.
+
+## Perspective
+
+- **Angle**: Isometric ¾ top-down view (~30° from horizontal)
+- **Camera**: Looking from bottom-left toward top-right
+- **Shadow direction**: Bottom-right, short and crisp
+- **Light source**: Top-left (consistent with shadow direction)
+
+## Proportions (relative to character height)
+
+| Element | Relative size | Notes |
+|---|---|---|
+| Character (standing) | 1.0x | Reference unit |
+| Character (sitting) | 0.7x | At desk |
+| Desk | 0.5x height, 1.2x width | With monitor, wider than tall |
+| Chair | 0.4x | Office swivel chair |
+| Bookshelf | 1.2x | Taller than character |
+| Door | 1.5x | Tallest common furniture |
+| Floor plant | 0.8-1.0x | Varies by type |
+| Desk plant | 0.2x | Small succulent/cactus |
+| Wall decoration | 0.3-0.5x | Clock, picture frame |
+| Bean bag | 0.4x height, 0.8x width | Wide and low |
+| Kit (pet) | 0.5x | Smaller than character |
+
+## Color palette guidelines
+
+- **Warm base**: Browns, beiges, warm grays for furniture and floors
+- **Department accents**: Orange (Research), Green (Engineering), Blue (Growth), Purple (Ops)
+- **Skin tones**: Varied, warm undertones
+- **Outlines**: Dark brown or black, 1-2px, clean and consistent
+- **Highlights**: Top-left facing surfaces lighter
+- **Shadows**: Bottom-right facing surfaces darker, 2-3 tone steps
+
+## Per-category prompt templates
+
+### tile
+```
+{STYLE_PREFIX}. A single isometric {description} tile, 64x64 pixel grid aligned, seamlessly tileable. {BG_SUFFIX}
+```
+
+### furniture
+```
+{STYLE_PREFIX}. A single {description}. Isometric perspective, detailed with visible texture and shading. {BG_SUFFIX}
+```
+
+### character
+```
+{STYLE_PREFIX}. A single cute office worker character, {description}. Gather Town style proportions: blocky square head wider than body, dot eyes with white highlight, small body. {BG_SUFFIX}
+```
+
+### pet
+```
+{STYLE_PREFIX}. A single small cute {description}. Expressive face, big eyes, stubby limbs. Game mascot style. {BG_SUFFIX}
+```
+
+### decoration
+```
+{STYLE_PREFIX}. A single {description}. Small decorative object, detailed pixel art. {BG_SUFFIX}
+```
+
+### background
+```
+{STYLE_PREFIX}. A wide panoramic {description}. Suitable as a background layer, horizontally tileable or wide format. {BG_SUFFIX}
+```
+
+## Predefined asset batches
+
+### tile
+| name | description |
+|------|-------------|
+| floor-wood | wooden floor tile with warm wood grain texture |
+| floor-carpet-orange | orange carpet tile for Research department |
+| floor-carpet-green | green carpet tile for Engineering department |
+| floor-carpet-blue | blue carpet tile for Growth department |
+| floor-carpet-purple | purple carpet tile for Ops department |
+| wall-back | cream/beige back wall section |
+| wall-side | slightly darker side wall section |
+
+### furniture
+| name | description |
+|------|-------------|
+| desk-basic | wooden office desk with computer monitor, keyboard, mouse, and coffee mug |
+| desk-standing | modern standing desk with large monitor and adjustable height |
+| chair-office | dark office swivel chair with armrests |
+| bookshelf | tall wooden bookshelf packed with colorful books, small plant on top |
+| whiteboard | office whiteboard covered in colorful sticky notes, marker tray at bottom |
+| beanbag-green | large green bean bag chair, puffy and round |
+| beanbag-orange | large orange bean bag chair, puffy and round |
+| beanbag-purple | large purple bean bag chair, puffy and round |
+| coffee-station | espresso machine on wooden counter with white mug underneath |
+| water-cooler | water cooler dispenser with blue water jug on top |
+| meeting-table | round meeting table with 4 small chairs |
+| sofa | comfortable modern office couch |
+
+### character
+| name | description |
+|------|-------------|
+| char-research-sitting | in orange shirt, brown hair, sitting and typing on laptop |
+| char-research-standing | in orange shirt, brown hair, standing casually |
+| char-engineering-sitting | in green shirt, black hair, sitting and typing on laptop |
+| char-engineering-standing | in green shirt, black hair, standing casually |
+| char-growth-sitting | in blue shirt, blonde hair, sitting and typing on laptop |
+| char-growth-standing | in blue shirt, blonde hair, standing casually |
+| char-ops-sitting | in purple shirt, red ponytail, sitting and typing on laptop |
+| char-ops-standing | in purple shirt, red ponytail, standing casually |
+
+### pet
+| name | description |
+|------|-------------|
+| kit-idle | golden yellow cat creature mascot, happy expression, standing still |
+| kit-bounce-1 | golden yellow cat creature mascot, jumping up with arms raised |
+| kit-bounce-2 | golden yellow cat creature mascot, at peak of jump |
+| kit-blink | golden yellow cat creature mascot, eyes closed, smiling |
+
+### decoration
+| name | description |
+|------|-------------|
+| plant-hanging | hanging potted plant with green vines draping from terracotta pot on chain |
+| plant-floor-large | tall floor potted plant with large green leaves in brown pot |
+| plant-desk | small succulent in tiny pot for desk |
+| clock-wall | round wall clock with simple markers |
+| picture-frame | framed picture/certificate for wall |
+| pendant-light | hanging ceiling pendant light with warm glow |
+| window-large | large floor-to-ceiling window panel |
+| bulletin-board | cork board with pinned papers and photos |
+
+### background
+| name | description |
+|------|-------------|
+| skyline-day | city skyline with buildings, blue sky, white clouds, wide panorama |
+| skyline-night | nighttime city skyline with lit windows, dark blue sky, wide panorama |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "AI development toolkit for Claude Code — ideate, auto-resolve, and ship with context engineering and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {