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

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, link skills using 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), and thin entry-point scripts. Each skill must include a 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 and CONTRIBUTING.md. These laws are enforced by CI checks in tests/python/global/test_package_boundaries.py and 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. 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 test suite validates this isolation.

No Symlinks in Releases

The repository never ships symlinks in releases. The 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:

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:

npm --prefix apps/viewer install

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

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 file, a 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:

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:

./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 files:

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. If you modified any 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/:

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

├── requirements.txt        # Pin current cadgen version

└── my_skill.py             # Entry-point script

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

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

./.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:

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, and running scripts/install/install-skills.sh for local testing.
• Testing must include 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 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 and 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 for the full suite, or use ./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 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, skills must only import from the shared cadgen distribution declared in their requirements.txt. Cross-skill imports violate the architectural boundaries and will fail the 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 files in skills/ must pin cadgen to the version specified in this file. The scripts/release/check-version.sh script validates this consistency during CI, and the release workflow automatically bumps VERSION when merging approved changes.

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