devlyn-cli 1.8.1 → 1.9.1

package/CLAUDE.md

@@ -56,13 +56,17 @@ For hands-free build-evaluate-polish cycles — works for bugs, features, refact
 /devlyn:auto-resolve [task description]
 ```
 
-This runs the full pipeline automatically: **Build → Browser Validate → Evaluate → Fix Loop → Simplify → Review → Security Review → Clean → Docs**. Each phase runs as a separate subagent with its own context. Communication between phases happens via files (`.devlyn/done-criteria.md`, `.devlyn/EVAL-FINDINGS.md`, `.devlyn/BROWSER-RESULTS.md`).
+This runs the full pipeline automatically: **Build → Build Gate → Browser Validate → Evaluate → Fix Loop → Simplify → Review → Security Review → Clean → Docs**. Each phase runs as a separate subagent with its own context. Communication between phases happens via files (`.devlyn/done-criteria.md`, `.devlyn/BUILD-GATE.md`, `.devlyn/EVAL-FINDINGS.md`, `.devlyn/BROWSER-RESULTS.md`).
+
+The **Build Gate** (Phase 1.4) runs real compilers, typecheckers, and linters — the same commands CI/Docker/production will run. It auto-detects project types (Next.js, Rust, Go, Solidity, Expo, Swift, etc.) and Dockerfiles. This is the primary defense against "tests pass locally, breaks in CI/Docker" class of bugs (type errors in un-tested files, cross-package drift, Dockerfile copy mismatches).
 
 For web projects, the Browser Validate phase starts the dev server and tests the implemented feature in a real browser — clicking buttons, filling forms, verifying results. If the feature doesn't work, findings feed back into the fix loop.
 
 Optional flags:
 - `--max-rounds 6` — increase max evaluate-fix iterations (default: 4)
 - `--skip-browser` — skip browser validation phase (auto-skipped for non-web changes)
+- `--skip-build-gate` — skip the deterministic build gate (not recommended)
+- `--build-gate strict` — treat warnings as errors; `--build-gate no-docker` — skip Docker builds for speed
 - `--skip-review` — skip team-review phase
 - `--skip-clean` — skip clean phase
 - `--skip-docs` — skip update-docs phase
@@ -76,7 +80,7 @@ After completing a roadmap (or a phase), verify that everything was actually imp
 /devlyn:preflight
 ```
 
-This reads every commitment from VISION.md, ROADMAP.md, and item specs, then audits the codebase evidence-based. Finds: missing features, incomplete implementations, spec divergence, bugs, stale documentation. Also checks in the browser for web projects.
+This reads every commitment from VISION.md, ROADMAP.md, and item specs, then audits the codebase evidence-based. The code auditor now runs real build/typecheck commands as its first step — any project that doesn't compile is flagged as BROKEN at CRITICAL severity before individual commitments are even checked. Also checks in the browser for web projects.
 
 Output: `.devlyn/PREFLIGHT-REPORT.md` with categorized findings (MISSING, INCOMPLETE, DIVERGENT, BROKEN, STALE_DOC). Confirmed gaps can be promoted to new roadmap items for auto-resolve.
 

package/README.md

@@ -65,18 +65,20 @@ Point it at a spec (or just describe what you want) and walk away.
 /devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-1/1.1-user-auth.md"
 ```
 
-It runs a **9-phase pipeline** autonomously:
+It runs a **10-phase pipeline** autonomously:
 
 ```
-Build → Browser Test → Evaluate → Fix Loop → Simplify → Review → Security → Clean → Docs
+Build → Build Gate → Browser Test → Evaluate → Fix Loop → Simplify → Review → Security → Clean → Docs
 ```
 
 - Each phase runs as a separate agent with fresh context
 - Git checkpoints at every phase for safe rollback
+- **Build Gate** runs your project's real compilers, typecheckers, and linters — catches type errors, cross-package drift, and Docker build failures that tests alone miss. Auto-detects project type (Next.js, Rust, Go, Solidity, Expo, Swift, and more) and Dockerfiles.
 - Browser validation tests your feature end-to-end (clicks, forms, verification)
 - Evaluation grades against done-criteria — if it fails, auto-fix and re-evaluate
 
-Skip phases you don't need: `--skip-browser`, `--skip-review`, `--skip-clean`, `--skip-docs`, `--max-rounds 6`
+Skip phases you don't need: `--skip-browser`, `--skip-review`, `--skip-clean`, `--skip-docs`, `--skip-build-gate`, `--max-rounds 6`
+Customize the build gate: `--build-gate strict` (warnings = errors), `--build-gate no-docker` (skip Docker builds for speed)
 
 ### Step 3 — Verify with `/devlyn:preflight`
 

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/config/skills/devlyn:auto-resolve/SKILL.md

@@ -31,6 +31,8 @@ This pipeline runs hands-free. The user launches it to walk away and come back t
    - `--skip-clean` (false) — skip clean phase
    - `--skip-browser` (false) — skip browser validation phase (auto-skipped for non-web changes)
    - `--skip-docs` (false) — skip update-docs phase
+   - `--skip-build-gate` (false) — skip the deterministic build gate (Phase 1.4). Not recommended — the build gate is the primary defense against "tests pass locally, breaks in CI/Docker/production" class of bugs.
+   - `--build-gate MODE` (auto) — controls build gate behavior. `auto`: detect project type and run appropriate build/typecheck/lint commands; if Dockerfile(s) are present, Docker builds are included automatically. `strict`: auto + treat warnings as errors. `no-docker`: auto but skip Docker builds even if Dockerfiles exist (for faster iteration). `skip`: same as --skip-build-gate.
    - `--with-codex` (false) — use OpenAI Codex as a cross-model evaluator/reviewer via `mcp__codex-cli__*` MCP tools. Accepts: `evaluate`, `review`, or `both` (default when flag is present without value). When enabled, Codex provides an independent second opinion from a different model family, creating a GAN-like dynamic where Claude builds and Codex critiques.
 
    Flags can be passed naturally: `/devlyn:auto-resolve fix the auth bug --max-rounds 3 --skip-docs`
@@ -43,7 +45,7 @@ This pipeline runs hands-free. The user launches it to walk away and come back t
 ```
 Auto-resolve pipeline starting
 Task: [extracted task description]
-Phases: Build → [Browser] → Evaluate → [Fix loop if needed] → Simplify → [Review] → [Security] → [Clean] → [Docs]
+Phases: Build → Build Gate → [Browser] → Evaluate → [Fix loop if needed] → Simplify → [Review] → [Security] → [Clean] → [Docs]
 Max evaluation rounds: [N]
 Cross-model evaluation (Codex): [evaluate / review / both / disabled]
 ```
@@ -86,6 +88,63 @@ The task is: [paste the task description here]
 3. If no changes were made, report failure and stop
 4. **Checkpoint**: Run `git add -A && git commit -m "chore(pipeline): phase 1 — build complete"` to create a rollback point
 
+## PHASE 1.4: BUILD GATE
+
+Skip if `--skip-build-gate` or `--build-gate skip` was set.
+
+This phase runs the project's real build, typecheck, and lint commands — the same ones CI, Docker, and production environments will run. It catches the entire class of bugs that LLM-based evaluation and test suites cannot: type errors in un-tested files, cross-package type drift in monorepos, lint violations, missing production dependencies, and Dockerfile copy mismatches.
+
+This is deterministic — if the compiler says no, the pipeline stops. No LLM judgment involved.
+
+Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`.
+
+Agent prompt — pass this to the Agent tool:
+
+You are the build gate agent. Read `references/build-gate.md` from the auto-resolve skill directory for the full project-type detection matrix and execution rules.
+
+Your job: detect every project type in this repo, run their build/typecheck/lint commands, and report results. You do NOT reason about code quality — you run commands and faithfully report what they output.
+
+1. Read the detection matrix in `references/build-gate.md`
+2. Scan the repo to detect all matching project types (a monorepo may match several)
+3. Detect the package manager (npm/pnpm/yarn/bun) per the rules in the reference file
+4. Run all gate commands. Sequential within a project type, parallel across unrelated types.
+5. If `--build-gate strict` is set, apply strict-mode flags per the reference file
+6. Run Dockerfile builds if Dockerfiles are detected, UNLESS `--build-gate no-docker` is set (see reference file)
+7. Write results to `.devlyn/BUILD-GATE.md` following the output format in the reference file
+
+For failures: include the FULL error output (not truncated) and extract root file:line references with concrete fix guidance so the fix agent knows exactly where to look.
+
+**After the agent completes**:
+1. Read `.devlyn/BUILD-GATE.md`
+2. Extract verdict
+3. Branch:
+   - `PASS` → continue to PHASE 1.5
+   - `FAIL` → go to PHASE 1.4-fix (build gate fix loop)
+
+## PHASE 1.4-fix: BUILD GATE FIX LOOP
+
+Triggered only when PHASE 1.4 returns FAIL.
+
+Track a round counter (shared with the main fix loop counter against `max-rounds`). If `round >= max-rounds`, stop with a clear failure report — do NOT continue to evaluate/browser/etc. Code that doesn't build cannot be meaningfully evaluated or tested.
+
+Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`.
+
+Agent prompt — pass this to the Agent tool:
+
+Read `.devlyn/BUILD-GATE.md` — it contains deterministic build/typecheck/lint failures from real compiler output. These are not opinions; the compiler rejected this code. Fix every listed failure at the root cause level.
+
+For each failure:
+1. Read the referenced file:line and enough surrounding context to understand the error
+2. For type errors: check BOTH sides of the type contract — the consumer AND the type definition. The fix may belong to either side. Do NOT suppress errors with `any`, `@ts-ignore`, `as unknown as`, `// eslint-disable`, or equivalent escape hatches.
+3. For lint errors: fix the underlying issue, do not disable the rule.
+4. For missing module/dependency errors: investigate the cause — it may be a missing dep in package.json, a typo in the import path, or a tsconfig paths misconfiguration.
+5. After fixing, do NOT re-run the build yourself. The orchestrator re-runs PHASE 1.4.
+
+**After the agent completes**:
+1. **Checkpoint**: `git add -A && git commit -m "chore(pipeline): build gate fix round [N]"`
+2. Increment round counter
+3. Go back to PHASE 1.4 (re-run the gate)
+
 ## PHASE 1.5: BROWSER VALIDATE (conditional)
 
 Skip if `--skip-browser` was set.
@@ -284,7 +343,7 @@ Synchronize documentation with recent code changes. Use `git log --oneline -20`
 After all phases complete:
 
 1. Clean up temporary files:
-   - Delete the `.devlyn/` directory entirely (contains done-criteria.md, EVAL-FINDINGS.md, BROWSER-RESULTS.md, screenshots/, playwright temp files)
+   - Delete the `.devlyn/` directory entirely (contains done-criteria.md, BUILD-GATE.md, EVAL-FINDINGS.md, BROWSER-RESULTS.md, screenshots/, playwright temp files)
    - Kill any dev server process still running from browser validation
 
 2. Run `git log --oneline -10` to show commits made during the pipeline
@@ -300,6 +359,7 @@ After all phases complete:
 | Phase | Status | Notes |
 |-------|--------|-------|
 | Build (team-resolve) | [completed] | [brief summary] |
+| Build gate | [completed / skipped / FAIL after N rounds] | [project types detected, commands run, pass/fail per command] |
 | Browser validate | [completed / skipped / auto-skipped] | [verdict, tier used, console errors, flow results] |
 | Evaluate (Claude) | [PASS/NEEDS WORK after N rounds] | [verdict + key findings] |
 | Evaluate (Codex) | [completed / skipped] | [Codex-only findings count, merged verdict] |

package/config/skills/devlyn:auto-resolve/references/build-gate.md

@@ -0,0 +1,116 @@
+# Build Gate — Project Type Detection & Commands
+
+Reference for PHASE 1.4 (Build Gate). The build gate agent reads this file to determine which commands to run.
+
+---
+
+## Project Type Detection Matrix
+
+Inspect the repository root and subdirectories (up to 2 levels). A repo can match **multiple** signals — run ALL matching gates. Do not pick "the main one"; a monorepo with a Next.js dashboard + Rust service needs both.
+
+| Signal file(s) | Project type | Gate commands (run in order) |
+|---|---|---|
+| `package.json` with `next` dep | Next.js | `npx tsc --noEmit` → `npx next build` |
+| `package.json` with `nuxt` dep | Nuxt | `npx nuxi typecheck` → `npx nuxi build` |
+| `package.json` with `vite` + `tsconfig.json` | Vite+TS | `npx tsc --noEmit` → `npm run build` (if script exists) |
+| `package.json` with `expo` dep | Expo (React Native) | `npx tsc --noEmit` → `npx expo-doctor` |
+| `package.json` with `react-native` (no expo) | React Native | `npx tsc --noEmit` |
+| `package.json` with `svelte` + `@sveltejs/kit` | SvelteKit | `npm run check` → `npm run build` |
+| `package.json` only, has `build` script | Generic Node | `npm run build` |
+| `package.json` only, has `tsconfig.json` but no `build` | TS library | `npx tsc --noEmit` |
+| `pnpm-workspace.yaml` / `turbo.json` / `lerna.json` | Monorepo | `pnpm -r build` or `turbo run build typecheck lint` — **workspace-wide**, NOT just the changed package |
+| `Cargo.toml` | Rust | `cargo check --all-targets` → `cargo clippy -- -D warnings` |
+| `go.mod` | Go | `go build ./...` → `go vet ./...` |
+| `foundry.toml` | Foundry (Solidity) | `forge build` |
+| `hardhat.config.{js,ts,cjs}` | Hardhat (Solidity) | `npx hardhat compile` |
+| `Anchor.toml` | Anchor (Solana) | `anchor build` |
+| `Move.toml` | Move (Sui/Aptos) | `sui move build` or `aptos move compile` |
+| `pyproject.toml` / `setup.py` + mypy config | Python+mypy | `mypy .` |
+| `pyproject.toml` with `ruff` | Python+Ruff | `ruff check .` |
+| `Package.swift` | Swift package | `swift build` |
+| `*.xcodeproj` / `*.xcworkspace` | iOS/macOS (Xcode) | Skip by default — log "Xcode project detected, manual build gate recommended". Too project-specific without knowing the scheme. |
+| `build.gradle*` / `settings.gradle*` | Gradle/Android | `./gradlew assembleDebug` (debug, not release — keep it fast) |
+| `CMakeLists.txt` | C/C++ (CMake) | `cmake -B build && cmake --build build` |
+| `Makefile` (with no other signals) | Generic Make | `make` (only if no other type matched — Makefiles are too generic) |
+| `Unity/ProjectSettings/` or `ProjectSettings/ProjectVersion.txt` | Unity | Skip by default — log "Unity project detected, manual build gate recommended" |
+| `project.godot` | Godot | Skip by default — log "Godot project detected, manual build gate recommended" |
+| `Dockerfile*` | Docker | `docker build -f <dockerfile> -t _pipeline_gate_test .` — included by default in `auto` mode. Skip with `--build-gate no-docker`. |
+
+## Package Manager Detection
+
+Respect the project's package manager. Check in order:
+1. `packageManager` field in root `package.json` → use that
+2. `pnpm-lock.yaml` exists → `pnpm`
+3. `yarn.lock` exists → `yarn`
+4. `bun.lockb` / `bun.lock` exists → `bun`
+5. Default → `npm`
+
+Replace `npm run build` / `npx` accordingly: `pnpm build` / `pnpm exec`, `yarn build` / `yarn`, `bun run build` / `bunx`.
+
+## Monorepo Handling
+
+Monorepo is the most critical case — cross-package type drift is the #1 source of "tests pass locally, build fails in CI."
+
+1. Detect workspace root markers: `pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, `workspaces` in root `package.json`
+2. Run gates at the **workspace root** level, not per-changed-package:
+   - Turbo: `turbo run build typecheck lint` (respects dependency graph)
+   - pnpm: `pnpm -r build` (runs in topological order)
+   - yarn workspaces: `yarn workspaces foreach -A run build`
+   - npm workspaces: `npm run build --workspaces`
+3. This ensures Package A's type change that breaks Package B's consumer is caught, even if only Package A was directly modified.
+
+## Strict Mode (`--build-gate strict`)
+
+When strict mode is set, treat warnings as failures:
+- TypeScript: add `--strict` if not already in tsconfig (or verify it's set)
+- Clippy: `-D warnings` (already default in the matrix)
+- ESLint: `--max-warnings 0`
+- Go vet: already treats warnings as errors
+- Foundry: `--deny-warnings`
+
+In default (auto) mode, only hard errors (non-zero exit code from the tool's perspective) block.
+
+## Docker Build (default in `auto` mode)
+
+When `Dockerfile*` files are detected AND `--build-gate no-docker` is NOT set:
+1. Run all non-Docker gates first (they're faster and catch most errors before the slow Docker step)
+2. Then run `docker build -f <dockerfile> -t _pipeline_gate_test .` for each Dockerfile found in the repo root and subdirectories (up to 2 levels)
+3. If Docker daemon is not available, log the skip with a warning but do NOT fail — developers without Docker should not be blocked. The warning should note: "Docker builds were skipped because the Docker daemon is unavailable. Use `--build-gate no-docker` to suppress this warning, or ensure Docker is running to catch Dockerfile-specific issues."
+4. This catches Dockerfile-specific issues that no other gate can: COPY paths referencing files excluded by .dockerignore, multi-stage build failures, production-only dependency resolution, and environment differences between dev and container builds
+
+Use `--build-gate no-docker` to skip Docker builds for faster iteration during development — the language-level gates (tsc, cargo check, etc.) still run and catch the majority of issues. Docker builds are most valuable as a final gate before shipping.
+
+## Output Format
+
+Write results to `.devlyn/BUILD-GATE.md`:
+
+```markdown
+# Build Gate Results
+## Verdict: [PASS / FAIL]
+## Detected Project Types
+- [type] ([path/])
+## Gate Commands Run
+| # | Command | Dir | Exit | Status | Time |
+|---|---|---|---|---|---|
+| 1 | `npx tsc --noEmit` | dashboard/ | 0 | PASS | 4.2s |
+| 2 | `npx next build` | dashboard/ | 1 | FAIL | 9.8s |
+| 3 | `cargo check --all-targets` | services/indexer/ | 0 | PASS | 12.1s |
+
+## Failures
+
+### Command #2: `npx next build` (dashboard/, exit 1)
+```
+[full error output — do NOT truncate. Build errors reference files from earlier in output.]
+```
+
+**Root file:line(s)**:
+- `dashboard/app/(dashboard)/settings/page.tsx:90` — Type error: Property 'config' does not exist on type 'SettingsTabsProps'
+
+**Fix guidance**:
+Read `dashboard/app/(dashboard)/settings/page.tsx:88-93` and `dashboard/components/settings/SettingsTabs.tsx` (the SettingsTabsProps type definition). Either add `config` to SettingsTabsProps or remove the prop from the parent. Then re-run `npx next build` from `dashboard/` to verify.
+```
+
+Verdict rules:
+- Any exit code != 0 → **FAIL**
+- All exit codes == 0 → **PASS**
+- No gates detected → **PASS** with note "No build gate detected — project type unknown. Consider adding `--build-gate deploy` if Dockerfiles are present."

package/config/skills/devlyn:preflight/references/auditors/code-auditor.md

@@ -8,6 +8,19 @@ You are auditing a codebase against its planning commitments. Your job is to ver
 
 Read `.devlyn/commitment-registry.md` for the full list of commitments to verify. Skip any items in the "Not Started (Planned)" section — those are acknowledged future work, not gaps.
 
+**Step 0 — Build health check**: Before auditing individual commitments, verify the project actually builds. Detect the project type(s) and run their build/typecheck commands:
+- `package.json` with `next` → `npx tsc --noEmit && npx next build`
+- `package.json` with `vite` + `tsconfig.json` → `npx tsc --noEmit`
+- `Cargo.toml` → `cargo check --all-targets`
+- `go.mod` → `go build ./... && go vet ./...`
+- `foundry.toml` → `forge build`
+- `hardhat.config.*` → `npx hardhat compile`
+- Monorepo (`pnpm-workspace.yaml`/`turbo.json`) → workspace-wide build
+- `Dockerfile*` → `docker build` (if Docker available)
+- For other project types, look for a `build` script in `package.json` or equivalent
+
+Any build/typecheck failure is a BROKEN finding at CRITICAL severity — code that doesn't compile cannot fulfill any commitment. Include the full compiler error output with file:line references. This catches type errors, missing imports, cross-package drift, and Dockerfile build failures that text-based code reading alone cannot detect.
+
 **For each active commitment (not planned):**
 1. Search the codebase for its implementation (use Grep, Glob, Read in parallel where possible)
 2. Read the implementing code thoroughly — line by line for critical paths

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.8.1",
+  "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": {