Freecad

FreeCAD

From brief to useful part

Establish what the part must fit, how it attaches, which dimensions are measured, the units and the intended process/material. Explain a needed measurement in everyday terms. A sketch or photo can guide shape, but does not establish scale or hidden dimensions. Record assumptions separately from requirements. For load-bearing, electrical, medical or other consequential uses, identify the necessary professional/physical validation; do not certify suitability from a CAD preview.

Create design.json with the brief, named parts/reference envelopes and measurable checks. Read the design contract when creating or changing this file. Cover the requirements that matter to the user's job: outside dimensions alone do not establish fit. Use reference shapes for boards, connectors, movement or fastener/tool access, and check those references' dimensions/positions so an accidentally moved or undersized keep-out cannot pass.

Build the appropriate model, not automatically an enclosure. part.FCMacro is Python executed by FreeCADCmd, not system Python. Use FreeCAD as App, Part, named inputs and reusable construction functions. Import an existing STEP as a reference when useful; include only user-approved input files in the explicit sourceFiles list. Never bundle an entire workspace or hidden credentials.

The macro reads inputs from HARNESS_WORKSPACE, creates the named document objects and saves part.FCStd in the unique HARNESS_BUILD_DIR. Close the document after saving. The runner handles exports, measurements, drawings and the portable bundle. The example's dimensions.json is an editable starting point, not a restriction on new designs. Preserve a user's existing work.

Build and inspect

sh "$FREECAD_SKILLS/freecad/scripts/build-part.sh"

Requires Node 20+ and headless FreeCAD with Part, MeshPart and TechDraw (tested with 1.1.3). The wrapper resolves FREECAD_BIN, the toolchain link, freecadcmd/FreeCADCmd or the installed macOS app. Recent macOS packages put the CLI at FreeCAD.app/Contents/Resources/bin/freecadcmd, not necessarily Contents/MacOS/FreeCADCmd.

The runner reopens the native document and validates its individual solids. Each manufactured part must be one solid; declare disconnected pieces separately. It checks the saved requirements and reimports individual STEP and STL exports. STEP volume, size and position must survive export; STL must be a closed mesh with matching dimensions. Assembly contacts are allowed, but unwanted overlap must be covered by interference/clearance checks. Reference objects are not exported.

Read .harness/geometry.json, inspect the actual assembly in the shared CAD Viewer and review each projected drawing. Inspect access, orientation and assembly sequence as well as dimensions. For revisions, retain unchanged requirements; update requirements only when the brief changes. Rebuild, inspect the changed geometry and report what changed. Never treat a previous render as evidence of a successful new build.

On failure, inspect .harness/build.log or .harness/failed-design.json. A failed measured candidate is shown as candidate.step; the last successful part.step and handoff/ stay unchanged. Fix the model or resolve the brief conflict, not the test threshold. .harness/history/ retains replaced successful artifacts. Do not delete history or a build lock merely to hide an error. A stale lock may be removed only after confirming its owning build is no longer running.

Legacy macros without design.json may still export part.step, but remain ready:false: geometry validity alone is not a checked job. Add requirements before claiming a complete handoff.