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

> Explore the Text-to-CAD roadmap, detailing its modular architecture, essential skills, and a seven-step pipeline to convert natural language into validated STEP files and robot descriptions.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: roadmap
- Published: 2026-08-04

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) manifest. These manifests declare CLI entry points, required inputs, and output artefacts. The [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) file defines the canonical CAD generation workflow, while companion skills like [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md) and [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) lines 58-64.

2. **Load References** – The skill pulls only necessary reference files such as [`references/cad-brief.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/.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:

```bash

# 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:

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

```

Export secondary formats after STEP generation:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md). Run [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/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/`.