vibe-model

---
name: vibe-model
description: Preview-first reconstruction of reference-driven hard-surface props, machinery, signage, modular architecture, and hero assemblies as direct Three.js source. Use when building, revising, visually matching, previewing, or preparing a procedural hard-surface model for a Vibe3D registry, or when improving, auditing, or upgrading the visual quality of an existing procedural Three.js model in any codebase, with or without a reference image or registry. Do not use for generic Three.js application code, bitmap editing, characters, organic assets, foliage, terrain, or particle effects.
---

# Vibe Model

Build direct Three.js models with one short visual loop:

```text
model source -> deterministic preview -> independent visual critique
      ^                                      |
      `----------- highest-impact fix -------'
```

Before authoring, read both references completely:

- [fast-loop.md](references/fast-loop.md) for capture and critique;
- [modeling-rules.md](references/modeling-rules.md) for hard-surface geometry
  rules that prevent generated-looking results and wasted iterations.

When the model already exists — improving, auditing, or upgrading a
procedural model in a host codebase rather than building one from reference —
also read [improving-existing.md](references/improving-existing.md). It keeps
the same loop but replaces the registry, reference image, and preview CLI
with the host's own contract, a baseline capture, and an authored brief. The
Author, Preview, and Deliver sections below describe the registry workflow;
improving-existing.md states which parts transfer and what replaces the rest.

## Author

Work directly in the registry model source. In this repository the canonical
sources live at `assets/prototypes/<model-id>/model.ts` and are compiled into
the Sci-Fi Kit registry. In another registry, follow its configured source
directory.

Export `createModel`. It may return a Three.js `Group` or a controller with a
stable `root`, optional `update`, semantic parts and actions, and idempotent
`dispose`. Keep preview-only scene setup in `createPreview` rather than inside
the installed model root.

Use shared primitives and material sources when they preserve the intended
shape. Keep the model small enough to understand and change in one focused
edit. Preserve physical bevel widths, clearances, sockets, pivots, semantic
part anchors, and declared configuration behavior.

## Preview

Capture as soon as the primary silhouette and major secondary masses exist:

```sh
bun run vibe:model preview \
  --module assets/prototypes/<model-id>/model.ts \
  --export createModel \
  --asset <model-id> \
  --reference <reference-image>
```

The local compatibility command `bun run asset:forge preview` may be used
during migration. Prefer `vibe:model` in new documentation and automation.

Keep the camera deterministic. Change yaw, pitch, width, height, or the preview
factory only when the reference requires it.

## Critique

Give a fresh critic only the brief, reference, and current beauty image. Ask
for a resemblance score, what reads correctly, and no more than three
prioritized fixes.

Score silhouette and proportions first, then major masses and negative space,
distinctive landmarks, material/value/color read, and detail plausibility.
When the host renders below critic resolution, score that runtime capture
too (improving-existing.md). Apply the highest-impact correction and capture
again.

Stop at a score of 85 or higher, after two plateauing scores, or after ten
iterations. Treat a plateau as evidence to change the representation or obtain
better reference evidence. A runtime-resolution miss of the primary read is
a massing/value problem, not an emissive problem.

## Deliver

Keep the accepted TypeScript source and final deterministic preview. Preserve
runtime anatomy and ownership contracts. Mark preview-only nodes with
`userData.excludeFromExport = true`.

When a GLB is requested, export the accepted model through the shared portable
GLB path so procedural wear is baked into standard PBR data. Report the model
source, final preview, iteration count, accepted score, and unresolved visual
approximations. Do not commit generated previews or GLBs unless requested.

• SKILL.md 4 KB
• agents/openai.yaml 1 KB
• references/fast-loop.md 2 KB
• references/improving-existing.md 5 KB
• references/modeling-rules.md 5 KB