cadSet/text-to-cad/skills/cad-router/SKILL.md

name, description

name

description

cad-router

Route natural-language CAD, mechanical-part, assembly, 3D-printing, and robot-description requests across text-to-cad, SimpleCADAPI, and CADAM; create one editable model-spec.json per part; convert supplied STEP/STP files into exact-base JSON-controlled models; and enforce generation, modification, validation, visual repair, and CAD Viewer handoff. Use for new or modified STEP/STP, SCAD, STL, 3MF, DXF, URDF, SRDF, SDF, or G-code work when the agent must choose a backend, preserve editable sources, edit JSON model parameters, or parameterize an imported STEP.

CAD Router

Choose a backend before modeling, keep its source as the editable authority, and normalize every result into one handoff contract. Use three projects by role: text-to-cad owns orchestration, general CAD, refinement, validation, repair, and viewing; SimpleCADAPI owns specialized mechanical families; CADAM owns SCAD execution.

Required workflow

1. Convert the request into a brief: part type, dimensions, units, manufacturing intent, required outputs, assembly relationships, editability, and validation targets. Never treat a teacher STEP or a single-case DesignIR as experience. Batch case JSON belongs to the separate CAD Experience plugin. Generation may consume only its promoted schema 2.0 generalized library. Never read cad-experience-plugin/parser/input, parser/output, or private case JSON during creation, modification, or reconstruction.

2. Run the deterministic router from this skill directory:

   python3 scripts/route.py "<request>" --explain
   

   Add explicit signals when known: --output step, --output stl, --manufacturing machining|printing|laser-cutting, --edit-source path/to/source, --existing-model, --assembly, or --browser-controls. The router auto-discovers the workspace cad-experience-library/library.json, infers an experience family and feature roles from the request, and emits a backend-neutral design_plan. Use --experience-library, --experience-family, or repeated --experience-feature only to override those defaults.

3. Follow the selected route unless a hard environmental constraint makes it unavailable. If overriding it, record the reason in the task manifest.

4. Load only the selected backend reference from references/capabilities.md and the matching installed Skill:

   • build123d: use $cad; this is the default for general STEP-first mechanical parts, assemblies, and existing STEP modification.
   • simplecadapi: use an installed SimpleCADAPI Skill/runtime; prefer it for gears, racks, ring gears, bearings, cycloidal parts, reducers, replayable graphs, semantic tags, and FreeCAD interchange.
   • cadam: generate editable .scad, then execute node scripts/cadam_compile.mjs <source.scad> <output.stl|output.dxf>. Set CADAM_ROOT or pass --cadam-root when the CADAM checkout is not beside text-to-cad. Prefer it for fast parametric printable models, repeated patterns, decorative CSG, and parameter controls.

5. When the route reports requirement_refinement or visual_repair, refine the brief, generate, execute, inspect multiple views, and repair no more than three visual mismatch rounds before asking the user.

6. Generate into a task-owned directory and start CAD Viewer with that task directory as --dir; do not expose the repository-wide fixture library for a task review. Write one model-spec.json per part and treat it as the editable geometry contract; keep cad-task.json as the execution record. Read references/model-spec.md before creating, importing, or modifying a model specification. Never change backend during an edit unless conversion is explicitly requested; modify the recorded source of truth. For a supplied STEP/STP without an editable generator, create an exact_step_base specification with scripts/model_spec.py import-step. Preserve the copied STEP as the immutable exact B-Rep base and express later edits as named JSON parameters and modification features. Do not claim that arbitrary STEP recovers its original sketches, constraints, or feature history. For modification, prefer a native Python/SCAD generator. With STEP only, inspect the explicitly supplied model and perform the smallest local feature rebuild possible. For major topology changes, reconstruct from that model under the promoted experience methods while preserving unchanged interfaces. If the request does not name the source part family, inspect the explicit source first and rerun the experience query with --experience-family and --experience-feature; do not guess across family-scoped experience.

7. Validate against the brief. STEP-first routes must run geometry inspection and snapshot review. Mesh routes must check compilation, bounds, solidity/manifold facts when available, and snapshot review. For experience-informed generation, record which generalized methods were applied. Validate against the user's brief and held-out targets, never against parameters exposed from the same source case.

8. Write a cad-task.json manifest using the contract in references/backend-contract.md. Hand supported artifacts to $cad-viewer and return its live links.

Routing rules

• Prefer an explicit user backend when it can produce the required primary format.
• Prefer SimpleCADAPI when a supported standard mechanical factory or replay/semantic requirement materially reduces custom modeling.
• Prefer build123d for general machined parts such as brackets, connecting rods, housings, shafts, flanges, fixtures, and source-driven assemblies.
• Prefer CADAM for SCAD-native, fast printable, pattern-heavy, or interactive-parameter models. Do not choose it when editable STEP is mandatory.
• Route DXF, URDF, SRDF, SDF, G-code, printer, or fabrication handoffs to their focused installed Skills after primary geometry generation.
• Prefer source quality and future modification over the shortest first generation.

V1 boundaries

• Do not promise lossless conversion of feature history between backends.
• Do not treat STL as an editable CAD source when a parametric source or STEP exists.
• Do not claim engineering certification, tolerance analysis, FEA, CAM toolpaths, or manufacturability without separate checks.
• Keep GPL/AGPL backends independently installed and invoked; do not copy their implementation into an MIT-distributed Skill.

References

• Read references/capabilities.md when comparing or invoking backends.
• Read references/backend-contract.md before writing a task manifest or adding another backend.
• Read references/model-spec.md when generating per-part parameter JSON, converting STEP to a JSON-controlled model, or modifying an existing part.
• scripts/capabilities.json is the machine-readable V1 registry used by scripts/route.py.