How the Develop Branch Powers Active Development in text-to-cad

The develop branch serves as the active development workspace for the earthtojake/text-to-cad repository, utilizing a symlink-driven layout to enable rapid iteration while the main branch remains a pristine, publish-only snapshot.

The develop branch functions as the engine room for the text-to-cad workbench, hosting all day-to-day changes, new skills, bug fixes, and experiments. Unlike the main branch, which contains only self-contained, installable releases, develop employs a sophisticated symlink architecture that links generated output paths back to canonical source directories. This design allows developers to edit a single source file and have changes instantly reflected across all dependent locations.

The Develop Branch vs. Main: A Dual-Branch Strategy

The repository maintains a strict separation between development and production code. The develop branch contains symlinks that point runtime builds, plugin copies, and viewer assets back to canonical source directories such as skills/, viewer/, and packages/. This allows for live, mutable development where changes propagate immediately.

In contrast, the main branch contains real generated files with no symlinks and is designated as publish-only. According to AGENTS.md, no direct pushes or pull requests to main are permitted, ensuring that anyone checking out main receives a fully self-contained, reproducible release.

Understanding the Symlink-Driven Layout

Canonical Sources and Generated Outputs

The symlink architecture requires developers to edit the target of the symlink, not the link itself. When you modify a file under packages/cadpy/src/cadpy/helpers.py, the change instantly appears in dependent locations like skills/your-skill/ or plugins/cad/ because they resolve to the same physical file on disk. This prevents divergent copies and maintains a single source of truth across the repository.

As documented in AGENTS.md (lines 77-78), you must always "edit the source reached by the develop symlink layout first" rather than modifying files within symlinked paths directly.

The setup-symlinks.sh Script

The scripts/dev/setup-symlinks.sh utility creates and validates the symlink tree required for development. Run this script after cloning the develop branch or whenever structural changes occur.

# Clone the repository and check out the develop branch

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

# Create the symlink layout

scripts/dev/setup-symlinks.sh

# Verify symlinks are correctly configured

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

Development Workflow Rules

All feature work must follow the branch-first rule: always start a feature branch from develop and open pull requests back to develop. This guarantees that the symlinked layout used for development is preserved and that CI runs against the correct branch.

# Create a feature branch off develop

git switch -c my-new-skill

# Edit canonical source files (not symlinks)

nano packages/cadpy/src/cadpy/helpers.py

# Stage and commit changes

git add .
git commit -m "Add new CAD helper utilities"

# Push and open PR back to develop

git push -u origin my-new-skill

As noted in CONTRIBUTING.md (lines 65-73), this workflow ensures that the development environment remains consistent across all contributors' machines.

Continuous Integration on Develop

The CI pipeline runs exclusively against the develop branch to validate the symlink layout before testing. According to AGENTS.md (lines 38-46), the test workflow performs the following sequence:

1. Verifies the symlink layout integrity
2. Bundles generated outputs
3. Executes unit and integration tests

This ensures that any change on develop still produces a valid production bundle suitable for merging into main.

# Run the full test suite locally (includes symlink validation)

scripts/test/test.sh

Summary

• The develop branch acts as a live workspace with symlink-driven file resolution, while main remains a frozen, publish-only release.
• Symlinks in develop point generated outputs back to canonical sources in packages/, skills/, and viewer/ directories.
• Always edit the canonical source files rather than files within symlinked paths to prevent code divergence.
• Use scripts/dev/setup-symlinks.sh to initialize or validate the development environment after cloning.
• All pull requests must target develop, never main, ensuring CI validates the symlink layout before release.

Frequently Asked Questions

How do I switch from working on main to develop?

Checkout the develop branch and run the setup script to initialize symlinks. Unlike main, which contains static generated files, develop requires the symlink layout to function correctly. Execute scripts/dev/setup-symlinks.sh immediately after switching branches to ensure all paths resolve properly.

What happens if I edit a file inside a symlinked directory?

Editing files within symlinked paths creates divergent copies that break the single source of truth. According to the repository rules in AGENTS.md, you must navigate to the canonical source (typically under packages/ or skills/) and edit the target file directly. Changes then propagate automatically to all symlinked locations.

Why can't I push directly to main?

The main branch is publish-only and protected to guarantee that every commit represents a fully self-contained, installable release. All development work flows through develop where CI validates symlink integrity and generated bundles. This separation prevents unstable code from reaching production releases.

How does the CI system validate develop branch changes?

The CI workflow defined in the test scripts first verifies that the symlink layout matches the expected structure, then bundles all generated outputs, and finally runs the complete test suite. This three-stage validation ensures that code merged into develop can successfully generate the static files required for main.

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