# How to Contribute to the text-to-cad Project: A Complete Developer Guide

> Learn how to contribute to the text-to-cad project by following this developer guide. Fork the repo, set up your environment, and understand core design laws for successful pull requests.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-09-13

---

**To contribute to the text-to-cad project, fork the `earthtojake/text-to-cad` repository, set up a Python 3.12 virtual environment with [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt), link skills using [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh), and adhere to the three core design laws—Skill Isolation, Ships-Alone, and No Symlinks—before submitting a pull request that passes the full CI test matrix.**

The `text-to-cad` repository is a workbench of agent skills designed for generating, inspecting, and handing off CAD and robot-description artifacts. Before you contribute to the text-to-cad project, you must understand its unique architectural constraints that enforce strict boundaries between skills and shared packages. The repository uses a monorepo structure where the canonical version is stored in the root `VERSION` file and all sub-packages derive their versioning from this single source.

## Repository Architecture Overview

The codebase is organized into five distinct directories, each with specific responsibilities and contribution requirements.

- **`skills/`** – Contains individual skill definitions, reference documentation ([`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md)), and thin entry-point scripts. Each skill must include a [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) that pins the current `cadgen` version.
- **`packages/`** – Houses shared runtime libraries. The `packages/cadgen` directory builds the publishable PyPI wheel, while `packages/cadgen-js` provides the JavaScript runtime used by the viewer.
- **`apps/viewer/`** – A React client for the CAD Viewer with its backend implementation living in `cadgen.viewer` inside `packages/cadgen`.
- **`models/`** – Stores the fixture corpus of LFS-tracked CAD assets and example projects used by tests and documentation.
- **`scripts/`** – Durable repository-level commands including installers, test runners, and bundlers.

## The Three Core Design Laws

All contributions must respect the architectural constraints defined in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) and [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md). These laws are enforced by CI checks in [`tests/python/global/test_package_boundaries.py`](https://github.com/earthtojake/text-to-cad/blob/main/tests/python/global/test_package_boundaries.py) and [`scripts/github-workflows/check-builds.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/github-workflows/check-builds.sh).

### Skill Isolation

**Skills must never import another skill or any repository-root module at runtime.** Each skill depends solely on the shared `cadgen` distribution, declared explicitly in its [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt). This ensures that skills operate as independent units without circular dependencies or implicit coupling.

### Ships-Alone

The `packages/cadgen` distribution must build a wheel that functions entirely outside the repository context. This constraint guarantees that the core library is self-contained and publishable to PyPI without requiring the full monorepo structure. The [`test_package_boundaries.py`](https://github.com/earthtojake/text-to-cad/blob/main/test_package_boundaries.py) test suite validates this isolation.

### No Symlinks in Releases

The repository never ships symlinks in releases. The [`scripts/github-workflows/check-builds.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/github-workflows/check-builds.sh) script validates this constraint during the CI pipeline to ensure cross-platform compatibility and clean distribution artifacts.

## Setting Up Your Development Environment

Prepare your local environment with Python 3.12 and Node.js for full development capabilities.

First, clone the repository and create a virtual environment:

```bash
git clone https://github.com/earthtojake/text-to-cad.git
cd text-to-cad
git switch -c my-feature-branch

python3.12 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements-dev.txt

```

For Viewer development, install JavaScript dependencies:

```bash
npm --prefix apps/viewer install

```

Link skills for local agent testing using the provided installer script:

```bash
scripts/install/install-skills.sh --agent codex
scripts/install/install-skills.sh --list-agents  # Verify links

```

## Step-by-Step Contribution Workflow

### 1. Implement Your Changes

**Adding a new skill** requires creating a new folder under `skills/`, adding a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file, a [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) pinning the current `cadgen==<VERSION>` from the root `VERSION` file, and an entry-point script. Follow the pattern established by existing skills such as `skills/cad/` or `skills/urdf/`.

**Modifying shared code** in `packages/` requires running the bundler to regenerate runtime assets:

```bash
scripts/bundle/bundle.sh
git add packages/cadgen/_runtime

```

**Updating documentation or examples** involves adding Markdown files in `docs/` or assets under `models/`. Ensure large binary files are LFS-tracked.

### 2. Run Tests Locally

Validate your changes against the full test suite before committing:

```bash
./scripts/test/test.sh               # Full suite

./scripts/test/test-python.sh        # Python-only tests

npm --prefix packages/cadgen-js test # JavaScript unit tests

npm --prefix apps/viewer run test    # Viewer tests

```

### 3. Commit and Submit

Stage your changes and ensure version consistency across all [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) files:

```bash
git add .
git commit -m "feat: add <description>"
git push -u origin my-feature-branch

```

Open a pull request targeting the `main` branch. The CI pipeline automatically runs the full test matrix and version checks via [`scripts/release/check-version.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/release/check-version.sh). If you modified any [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) files, ensure the pinned `cadgen` version matches the repository's `VERSION` file exactly.

## Code Examples for Common Tasks

### Creating a Minimal Skill Skeleton

Create the directory structure under `skills/`:

```text
skills/my-skill/
├── SKILL.md                # Human-readable description

├── requirements.txt        # Pin current cadgen version

└── my_skill.py             # Entry-point script

```

The [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) must specify the exact version from the root `VERSION` file:

```

cadgen==0.5.2   # keep in sync with repo VERSION

```

The entry-point script imports only from `cadgen`:

```python
#!/usr/bin/env python3
from cadgen.cli import some_shared_verb

def main():
    # Your skill logic here

    print("Hello from my-skill!")

if __name__ == "__main__":
    main()

```

### Running a Skill via CLI

After linking the skill to your agent:

```bash
./.venv/bin/python -m cadgen.cli my-skill <subcommand> --help

```

### Building the Viewer Runtime

When modifying JavaScript code in `packages/cadgen-js` or `apps/viewer`, rebuild the runtime:

```bash
scripts/bundle/bundle.sh          # Rebuild cadgen-js runtime

git add packages/cadgen/_runtime  # Stage regenerated assets

```

## Summary

- **Repository structure** splits code into `skills/`, `packages/`, `apps/viewer/`, `models/`, and `scripts/` with strict separation concerns.
- **Three design laws** govern all contributions: Skill Isolation (no cross-skill imports), Ships-Alone (`packages/cadgen` must work independently), and No Symlinks.
- **Development setup** requires Python 3.12, [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt), and running [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) for local testing.
- **Testing** must include [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) and specific suite runners for Python and JavaScript changes.
- **Version management** uses the root `VERSION` file as the single source of truth; all [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) files must pin `cadgen` to this version.

## Frequently Asked Questions

### What are the three core design laws in text-to-cad?

The three laws are **Skill Isolation** (skills cannot import other skills or repo-root modules), **Ships-Alone** (`packages/cadgen` must build a working wheel outside the repo), and **No Symlinks** (releases never contain symbolic links). These are enforced by [`tests/python/global/test_package_boundaries.py`](https://github.com/earthtojake/text-to-cad/blob/main/tests/python/global/test_package_boundaries.py) and [`scripts/github-workflows/check-builds.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/github-workflows/check-builds.sh) in the CI pipeline.

### How do I test my changes locally before submitting a PR?

Run [`./scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/./scripts/test/test.sh) for the full suite, or use [`./scripts/test/test-python.sh`](https://github.com/earthtojake/text-to-cad/blob/main/./scripts/test/test-python.sh) for Python-only validation. For JavaScript modifications, execute `npm --prefix packages/cadgen-js test` and `npm --prefix apps/viewer run test`. Always ensure [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) completes successfully if you modified shared packages.

### Can skills import utilities from other skills?

No. According to the **Skill Isolation** law documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), skills must only import from the shared `cadgen` distribution declared in their [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt). Cross-skill imports violate the architectural boundaries and will fail the [`test_package_boundaries.py`](https://github.com/earthtojake/text-to-cad/blob/main/test_package_boundaries.py) checks.

### How does versioning work across the monorepo?

The root `VERSION` file serves as the single source of truth for the entire repository. All [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) files in `skills/` must pin `cadgen` to the version specified in this file. The [`scripts/release/check-version.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/release/check-version.sh) script validates this consistency during CI, and the release workflow automatically bumps `VERSION` when merging approved changes.