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

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

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

Viewer Dependencies

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

npm --prefix viewer install

Linking Skills for Local Testing

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

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 to maintain repository quality.

Running Skills Locally

Test individual CAD skills using the isolated skill interpreter:

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

scripts/test/test.sh

For viewer-specific tests:

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 file specifies that skills must include a SKILL.md file (e.g., 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:

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 – Detailed local workflow, symlink handling, and specific testing commands
• AGENTS.md – Repository-level rules, branch policy, and the release process requirements
• packages/cadpy/README.md – Documentation for the shared Python CAD runtime
• skills/<skill>/SKILL.md – Per-skill documentation standards (see skills/cad/SKILL.md for examples)
• 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 and scripts/test/test.sh for consistent local setup.
• Include documentation: Every skill requires a 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 and 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 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 file in its root directory (e.g., 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.

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