Joinery CAD: a built-in as parametric code
The model is the single source of truth. Every dimension lives in params.py; model.py
builds tagged boxes from them; the checks, the BOM, the cut list and the drawings all read the
geometry. Change one number and everything follows. This came out of a full media-wall build
(Nov 2026: 160+ parts, a CLS frame, boards, shelves, services, kit) for an owner who reads
Python but doesn't write it.
Start with the task
<skill-dir> means this skill's own folder: the base directory shown when the skill loads (for a personal install, ~/.claude/skills/joinery-cad).
| Task | Start with | Go deeper |
|---|---|---|
| Start a new project | Copy template/ (built against a wall) or template-furniture/ (a carcass), below | - |
| A wardrobe, drawers, cabinet or shelving unit | template-furniture/: panels, hinges, runners, edging | references/carcass-furniture.md |
| Take in site measurements | params.py: value + who/when/how/tolerance | references/site-survey.md |
| Use a phone LiDAR room scan | scripts/scan_import.py (POOR means rescan, not use), then the tape for anything fixed or fitted | references/lidar-scans.md |
| Add or change parts | model.py helpers: make_box, timber, stud_positions, sheet_strips | references/build123d-notes.md |
| Check a change | checks.py, then a snapshot you look at yourself | references/design-checks.md |
| Show someone / get a render | STEP, GLB, coloured elevation, image prompt | references/visualise.md |
| What to buy, cut lists | The cut-list-and-shopping skill | - |
| Drawings for whoever builds it | The build-drawings skill | - |
| How to frame it and fix it to the wall | The uk-stud-framing skill | - |
| Prices and where to buy | The uk-materials-pricing skill | - |
Start a new project
cp -R <skill-dir>/template ~/projects/<Name>
cd ~/projects/<Name> && mv gitignore .gitignore
uv sync
uv run python src/builtin/checks.py # 3 PASS on the example
git init -q && git add -A && git commit -qm "Start from the joinery-cad template"
For a wardrobe, chest of drawers, cabinet or shelving unit, copy template-furniture instead
(package furniture; 13 PASS on its example, a two-door wardrobe with two drawers under). Its
panel() helper carries edge banding and grain into the cut list, and door and drawer
positions follow the hinge and runner numbers in params.py.
Rename the package (builtin or furniture) if you like (folder, imports, pyproject.toml).
Replace the example with the real design, a layer at a time, starting from boxes for the main
volumes before any frame or hardware. Fill in the template's CLAUDE.md, and keep
it short: the brief and decision log go in docs/decisions.md, read when needed, because
CLAUDE.md is loaded with every message.
The model contract
These conventions are what make the BOM, checks and drawings work without special cases.
- Millimetres. Origin at the bottom-left of the existing wall face, at floor level. Say which floor (floorboards or finished floor): it decided a 20 mm question on the media wall.
- Axes: X along the wall (left to right from the room), Y INTO the wall, Z up. Room side is
negative Y. Depths in
params.pyare positive "out from the wall";place_boxnegates them. Getting this wrong mirrors the model left to right; the viewer's Front view is then from the room. - Every number in
params.py, with where it came from:# site survey (owner, Nov 2026, stud finder),# decided (owner, Nov 2026): raised for the toddler, or# TBC. Unmeasured values also go in theTBClist, which every script prints. Never invent a survey value. - Derive, don't copy. If the recess top is "one timber below the niche", write it that way
in
params.pyso it follows when the niche moves. - One part = one thing you cut or buy, made by
make_box()ortimber(), carryingname,material,stock,zoneand a colour.stocktells the BOM how it's bought:"... sheet", a timber stock text,"each", or"existing"/"owner supplies". Names are unique and plain English ("L shelf 2 (1760)"): they become cut-list rows and drawing labels.checks.pyfails on an untagged part, because it would silently drop off the BOM. - Layers are top-level
Compounds: Existing, Frame, Boards, Cladding, Shelves, Services, Kit (placeholder boxes for the TV, speakers and other kit, so clearances can be checked). - Real stock sizes: CLS 38 x 63 (or 38 x 89), sheets 2440 x 1220, the shop's real lengths. Sheet joints land on studs; stud positions come from the boards, not the other way round.
Working with the owner
- Small steps. After each change: rebuild, run the checks, look at a snapshot yourself, then show it in the OCP viewer and explain the change in two or three plain sentences.
- Propose the simplest thing that does the job first (a solid packed-noggin block was called "excessive"; a frame went from 52 pieces to 34 after a tradesman's review). Offer heavier options after, with the trade-off.
- Decisions go in
docs/decisions.mdwith who decided, when and why; purchases indocs/purchases.md. Commit after each working step with a clear message. - Quick "how far out is it?" questions get answered by running a facts script (one page of key dimensions measured from the model), never from memory: the design moves.
Check each change
| Change | Check |
|---|---|
| Any change | uv run python src/<pkg>/checks.py: all PASS, and read the INFO lines |
| Geometry you can't verify from numbers alone | Snapshot (below) and look at it with Read |
| A survey value | The cross-checks in site-survey.md (stud gaps add up to the wall width, etc.) |
| Stock, sizes or materials | The BOM sanity summary against a rough hand count |
| Before showing the owner | Both of the above, then ocp_vscode.show |
Snapshot: line drawings (hidden lines removed) of front, top, end and 3D views in one PNG. You can't see the OCP viewer, so this is how you check your own work first:
uv run python <skill-dir>/scripts/snapshot.py --build <pkg>.model:build --out out/snapshot.png
uv run python <skill-dir>/scripts/snapshot.py --build <pkg>.model:build --layer Frame --views front,iso --hidden
A check is only worth something if it measures the thing that matters. On the media wall a "media panel reachable" check measured the hatch panel instead of the hole you reach through, so its margin was wrong. Measure from the geometry, by part name, the thing a person will actually reach, see or fix into.
Gotchas from the media wall
- A stud run's end stud plus the last regular stud can land almost together: drop regular
studs too close for a noggin (
stud_positionsdoes). - A bracket at every stud put two brackets side by side at a corner: skip one closer than ~300.
- An offcut sliver (19 mm of board beside an opening) means a joint is in the wrong place: move the joint stud, not the opening.
- A corner stud in the existing wall is an assumption until found: say so wherever a fixing relies on it.
- A timber that "floats" (fixed to nothing) is easy to miss in numbers and obvious in a picture: look at the snapshot, and run rails on to a stud each side.