mechanism

What it does

Ask your agent for an exploded view or a drawing of something real: a machine, a chip, a board, or software (a file format, a protocol, an algorithm's output).

1. Researches. Opens datasheets, drawings, CAD files and teardowns, looks at the pictures, measures them.
2. Writes a spec. Parts with real dimensions, how they move, and the evidence behind every number.
3. Runs the gate. The model is compared with what is published. A spec that does not add up is not rendered, and one that does is told how far it was really checked.
4. Renders. A film (4:5, 9:16 or 1:1, with real recorded sound), a live viewer, an STL / GLB, or, for flat parts, an SVG drawing at true scale.

Every number carries its class:

The gate

$ node scripts/check-spec.mjs examples/hub/spec.js
...
  centres sun-p1: 16.000 mm (required 16.000)  ok
  mode Gear 2: 1.0000  published 1  ok
  mode Gear 3: 1.3333  published 1.3333333333333333  ok
  mode Gear 1: 0.7500  published 0.75  ok
provenance: 3 independent, 0 same source as the inputs, 0 with no sourced inputs, ...
verdict: VERIFIED   3 reproduced, 4 estimated, 0 unchecked published comparisons

Break something and it says exactly what:

$ node scripts/check-spec.mjs examples/k20a/spec.js      # firing order changed to 1-2-3-4
ERROR  firing order 1-2-3-4: cylinder 3 would have to fire at 360 degrees and its crank throw is at 180 (not possible with that crankshaft)
ERROR  firing order 1-2-3-4: cylinder 4 would have to fire at 540 degrees and its crank throw is at 0 (not possible with that crankshaft)
ERROR  phase Firing order: the model gives 1-2-3-4 and the published one is 1-3-4-2

DOES NOT PASS: 3 error(s)

It fails (exit 1) when a number has no source, a DERIVED claim has no cross-check, a MEASURED one no error, an ESTIMATED one no reason; when two meshing gears are not at the centre distance their module and teeth demand; when a mode does not give the ratio the maker publishes; when a cipher disagrees with a published test; when a firing order is impossible with the crank; when a drawn dimension differs from the figure it cites. It also refuses what a template leaves behind: placeholder addresses (example.com/.org/.net and their subdomains, any .invalid, .test or .example host, localhost), TODO, non-finite or non-positive sizes, a variable with no claim.

The verdict says how far it was really checked:

• VERIFIED: every published figure matched, none is pending, and at least one check is independent: the published figure's sources share nothing with the sources of the inputs the model computed it from.
• CONSISTENT: everything matched, but no check is independent. The checks share their source with the inputs, or compare a drawn dimension with the very figure it was drawn from, or have inputs the gate cannot trace. The gate says which.
• NOTHING CHECKED: nothing was compared; a description, not a verification. INCOMPLETE: a comparison is pending. DOES NOT PASS: any mismatch.

The full contract, and why four examples went from VERIFIED to CONSISTENT when it was tightened: docs/draft-evidence.md. --json verdict.json writes the report (verdict, errors, spec and kit SHA-256, Node version, date); node scripts/registry.mjs writes docs/registry.html and a badge per object straight from the gate.

Draft: dimensioned drawings

For flat parts (plates, brackets, flanges, PCB outlines, panels with holes and slots) the spec declares the geometry in mm and Draft exports an engineering SVG: at 1:1 (1 unit = 1 mm, the document's size in mm) or on an A4 sheet with its scale written on it. Circles and arcs stay exact, every dimension is a value of the geometry, and its colour says its evidence: teal printed by the source, blue derived, violet measured, ink given by the user or not verified, amber estimated. Every file says NOT A MANUFACTURING DRAWING: there are no tolerances, fits or finish.

node scripts/check-spec.mjs examples/rpi4-board/spec.js                          # CONSISTENT: one maker's PDF and DXF
node scripts/export-svg.mjs examples/rpi4-board/spec.js --mode geometry-1to1 --out work/svg

The Raspberry Pi 4 above comes from Raspberry Pi's own drawing (cited, not copied): 85 x 56 mm, R3 corners, four Ø2.7 holes on 58 x 49 mm. Draft is also a plugin on its own (1.6 MB, no 3D): plugins/mechanism-draft.

Tested by strangers. Fresh agent sessions with only the plugin installed were given one sentence each. In the first test (Draft 0.4) the drawings were exact, but a plate whose only source was the request passed as VERIFIED, a narrow part's SVG cut its manufacturing warning, and the skill was not picked unless named; all three were fixed. Afterwards, unprompted, it picked the skill in 3 of 3 sessions (a plate, a flange, an Arduino Uno outline from Arduino's CAD files), declared the user's numbers as USER, and reported CONSISTENT. Three runs, not a rate. When asked for a "final drawing with industrial tolerances" from a photo with no dimensions, the agent asked for measurements instead of inventing a drawing.

Examples

Every example is a film, a live viewer (examples/<name>/index.html?explore) and a model. The verdict is the gate's, today.

CONSISTENT is not a failure: the model agrees with its source in every figure compared. It means a wrong source would agree too. Synthetic demonstrations (demo-plate, demo-flange, demo-section) are NOTHING CHECKED on purpose.

Install

As a Claude Code plugin (Claude Code 2.1.275 or later):

/plugin marketplace add DiegoLopez0208/mechanism
/plugin install mechanism@mechanism            # everything: Studio, Workflow, Paper, Draft
/plugin install mechanism-draft@mechanism      # only the drawings (SVG, Paper sheets), 1.6 MB, no 3D

Or by hand, as a plain skill:

# macOS / Linux: a sparse clone (no site media, little history; tests include compact golden frames)
git clone --depth 1 --filter=blob:none --sparse https://github.com/DiegoLopez0208/mechanism ~/.claude/skills/mechanism
git -C ~/.claude/skills/mechanism sparse-checkout set kit scripts examples data tools tests
# Windows (PowerShell)
git clone --depth 1 --filter=blob:none --sparse https://github.com/DiegoLopez0208/mechanism $env:USERPROFILE\.claude\skills\mechanism
git -C $env:USERPROFILE\.claude\skills\mechanism sparse-checkout set kit scripts examples data tools tests

Then ask: "Use mechanism to model a mechanical keyboard switch from its published sources" or "a dimensioned SVG of a 120 x 80 mm plate with four 6 mm holes". Needs Node 22+; films and stills also need Edge or Chrome (on Linux, Google Chrome stable) and ffmpeg, and Studio films want a GPU. The gate and the SVG export need only Node.

Use the toolkit directly

node scripts/new.mjs my-object --title "My object"          # a draft spec that fails the gate until it is filled in
node scripts/check-spec.mjs examples/my-object/spec.js      # the gate
node scripts/export-svg.mjs examples/rpi4-board/spec.js --mode sheet-fit --out out/svg   # SVG of the flat parts
node scripts/render.mjs examples/my-object/index.html --out out/my-object.mp4            # the film
node scripts/render.mjs examples/my-object/index.html --length short --aspect 9:16 --out out/short.mp4
node scripts/render.mjs examples/my-object/index.html --method paper --background ivory --still 12 --out out/sheet.mp4
node scripts/render.mjs examples/my-object/index.html --export glb --e 1 --out out/my-object.mp4   # also: --export stl
node scripts/probe.mjs "examples/my-object/index.html?explore" out/probe                  # mouse-driven check of the viewer

Engines (Studio, Workflow, Paper), backgrounds, styles, lengths, encoders and the visual regression tests: docs/rendering.md.

How it works

spec.js  ->  the gate (kit/spec-core.js): sources, classes, kinematics, published figures, provenance
         ->  film (Studio 3D, Workflow or Paper; 4:5, 9:16, 1:1; three lengths; stereo)
         ->  interactive viewer (orbit, explode, measure, run the mechanism)
         ->  STL and GLB of the model
         ->  SVG drawings of its flat parts (kit/geom2d.js, kit/svg2d.js)

A part, with the evidence it stands on:

{ id: 'ring', kind: 'ring', p: { m: 0.8, z: 60, ro: 27.4, width: 8 }, mat: 'steel-dark',
  at: [0, 0, 0], body: 'ring', explode: [0, 0, -12], conf: 'derived', claims: ['teeth', 'formula'],
  params: { ro: { value: 27.4, unit: 'mm', conf: 'derived', claim: 'formula' } } }

Recognisable, not just correct. A spec declares what a stranger should call the object and the features that make it that object, each tied to parts that exist; node scripts/stranger.mjs <example> saves a still with no labels, a model with no context is asked what it is, and the answer is recorded. Run on the shipped examples it found two that were not recognisable.

Software is verified against the real program: make the real tool produce a sample, write a pure model from the published description, and the gate demands that the model rebuilds the sample byte for byte and that the real tool accepts what the model built (examples/rar5, examples/winrar).

Brand identity is drawn with decals (type, rules and shapes), never logo files, and declared like any other number: a livery no opened source shows is ESTIMATED.

Agent runs

Two 3D objects were given to fresh agents with only the skill and one sentence, under criteria written before the results (docs/benchmark/criteria.md):

The drawing runs are above, under Draft. Few runs are data points, not a success rate. Notes: docs/benchmark/.

Limits, stated plainly

• VERIFIED means compared and independent, not true. The gate does not know whether a source is right; it trusts derives when one source says it copies another, and it cannot tell that a model hard-codes the answer. Reading the spec is still the review.
• Not for manufacture. No tolerances, fits, surface finish or material specification. A 1:1 SVG is true size in a viewer; a printer may rescale it, so check with a rule.
• Mechanisms so far: gear trains (one degree of freedom), presses and slides, rotor ciphers, crank-slider engines, the Rubik cube and calculated figures. No general linkages. Flat-part outlines are rectangles, circles and straight-sided polygons (no arcs inside a polygon yet).
• Interiors need photos or drawings; without them they are estimated and dashed. A single photo gives no millimetres: it needs a published size, a ruler or a datasheet.
• Rendering speed. Studio films want a GPU (about 2-3 s per second of video on a laptop GPU; with software WebGL about 7 s per frame). Workflow, Paper, the gate and the SVG export do not.
• Platforms. Developed on Windows; tests and gates run on Ubuntu 24.04 in CI and were checked on WSL2. Films were not rendered on Linux, nothing was tried on macOS.

Roadmap

Arcs in polygon outlines; a bicycle drivetrain; more stranger runs of the drawing skill on real requests; the next objects of the agent test. The rule is the same for all: numbers that can be computed and checked against what is published, and an honest word about the ones that cannot.

Inspiration

Anatomy showed that an agent skill can explain something by building it as an interactive physical object, and its "Fig N" card is where ours started. mechanism goes the other way: real objects, every number traced to a source, a gate that refuses what contradicts what is published, and films, 3D files and drawings as outputs.

License

MIT. three.js, Inter and Cormorant Garamond are bundled under their own licenses, and the sound samples are CC0: see THIRD_PARTY.md. Product names identify the objects modelled and belong to their owners; their photos, datasheets and drawings are not redistributed.