# Text-to-CAD Contributing Guidelines: How to Contribute to the earthtojake/text-to-cad Repository

> Learn how to contribute to the earthtojake/text-to-cad repository. Follow our guidelines for the develop branch, symlink layout, and self-containment rules to ensure a smooth contribution process.

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

---

**The earthtojake/text-to-CAD repository requires contributors to work on the `develop` branch using a symlink-based layout, maintaining strict self-containment rules where skills cannot import from other skills or the repository root.**

This guide covers the complete **Text-to-CAD contributing guidelines** for the earthtojake/text-to-cad repository, a workbench of CAD-related agent skills. Whether you are adding new capabilities to the skill library, improving the browser-based viewer, or extending shared CAD utilities, you must follow the repository’s three-layer architecture and branch-specific workflows to ensure clean integration.

## Repository Architecture Overview

The repository organizes code into three distinct logical layers to enforce separation of concerns and runtime isolation.

### Skills Layer (`skills/`)

Individual, self-contained agent capabilities live under `skills/`. Each skill—such as CAD generation, URDF creation, or G-code slicing—operates independently with its own dependencies and documentation. According to the repository rules in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), a skill must not import code from other skills or from the repository root at runtime. All shared functionality must reside in `packages/` and be vendored into each skill during the bundling process.

### Shared Packages (`packages/`)

Reusable runtime helpers reside in `packages/`, including `cadpy` for Python-based STEP handling and `cadjs`/`implicitjs` for JavaScript rendering tasks. These packages provide the common CAD primitives that skills consume without creating cross-skill dependencies.

### CAD Viewer (`viewer/`)

The browser-based CAD Viewer previews CAD, robot, and G-code artifacts. This component requires Node.js dependencies and follows its own build pipeline separate from the Python skill environment.

## Branch Strategy and Symlink Layout

The repository uses a dual-branch strategy to separate development from production. The `develop` branch contains the canonical source directories (`skills/`, `packages/`, `viewer/`) and uses a **symlink layout** so edits propagate automatically to generated output locations. The `main` branch contains real copies of those outputs and is publish-only, updated exclusively through the automated release workflow.

When contributing, always clone the `develop` branch. The symlink system ensures that your changes in the canonical directories reflect immediately in the locations where the agent expects to find them, without requiring manual copying.

## Setting Up Your Development Environment

You need both Python and Node.js environments configured to work across the full stack.

### Python Environment Setup

Create an isolated Python 3.12 environment and install development dependencies:

```bash
python3.12 -m venv .venv
pip install -r requirements-dev.txt

```

### Viewer Dependencies

For CAD Viewer contributions, install Node dependencies using the prefix flag:

```bash
npm --prefix viewer install

```

### Linking Skills for Local Testing

Use the installation script to symlink skills into your local agent workspace:

```bash
scripts/install/install-skills.sh --agent codex --all

```

This command creates symlinks for all skills, allowing you to test changes without reinstalling packages.

## Contribution Workflow

Follow the iterative loop described in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) to maintain repository quality.

### Running Skills Locally

Test individual CAD skills using the isolated skill interpreter:

```bash
./.venv/skills/cad/bin/python skills/cad/scripts/step --help

```

This invokes the skill-specific Python environment with access only to its vendored packages, enforcing the self-containment requirement.

### Testing Changes

Run the comprehensive test suite using the provided scripts:

```bash
scripts/test/test.sh

```

For viewer-specific tests:

```bash
npm --prefix viewer run test

```

Or run Python unittest commands directly for specific skill modules.

### Development Standards

Keep skill instructions narrow and focused. Add reference documentation under `references/` within your skill directory, and update test fixtures in `models/` when modifying generation logic. The [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) file specifies that skills must include a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file (e.g., [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)) documenting the capability’s interface and parameters.

## Release Automation and Versioning

The repository includes CI/CD pipelines for release automation, model uploads, and viewer deployment. The `Release` workflow builds from `develop`, publishes to `main`, and creates a GitHub Release while ensuring version consistency via the `VERSION` file at the repository root. Do not manually modify `main` or the `VERSION` file; the automation handles these updates.

### Running the CAD Viewer in Development

Preview changes locally before submitting:

```bash
npm --prefix viewer run dev -- --host 127.0.0.1

```

This starts the development server on localhost for immediate visual feedback.

## Key Contribution Files

Reference these files when preparing contributions:

- **[`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md)** – Detailed local workflow, symlink handling, and specific testing commands
- **[`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)** – Repository-level rules, branch policy, and the release process requirements
- **[`packages/cadpy/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/README.md)** – Documentation for the shared Python CAD runtime
- **`skills/<skill>/SKILL.md`** – Per-skill documentation standards (see [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) for examples)
- **[`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh)** – The canonical script for linking skills into local agents

## Summary

- **Work on `develop`**: The `develop` branch contains canonical sources with symlink layouts; `main` is publish-only via automated releases.
- **Maintain self-containment**: Skills cannot import from other skills or the repository root; use `packages/` for shared code.
- **Use provided scripts**: Leverage [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) and [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) for consistent local setup.
- **Include documentation**: Every skill requires a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file and should reference docs under `references/`.
- **Respect the VERSION file**: Version bumps are handled automatically by the Release workflow; do not manually edit.

## Frequently Asked Questions

### What is the difference between the `develop` and `main` branches in text-to-CAD?

The `develop` branch contains the canonical source code with a symlink layout that allows live editing, while `main` contains real copies of generated outputs and serves as the publish-only branch updated exclusively through automated release workflows.

### Can skills in the text-to-CAD repository share code with each other?

No. According to the repository architecture 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), skills must remain self-contained and cannot import from other skills or the repository root. All shared functionality must reside in `packages/` (such as `cadpy`) and be vendored into individual skills during the build process.

### How do I test my changes before submitting a contribution?

Run `./.venv/skills/cad/bin/python skills/cad/scripts/step --help` to test individual skills, execute [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) for the full suite, and use `npm --prefix viewer run test` for viewer components. Additionally, link skills locally with `scripts/install/install-skills.sh --agent codex --all` to verify integration.

### Where should I add documentation for a new CAD skill?

Each skill requires a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file in its root directory (e.g., [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)) describing the capability's interface. Additionally, place reference documentation under the skill's `references/` directory and update test fixtures in `models/` to reflect expected outputs.