img2threejs – Design & UI skill for AI agents

img2threejs — Image to procedural Three.js

Rebuild the object visible in a reference image as a code-only procedural Three.js model,

gated by a staged sculpting pipeline and an AI-vision self-correction loop. This is

reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.

Agent-agnostic: works under Claude Code, Codex, or OpenCode. Wherever this doc says "agent

vision" or "agent browser tool", use whatever the host provides — native image reading, a

browser MCP (playwright/chrome-devtools), the project preview, or a user-supplied screenshot.

This file is the always-loaded router: it holds the order of operations and every hard rule as one

line. The full contract behind each rule lives in the grimoire/ or docs/ file that rule names —

read the named file at the moment you reach that stage, not before.

Canonical shared checkout

Keep one checkout of this repository and let every host enter it through a symlink, so Claude and

Codex execute the same code instead of drifting apart:

~/.claude/skills/img2threejs -> <your checkout>
~/.codex/skills/img2threejs  -> <your checkout>

When To Use

The user attaches/points to an object image and wants a procedural Three.js model, a

reconstruction/animation/destruction plan, a sculpt spec, or code. Also for material studies,

action-ready props, game objects, botanical/mechanical parts, and stylized reconstructions.

Core Promise

Sculpt from a photo, in order — never one-shot a mesh:

1. Run python3 forge/next.py --state .img2threejs/state.json [<spec>] first, at every start,

resume, and before every correction iteration. It reports the ordered checklist, exact next

command, evidence status, and bounded correction-loop status; it never replaces the spec/pass

gates. Obey a hard stop; never continue from memory.

2. Validate the image is a suitable 3D target (grimoire/intake/validation_rubric.md).

3. Assess object class + complexity, then write a qualityContract before any code.

4. Spec it: component hierarchy, materials, lighting, pivots, sockets, action anchors.

5. Build pass-by-pass from blockout → structure → form → material → lighting → interaction → optimization.

6. Verify each pass with a screenshot compared against the reference; fail a pass if an

identity-defining feature is wrong even when the global score looks fine.

State explicitly when output is approximate/stylized/low-poly. A single image cannot reveal

hidden sides or guarantee exact geometry — say so instead of faking confidence.

Mandatory Local State Gate

Conversation context is disposable; .img2threejs/state.json is the local checklist authority.

Initialize once per reconstruction, then gate every step through it:

python3 forge/state.py init --state .img2threejs/state.json --reference <img> --profile <generic|cs2|character|animated-character> --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json [object-sculpt-spec.json]
python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence <path>

• next.py prints the current step, pass, incomplete mandatory steps, exact next command, and

loop/max. Exit code 3 or status=stopped is a hard stop: report the reason and request input.

Never bypass it by reconstructing progress from chat history.

• Every completed step needs evidence; mark a non-applicable step skipped only with --reason —

silent omission is forbidden. Loop counts derive from reviewHistory actions

(refine-spec/refine-code), not agent memory. Defaults: 3 corrections per pass, 6 total.

• Profiles add mandatory gates without changing the core order: cs2 requires classification,

manifest, and a machine-readable CS2 review before AI review; character requires the character

contracts and landmark evidence; animated-character adds all of character plus the nine Stage R

steps (grimoire/readiness/animation_contract.md). Pick it whenever the rig must MOVE — on

character the Stage R gates are absent and the build completes without ever running them, which

is how animation used to ship broken. Its order is load-bearing: repair the mesh, freeze it, bind

additively, then verify parity. Every profile records suitability, projection applicability, and

material-evidence applicability. The state file is a resumability index, not visual evidence:

renders, specs, review history, and deterministic gates remain the authoritative artifacts.

Required Inputs

• one image path / screenshot / URL / attached image (if missing or unreadable, ask)
• intended use: prop, game object, hero render, playable/destructible object, animation rig

(default: real-time browser prop with interactive performance)

• for a CS2 request, an authoritative classification record (family/subtype and evidence refs) or

an explicit request for the user/vision provider to supply one; heuristic detection alone is not

enough to select a geometry adapter

The Loop (scripts do enforcement; agent vision does judgment)

Run scripts from the skill root (forge/...). Pure Python 3.10+ stdlib, no pip installs.

Full flags: grimoire/scripts.md. Never let a script *score* visuals — that is the agent's job.

1. Analyze the image first (agent vision, before any script): work the layered observation

protocol in grimoire/intake/image_analysis.md — identify/classify, decompose macro→meso→micro,

map part relationships, name materials in PBR terms, list identity-defining features, and flag

what the single view hides. Observation before inference; controlled 3D vocabulary; 3D

object-space not 2D image-space. Then probe local images:

forge/stage1_intake/probe_image.py <image> (metadata only, not a visual check).

1a. Local Spec Search — after image analysis, before writing or refining a spec, pull local

domain evidence (anatomy/PBR/wear/geometry/runtime/physics) rather than inventing it:

python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --out assessment.json

(auto-runs BM25, auto-picks cs2/core_3d collection, writes a localSpecSearch bundle that

new_sculpt_spec.py --assessment carries into the spec). Full query-expansion recipe

(bilingual terms, focused search_specs.py retrieval, cache rules):

grimoire/intake/local_spec_search.md. MUST read it before retrying an incomplete or

domain-specific query.

1b. CS2 intake manifest — for a CS2 request, create and validate cs2-intake.json before

pre-spec authoring (admission, heuristic signal, classification, family/route resolution).

MUST read grimoire/intake/cs2_intake_contract.md completely before creating the manifest or

running pre-spec assessment.

1c. Optional fidelity evidence adapters — only when they improve an observed weak point; the

stdlib core remains authoritative. Thin/complex masks → local SAM2; character face/pose →

MediaPipe; weak front/back cues → Depth Anything V2

(forge/stage1_intake/run_vision_adapter.py <segment|landmarks|depth> ...; every adapter emits

provenance; monocular depth is relative only). **MCP-only scene mutations never count as

implementation** — write the proven change back to the spec or TypeScript, rebuild, recapture.

Full adapter + MCP routing and authority boundaries:

docs/integrations/reference_fidelity_tooling.md.

2. Pre-Spec Assessment Gate — classify + score complexity + write the quality contract:

forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json. Rules: grimoire/intake/quality_contract.md.

Set objectClass.primaryDomain (object | character | hybrid) and fill the seeded

detailInventory (its targetMinDetails scales with complexity). **Supported CS2 knife skins

and Glock-18 assets**: always pass --cs2, which defaults the complexity tier to ultra-complex

(targetMinDetails 16, floor 9) — the finish/wear/hardware is the item, so CS2 is held to the

top fidelity bar. Author procedural GEOMETRY but route the FINISH through the projection path in

step 2c — a procedural finish for a patterned skin (Doppler/Gamma/Marble/Fade) reads visibly

wrong against the reference. Finish routes + rulebook: grimoire/build/cs2_finishes.md;

optional exact-texture acquisition: grimoire/intake/cs2_texture_acquisition.md.

2b. Detail inventory (do not skip for detailed subjects) — scan zones and enumerate every

identity-defining small detail (gloss, bevel, fasteners, linework, contours, stains):

forge/stage1_intake/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json.

Each detail MUST map to a component.localFeatures or material.localOverrides entry — never

prose only. Taxonomy + 3D-term recipes: grimoire/intake/detail_inventory.md.

2c. **Projection-first fidelit

… (full content is in the download package)