loft

Make a considered image or 3D scene from a described intent the iterative-craft way — block in, render, measure, critique against the intent, refine across passes — instead of trying to emit a finished result in one shot. Use this whenever the user wants to DRAW, sketch, illustrate, depict, compose, or paint a 2D picture, OR model / build / lay out a 3D scene, asset, or environment (e.g. a game prop, a room, a character, a landscape), ESPECIALLY when they give a subject, a mood, or a composition to hit ("an old woman at dusk", "a cosy tavern interior", "a low-poly pine tree", "make it feel ominous"). Also use when iterating on or critiquing such an image/scene. Reach for it even if the user doesn't say "iteratively" — the loop is the point, and one-shot guessing is what it replaces. Do NOT use for text-to-image prompts handed to a diffusion model, for charts / plots / diagrams / dashboards (data visualisation), or for UI / web layout.

Reference for writing correct loft code. Apply whenever writing, editing, or reviewing .loft files. Covers types, syntax, known bugs, workarounds, naming rules, and error→fix table.

Procedures for plan-shaped work — opening a plan, closing/deferring one, promoting a doc to a plan, choosing the lightest workflow, applying value categories. Apply when the task involves plans, plan directories, a roadmap, or doc-to-plan promotion. The method is tree-agnostic; the concrete paths/templates/tracker that bind it to this repo live in one § at the bottom. Cites source docs for definitions; does not restate.

The shared discipline for any non-trivial change — fixing a bug OR designing/refactoring a load-bearing algorithm. USE THIS when about to fix a non-trivial bug (crash, silent corruption, wrong result), design or refactor a load-bearing algorithm (core representation, runtime, memory, codegen, a public contract or data format), when a change feels fragile or "longer than expected for what it does", or when reaching for an approximation in an exact-invariant domain (geometry, caching, hashing, round-trips) and can't pin the exact construction — ESPECIALLY when a fix already looks obvious (that's the cue, not the exception). It is a SPEED tool, not a brake: a coherent explanation is a hypothesis, not a conclusion, and the fastest route to a fix that sticks is the cheapest probe that could prove your idea wrong (a timing, a grep of a count, one --emit-and-look — seconds). So the moment you can state a cause or a fix, that fluency is the cue to GATHER first, not act — which also lets you fix the SOURCE and delete

Design Protocol 1 — a design is a testable HYPOTHESIS about an invariant, not a plan you execute. The DESIGN-mode counterpart to the engineering-rigor skill (which routes here for the design half). USE THIS whenever you are about to commit to a load-bearing design — a core representation, runtime, memory model, codegen, a public contract, a data format, or any algorithm that will carry weight: name the ONE invariant, count its re-assertion sites, build the cheapest probe that could FALSIFY each load-bearing claim, then build and validate against the written prediction. And for exact-invariant domains where you cannot even form the invariant (geometry, caching, hashing, store/memory lifetime, round-trips), flip to the constructive instrument — plot a concrete instance of the ANSWER and read the invariant off it. Reach for it when a design feels too clean, when you keep reaching for an approximation, or whenever you catch yourself about to build the first coherent design without probing it.

Write, bridge, verify, and publish a loft library so it behaves IDENTICALLY on all four targets — the interpreter, --native, --native-wasm, and --html (browser). Use this skill whenever the user is creating, packaging, cross-compiling, or publishing a loft library or package; mentions loft.toml, the target matrix, a wasm bridge, `loft new` / `loft install`, the registry, the sha256/signature, or making a library "work in the browser" / "work in wasm"; or is debugging native-vs-wasm-vs-interpret divergence in a library. Trigger it even when the user doesn't say "all four platforms" — any loft library that has to ship beyond the interpreter belongs here, because the cross-target parity gate and the wasm-bridge pitfalls are exactly where this work silently goes wrong.

The discipline for ANY loft compiler/codegen work — fixing a store-lifetime or codegen bug, adding/altering bytecode, parser IR, the interpreter, or the native generator, or implementing a language feature that emits ops — OR restructuring any of those without meaning to change what they emit (extracting a selector, folding a special case, deleting a redundant condition). USE THIS the moment you are about to edit src/parser/, src/state/codegen.rs, src/fill.rs, src/generation/, src/compile.rs, or scopes.rs to change OR reshape what code is emitted — ESPECIALLY when a fix looks obvious and you're tempted to "just patch the generator and run the suite." The one load-bearing instrument is the same in both modes — `loft introspect` on BOTH backends BEFORE you touch the compiler — but the gate flips: a BUG FIX proves the WORKING bytecode standalone beside the broken one; a behaviour-PRESERVING REFACTOR proves the emitted IR + native Rust BYTE-IDENTICAL before/after. Skipping it is how codegen work flails and regres

Operational companion for running a loft bug down on this box — LOFT_LOG presets, dump files, find_problems flow, the live-debugger RPC surface (loft debug --rpc — scripted breakpoint/eval/setValue sessions), the native-backend env gotchas that cause FALSE failures, and the operational-safety rules for builds/processes. Routes to the matrix-first protocol (CLAUDE.md) for the METHOD; this is the MECHANICS. Apply when reproducing, investigating, or verifying a loft crash, wrong-result, or codegen bug — and whenever about to sprinkle println/probe prints into a loft program (the debugger session replaces them).

Write and edit documentation in the loft repo the way it should read: code comments and doc-comments in `.rs` files, AND prose docs (`.md` — README, onboarding, reference). Use this whenever you add or revise a `///` doc comment, an inline comment, a module `//!` header, or any Markdown doc, and whenever you review the comments in a diff. It keeps comments present-tense (describe the code as it is NOW, not its history), makes a function's description about *why to use it* (not why it was written), strips dead plan-tag/date stamps while keeping live pointers to issues/plans, and keeps prose readable for entry-level and non-native-English readers. Reach for it even when the user only says "document this", "add comments", "write the docstring", "explain this function", "write up the README", or "clean up the comments" — it applies to all of those.

Reference for writing tests against the loft interpreter, --native backend, and WASM build. Apply whenever adding, editing, or reviewing tests/*.rs or tests/scripts/*.loft / tests/docs/*.loft. Covers test-binary layout, the `code!` and `cross_mode!` macros, the @EXPECT_ERROR / @EXPECT_FAIL / @ARGS / @NAME / @TITLE annotations on `.loft` files, ignore conventions, P-id rules, and the targeted-suite map for subsystem changes.