How the Symlink Layout in text-to-cad Enables Seamless Development

The symlink layout in the develop branch creates symbolic links from consumer directories like viewer/packages/ and plugins/cad/skills/ back to the true source trees in packages/ and skills/, enabling instant code propagation across the entire codebase while ensuring production bundles remain self-contained.

The earthtojake/text-to-cad repository implements a sophisticated symlink layout to streamline development workflows for CAD agents. In the develop branch, directories such as viewer/packages/*, plugins/cad/skills/*, and generated runtime paths are not duplicated copies but symbolic links pointing to canonical source locations. This architecture, documented in AGENTS.md, eliminates file redundancy and ensures that modifications to source files immediately reflect across all consumers including the viewer, plugins, and skill runtimes.

Core Benefits of the Development Symlink Layout

Single Source of Truth for All Components

The symlink layout establishes one canonical location for every shared module. Files under viewer/packages/* and plugins/cad/skills/* are symbolic links to the original code residing in packages/ or skills/. When you edit packages/cadjs/src/render.js, the change is instantly visible to the viewer because viewer/packages/cadjs links directly to that directory. This eliminates version drift between copies and reduces maintenance overhead across the monorepo.

Rapid Iteration with Automated Setup

The repository provides scripts/dev/setup-symlinks.sh to create the entire development layout in a single step. This script orchestrates scripts/dev/setup-skill-symlink.sh for individual skills and scripts/dev/setup-plugin-symlink.sh for plugin directories, outputting "Development symlink layout is ready." upon completion. Developers can validate the integrity of these links without modifying anything by running the script with the --check flag, which ensures no broken links exist before executing tests.

Guaranteed Production Integrity

While symlinks accelerate development, they never reach production. The bundling pipeline in scripts/bundle/bundle.sh executes an assert_no_symlinks check that fails the build if any symbolic links remain. The bundle process replaces all symlinks with concrete file copies, ensuring that released artifacts are self-contained and portable. This strict separation prevents accidental dependencies on the development filesystem structure.

Isolated Skills with Shared Resources

Each skill lives independently under skills/ and is linked into plugins/cad/skills/ via dedicated symlink scripts. This isolation allows the skill runtime to access shared helpers in packages/ while keeping skill-specific code separate. Large generated assets, such as CAD meshes stored in models/, are referenced through symlinks rather than duplicated across runtimes, keeping the repository lightweight and storage-efficient.

Working with the Symlink Layout

To establish the development environment, execute the setup script from the repository root:

scripts/dev/setup-symlinks.sh

This command sets up skill symlinks, creates plugin symlinks, and prints confirmation when the layout is ready.

To verify that all symbolic links are intact without modifying the filesystem:

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

If a link is broken, the script returns a specific error indicating which path/to/link must be a symlink to expected/target, allowing you to repair the layout before running tests.

When editing code, work directly in the source trees. For example, modifying packages/cadjs/src/render.js immediately affects any viewer command because viewer/packages/cadjs is a symlink to that source directory:

# Edit the actual source

nano packages/cadjs/src/render.js

# Run viewer tests—the changes are live immediately

npm --prefix viewer run test

Building Production Bundles

When preparing a release, the bundle script ensures no symlinks persist in the final artifact:

scripts/bundle/bundle.sh

During execution, the script validates that all symbolic links have been replaced with physical copies. This guarantees that the production package contains no external dependencies on the development directory structure, creating a clean, reproducible artifact suitable for distribution.

Summary

• The symlink layout establishes a single source of truth by linking viewer/packages/* and plugins/cad/skills/* to canonical source directories in packages/ and skills/.
• scripts/dev/setup-symlinks.sh automates the creation and validation of development links, while scripts/bundle/bundle.sh ensures production builds contain only concrete files.
• Editing source files propagates changes instantly to all consumers without file copying, enabling rapid iteration across the viewer and plugins.
• Large assets remain in models/ and are referenced via symlinks to minimize repository bloat and prevent duplication.
• The --check flag validates link integrity, preventing hard-to-debug issues caused by broken symbolic references.

Frequently Asked Questions

What happens if a symlink breaks during development?

Running scripts/dev/setup-symlinks.sh --check detects broken links immediately and returns a specific error message indicating which path must be a symlink to its expected target. This allows developers to repair the layout before running tests or builds, preventing runtime errors caused by missing dependencies.

Why does the production build remove all symlinks?

Production bundles must be self-contained and portable across different filesystems. The scripts/bundle/bundle.sh script explicitly asserts that no symlinks exist using assert_no_symlinks and replaces them with physical copies, ensuring the artifact contains all necessary files without external dependencies on the development machine's directory structure.

How does the symlink layout handle large binary assets like CAD models?

Large generated assets stored in models/ are never duplicated across runtimes. Instead, components reference the single canonical copy through symlinks, significantly reducing storage requirements and ensuring that all viewers and plugins use identical asset versions without wasting disk space.

Can I manually create symlinks instead of using the setup script?

While technically possible, manual symlink creation risks path inconsistencies and incomplete coverage. The scripts/dev/setup-symlinks.sh script orchestrates setup-skill-symlink.sh and setup-plugin-symlink.sh to ensure correct relative paths and complete layout coverage, making it the recommended and maintained approach according to the repository's AGENTS.md guidelines.

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