Text-to-CAD Roadmap: Architecture, Core Skills, and Development Pipeline

The Text-to-CAD roadmap outlines a modular architecture built on agent skills, shared runtime packages, and a seven-step CAD generation pipeline that converts natural language into validated STEP files and robot descriptions.

The earthtojake/text-to-cad repository provides a structured roadmap for building AI-driven CAD generation systems. This open-source project implements a skill-based architecture that bridges natural language processing with precise mechanical design, offering a clear path from text prompts to manufacturable 3D models and robot descriptions.

Three-Layer Architecture

The Text-to-CAD roadmap organizes code into three distinct layers that separate concerns between skill definitions, shared libraries, and generated outputs. This architecture ensures that skills remain lightweight while heavy geometric processing logic stays centralized in reusable packages.

Skill Definitions

Each capability resides in the skills/ directory as an isolated module with its own SKILL.md manifest. These manifests declare CLI entry points, required inputs, and output artefacts. The skills/cad/SKILL.md file defines the canonical CAD generation workflow, while companion skills like skills/cad-viewer/SKILL.md and skills/urdf/SKILL.md handle visualization and robot descriptions.

Shared Runtime Packages

Reusable logic lives in packages/ and is vendored into skills via symlinks. Key packages include:

• packages/cadjs/ – CAD viewer code that powers the web-based visualization
• packages/implicitjs/ – GLSL-based signed-distance-field engine for experimental implicit modeling
• packages/cadpy*/ – Python artefact generators for geometric operations

According to AGENTS.md, the develop branch uses symlinks to map these packages into skills without duplication, allowing you to build once and reference everywhere.

Runtime Artefacts

Generated files store under models/ with support for STEP, STL, 3MF, GLB, URDF, SDF, and SRDF formats. Heavy binary assets like GIF previews and large CAD files are tracked with Git LFS to keep clones lightweight.

Core CAD Skill Pipeline

The primary CAD skill follows a strict, reproducible seven-step workflow defined in skills/cad/SKILL.md. Each step includes specific validation gates to ensure geometric correctness before proceeding.

1. Classify – The system categorizes requests as new parts, assemblies, source-only edits, or direct STEP imports. This routing logic appears in skills/cad/SKILL.md lines 58-64.

2. Load References – The skill pulls only necessary reference files such as references/cad-brief.md to establish design constraints and dimensional requirements.

3. Write Brief – Natural language specifications convert into a formal CAD brief that documents dimensions, units, and manufacturing assumptions.

4. Generate or Import STEP – For new designs, the system executes python scripts/step against a Build123d Python generator. For existing geometry, it imports STEP/STP files directly. This step is documented in skills/cad/SKILL.md lines 46-53.

5. Validate – The scripts/inspect tool queries selectors, planes, facts, and measurements against the geometry. Validation policies are detailed in references/inspection-and-validation.md.

6. Snapshot – A mandatory visual snapshot via scripts/snapshot generates PNG/GIF review packets. Failures must include documented reasons before the workflow can proceed, as specified in references/snapshot-review.md.

7. Handoff – The final artefact path passes to $cad-viewer, which launches the CAD Viewer and returns a permalink for review. This integration is defined in skills/cad/SKILL.md lines 74-80.

Secondary exports to STL, 3MF, and GLB are always derived from the primary STEP output, ensuring a single source of truth for all downstream formats.

Supporting Skills and Tooling

Beyond core CAD generation, the roadmap includes specialized skills for robotics and advanced visualization. These extensions leverage the same shared packages to avoid duplicating geometric logic.

CAD Viewer

The skills/cad-viewer module launches a local Vite server that visualizes STEP, GLB, and G-code files. The viewer reads the ?dir= query parameter to locate the models/ directory and generates permalinks for each artefact, enabling quick design reviews without downloading heavy files. The core runtime that loads these files lives in packages/cadjs/src/lib/viewer/modelRuntime.js.

Robot Description Files

Dedicated skills generate URDF, SRDF, and SDF formats for robotics applications. These files can be inspected in the same CAD Viewer, providing unified visualization for both mechanical parts and complete robot assemblies.

DXF and Implicit CAD

The DXF skill creates 2-D drawings from 3-D geometry, operating outside the STEP-first workflow for legacy manufacturing compatibility. The experimental Implicit CAD skill runs entirely in the browser using GLSL shaders for signed-distance-field modeling, implemented in packages/implicitjs/src/lib/implicitCad.js.

Development Workflow

Contributors work exclusively on the develop branch, opening pull requests against develop rather than main. This branching strategy is enforced to maintain the symlink layout that maps generated runtime artefacts back to source packages.

Testing uses targeted helper scripts under scripts/test/test.sh. Individual JavaScript packages expose their own test suites via npm --prefix packages/cadjs test. The CI pipeline defined in .github/workflows/test.yml runs the full test suite on every push to ensure that changes to shared packages do not break dependent skills.

CLI Quick Start

Generate a simple part from a Build123d Python script:

# From the project directory containing my_part.py

python scripts/step my_part.py --kind part --out part.step
python scripts/inspect refs part.step --facts --planes
python scripts/snapshot part.step
cad-viewer --open part.step

Import an existing STEP file and extract geometric selectors:

python scripts/inspect refs existing_gear.step --selector "#o1.2.f1"

Export secondary formats after STEP generation:

python scripts/step my_assembly.py --kind assembly --out assembly.step
python scripts/export assembly.step --formats stl glb

Summary

• The Text-to-CAD roadmap implements a three-layer architecture separating skill definitions, shared packages, and runtime artefacts.
• The core CAD skill follows a seven-step pipeline from classification through validation to handoff, with STEP as the primary format.
• Supporting skills handle URDF/SRDF robot descriptions, 2-D DXF drawings, and browser-based implicit modeling.
• Development occurs on the develop branch using symlinks to share code between skills without duplication.
• All CLI operations center on scripts/step, scripts/inspect, and scripts/snapshot for reproducible geometric workflows.

Frequently Asked Questions

What is the Text-to-CAD roadmap?

The Text-to-CAD roadmap is the architectural blueprint for the earthtojake/text-to-cad repository, defining how AI agents convert natural language into manufacturable CAD files. It specifies a modular skill system, shared runtime packages, and a rigorous seven-step validation pipeline that ensures geometric accuracy before any file reaches production.

How does the seven-step pipeline ensure model quality?

Each step includes mandatory validation gates. The scripts/inspect tool verifies geometric facts and measurements against the brief, while scripts/snapshot requires visual confirmation with documented failure reasons. By enforcing STEP as the primary format and deriving all other exports from it, the pipeline maintains a single source of truth that prevents format drift.

What file formats does Text-to-CAD support?

The system generates STEP as the canonical format, then derives STL, 3MF, and GLB for manufacturing and visualization. It also produces URDF, SRDF, and SDF for robotics, plus DXF for 2-D drawings. The CAD Viewer in packages/cadjs can display STEP, GLB, and G-code files directly in the browser.

How do I set up the development environment?

Clone the repository and switch to the develop branch. The project uses symlinks to map shared packages from packages/ into individual skills, as documented in AGENTS.md. Run scripts/test/test.sh to verify your setup, and use npm --prefix packages/cadjs test to test specific JavaScript components. Ensure Git LFS is installed to handle binary assets in models/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}