How to Contribute to text-to-CAD: A Complete Guide for Developers

Contributing to text-to-CAD requires branching from the develop branch, setting up a Python 3.12 virtual environment, linking skills to your local agent via scripts/install/install-skills.sh, and opening pull requests against develop rather than main.

The text-to-CAD repository by earthtojake is organized as a workbench for CAD-related agent skills. Contributions follow a strict workflow that keeps the develop branch as the active development line while reserving main for publish-only releases. This guide covers the repository architecture, setup procedures, and validation steps needed to submit successful contributions.

Repository Architecture

The codebase is divided into distinct areas, each serving a specific purpose in the agent skill ecosystem.

Skills house individual agent capabilities for CAD generation, URDF, SDF, and more. Each skill lives under skills/<skill>/ and contains a SKILL.md instruction file plus a references/ folder for documentation.

Packages contain shared Python and JavaScript helpers used by multiple skills, such as cadpy and cadpy_metadata. These live in packages/ and are built into each skill's runtime.

Viewer powers the $cad-viewer skill through an editable CAD Viewer application located in viewer/.

Models store fixture and generated CAD/robot artifacts (STEP, STL, GLB, etc.) under models/, with access enforced by a file-policy.

Scripts provide repo-wide utilities for installation, testing, bundling, and release in scripts/.

Docs contain the public documentation site source at docs/.

Tests include unit and integration tests for skills, packages, and the viewer in tests/.

Branch Strategy and Policies

According to AGENTS.md, all feature work branches from develop and targets develop in pull requests. The main branch contains only generated production outputs with no symlinks and is never the target of direct commits. Contributors must never bump the VERSION file directly, as releases are performed via the GitHub Release workflow by maintainers only.

Contribution Workflow

Follow these steps to set up your environment and submit changes.

1. Create a Local Checkout on develop

Start by cloning the repository and creating a feature branch from develop:

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

2. Set Up the Python Environment

The project requires Python 3.12. Create a virtual environment and install development dependencies:

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

The dev requirements automatically pull source packages from packages/.

3. Install Viewer Dependencies (Optional)

If you are working on the CAD Viewer, install Node.js dependencies:

npm --prefix viewer install

4. Link Skills Into Your Agent

Run the install script to create symlinks that allow your local agent to see skills without copying files:

scripts/install/install-skills.sh --agent codex

This creates one symlink per skill. Supported agents include codex and other compatible platforms.

5. Run Skills and Tests

Execute a specific skill CLI:

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

Run Python unit tests:

./.venv/bin/python -m unittest tests/python/skills/urdf/test_cli.py

6. Validate Your Changes

Use the smallest applicable check before running the full suite:

# Verify symlink layout

scripts/dev/setup-symlinks.sh --check

# Run all repository tests

scripts/test/test.sh

# Run viewer unit tests

npm --prefix viewer run test

7. Open a Pull Request

Target the develop branch. The CI pipeline performs the following checks:

• Verifies symlink layout integrity
• Bundles generated outputs via scripts/bundle/bundle.sh --check
• Runs the complete test suite
• Validates the file-policy for models/

When all checks pass, a maintainer will merge into develop.

Adding a New CAD Skill

To create a new skill, establish the directory structure and required files:

# Create skill directory

mkdir -p skills/my-new-cad

# Add the instruction file

cat > skills/my-new-cad/SKILL.md <<'EOF'
---
name: my-new-cad
description: Example skill that demonstrates contribution steps.
---

# My New CAD Skill

...
EOF

# Add reference documentation

mkdir -p skills/my-new-cad/references
touch skills/my-new-cad/references/overview.md

Each skill must include a SKILL.md with YAML frontmatter defining the name and description, plus a references/ folder for supporting documentation.

Running Full CI Checks Locally

Before submitting, replicate the CI validation:

# Verify symlink layout matches AGENTS.md requirements

scripts/dev/setup-symlinks.sh --check

# Run all repository tests

scripts/test/test.sh

# Check generated outputs and bundling

scripts/bundle/bundle.sh --clean
scripts/bundle/bundle.sh --check

Key Files for Contributors

• README.md - High-level project overview, skill table, and install commands
• CONTRIBUTING.md - Full contributor guide covering checkout, environment setup, linking, and testing
• AGENTS.md - Repository-wide rules about branch policies and symlink layout requirements
• skills/<skill>/SKILL.md - Canonical instruction file for each skill (e.g., skills/cad/SKILL.md)
• packages/*/README.md - Documentation for shared packages (e.g., packages/cadpy/README.md)
• scripts/install/install-skills.sh - Installer that creates symlinks for local agents
• scripts/bundle/bundle.sh - Bundles generated production outputs and validates them
• tests/python/ - Unit tests for skills and packages

Summary

• Branch from develop - Never target main directly; it contains only generated production outputs
• Use Python 3.12 - Create a virtual environment and install requirements-dev.txt for dependencies
• Link skills locally - Run scripts/install/install-skills.sh to create symlinks for agent testing
• Validate before PRs - Check symlinks, run scripts/test/test.sh, and verify bundling
• Follow the file structure - Place new skills in skills/<name>/ with SKILL.md and references/ folder
• Don't modify VERSION - Releases are handled automatically by maintainers via GitHub workflows

Frequently Asked Questions

What Python version does text-to-CAD require?

The repository requires Python 3.12 specifically. Set up your environment using python3.12 -m venv .venv before installing dependencies from requirements-dev.txt. The development requirements pull source packages from the packages/ directory automatically.

Why can't I commit directly to the main branch?

The main branch contains only generated production outputs with no symlinks and is reserved for publish-only releases. As specified in AGENTS.md, all development work must branch from and target the develop branch. This separation ensures the main branch always represents stable, bundled artifacts while develop remains the active integration line.

How do I test my skill changes without copying files?

Use the scripts/install/install-skills.sh script with the --agent flag (e.g., --agent codex) to create symlinks between the repository skills and your local agent environment. This allows the agent to reference the latest code directly from skills/ without file duplication, enabling real-time testing of modifications.

What checks run in the CI pipeline?

The CI pipeline validates symlink layout via scripts/dev/setup-symlinks.sh --check, bundles generated outputs using scripts/bundle/bundle.sh --check, runs the full test suite with scripts/test/test.sh, and enforces the file-policy for the models/ directory. These checks ensure repository integrity before merging into develop.

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