AGENTS.md

This repo is a workbench for CAD-related agent skills. Treat skills/ as the product and models/ as the shared fixture/artifact area.

Branch And Layout First

Before changing code, branch from develop, not main; PRs should target develop. Do not start development work from main. The develop branch intentionally uses symlinks across generated runtime, viewer-local package, and plugin package paths. When a path is symlinked, follow the link and edit the source target. Use main as the production clone/release branch only. main is publish-only: do not open PRs to main or push it directly.

Release Workflow

Do not bump the canonical release version in plugins/cad/VERSION during normal development work. Ship releases only through the single Release GitHub Actions workflow, which handles the version bump, release PR, publish commit to main, models upload, web-app deploys, semver tag, and GitHub Release in one run.

When asked to publish, make, or ship a release, dispatch Release with its defaults: build from develop (base_branch=develop), publish to main (target_branch=main), and publish the GitHub Release (publish=true, not a draft). Never pick the semver bump yourself: if the request does not name patch, minor, major, or an exact version, ask which one before dispatching. Use target_branch=build-test only when the user explicitly asks to test CI/CD or build-pipeline changes — never by default and never as part of a requested release. Rerun Release with set_version pinned to the current version to resume a failed publish.

The standalone Deploy Docs and Deploy Viewer workflows redeploy the individual web apps from main, and the standalone Upload Models workflow uploads the models/ catalog to Vercel Blob from develop, all without running a release. main is publish-only; pushing develop runs tests but never publishes. See the Releases section in CONTRIBUTING.md for the full flow, CI/CD-testing and resume options, and local/manual fallbacks.

Repo Map

skills/: agent skills and their references/scripts.
plugins/: versioned agent plugin packages that bundle repo skills.
models/: sample and durable CAD/robot-description fixtures.
viewer/: editable CAD Viewer source app.
packages/cadjs: shared JS CAD/render/runtime code, UI-framework agnostic.
packages/implicitjs: standalone JS implicit CAD model, shader render, snapshot, mesh sampling, and export runtime.
packages/cadpy: shared Python STEP/GLB/topology artifact code.
packages/cadpy_metadata: dependency-free Python metadata helpers vendored into generated URDF/SRDF/SDF skill runtimes.
docs/: documentation site.
tests/: root-owned test suites for skills, packages, viewer services, and repo-wide policy.
scripts/: durable repo commands grouped by purpose.

Repo Rules

Keep root guidance short. Put domain workflows, CLI details, and validation policy in the relevant skills/<skill>/SKILL.md or references/ file.
Keep relevant Markdown docs current when changing behavior, commands, or repo layout, but do not bloat AGENTS.md; use it only for durable repo-level rules and pointers.
Read CONTRIBUTING.md before committing, rebasing, resolving generated-file conflicts, or bumping release versions.
Keep the primary local develop checkout in symlink layout with scripts/dev/setup-symlinks.sh. Do not auto-repair that layout from Codex or Claude Code startup hooks in linked worktrees.
Each skill must be self-contained and independent at runtime. A skill must not refer to or import or depend on code from another skill, from skills/ root, or from repository-root modules. Do not add skills/, the repository root, or sibling skill directories to sys.path, PYTHONPATH, NODE_PATH, or similar runtime lookup paths. Shared runtime helpers must live under packages/ as the source of truth and be vendored/generated from there into each consuming skill runtime; do not keep shared helper modules directly under skills/.
Edit the source reached by the develop symlink layout first, then regenerate explicit derived outputs when a production-output task requires it.
Write all test, sample, permanent, and generated CAD/robot-description artifacts under models/, including STEP/STP, STL, GLB, DXF, URDF, SRDF, SDF, and G-code outputs. Do not create ad hoc artifact directories elsewhere.
Reserve scripts/ for durable repo commands. Do not write temporary, one-off, or local-only helper scripts there; use tmp/ or /tmp instead.
Development symlinks mark generated or copied paths. If a file is under a symlinked runtime, viewer package, or plugin package path, edit the symlink target/source path instead of treating the copy as independent.
When source changes affect generated runtimes or plugin packages, refresh or check them with the master bundle wrapper, scripts/bundle/bundle.sh. Use lower-level bundle scripts only when debugging the wrapper itself.
packages/cadjs must stay reusable/non-React; app UI and workflow state belong in viewer/.
packages/implicitjs must stay reusable/non-React and independent of packages/cadjs; CAD Viewer and snapshot tools should consume its shared render/export APIs instead of duplicating implicit CAD logic.
packages/cadpy owns reusable Python artifact generation; skills should use bundled package code, not sibling skill imports.
Create lightweight shared Python packages under packages/cadpy_* when a helper should not inherit heavier package dependencies.
Use path-targeted search, validation, and git status; avoid broad scans over generated CAD/LFS artifacts unless the task requires them.
Treat plugins/cad/VERSION as the canonical release version. Do not hand-edit duplicate package, plugin, lockfile, or Python pyproject.toml versions; release preparation and scripts/bundle/bundle.sh stamp them from the canonical version.

Environments

Prefer ./.venv/bin/python for CAD Python work.
Keep new branch checkouts and git worktrees lightweight by default. Do not copy .venv/ or models/ through .worktreeinclude; recreate .venv/ inside the worktree only when Python dependencies are needed for the workflow.
In Codex or Claude Code worktrees, prefer the skill instructions and scripts under the current worktree's skills/ directory over globally installed skill symlinks from another checkout.
If a worktree explicitly needs the development symlink layout, run scripts/dev/setup-symlinks.sh --check and then scripts/dev/setup-symlinks.sh intentionally in that worktree.
Hydrate models/ only when the user asks for it or when the task targets specific files under models/. In a new worktree, make the relevant model paths real before using them, preferring the local Git LFS cache with git lfs checkout <path> or git lfs checkout models. Download missing LFS objects only when explicitly requested or required after confirming the local cache is missing them.
Install dependencies only for the workflow being changed.
Do not commit .venv/, node_modules/, caches, tmp/, local credentials, or printer config.

Checks

Run the smallest path-targeted check that covers the change. Use broad wrappers when touching shared surfaces or before handoff:

Code tests: scripts/test/test.sh
- In GitHub Actions, test.yml checks the canonical release version as a separate non-blocking job; its test job verifies the develop symlink layout, bundles temporary production outputs, and runs docs and code tests against that bundle. main writes are validated by the Release workflow's publish job; GitHub branch settings should block PRs and direct pushes to main.
Focused test runners: scripts/test/test-js.sh, scripts/test/test-docs.sh, scripts/test/test-python.sh, scripts/test/test-global.sh
Development symlink layout: scripts/dev/setup-symlinks.sh --check
Canonical release version: scripts/release/check-version.sh
Generated runtime and plugin freshness: scripts/bundle/bundle.sh --check
CAD Viewer, packages/cadjs, or packages/implicitjs: npm --prefix packages/cadjs test, npm --prefix packages/implicitjs test, npm --prefix viewer run test, npm --prefix viewer run build
Docs site: npm --prefix docs run check
Targeted Python tests: ./.venv/bin/python -m unittest <changed test paths>

When a task intentionally writes production outputs locally, run scripts/bundle/bundle.sh, rerun scripts/bundle/bundle.sh --check, and restore the development symlink layout afterward if you are continuing on develop.

CAD Viewer

When reviewing repo fixtures in CAD Viewer, point the Viewer at the repo models/ directory with an absolute ?dir= path; keep any permanent or generated CAD/robot-description files in models/ so the viewer catalog and artifacts stay in one place.

Start or reuse the Viewer through the cad-viewer skill launcher and use the base URL it prints. The launcher owns port selection, reuses a compatible live Viewer for the same worktree/branch, and uses the source app in Vite dev mode when the skill viewer path is a development symlink.

Run from skills/cad-viewer:

npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --shutdown-after 12h

Every returned Viewer URL must include ?dir=<absolute-model-root>, commonly <repo>/models, and file=<path> values must be relative to ?dir=. Do not manually choose or increment ports, do not rely on session-storage ?dir= fallbacks, and do not stop an existing Viewer server unless the user asks.

Packaged Viewer runtime and handoff details belong in the cad-viewer skill instructions. Treat packaged Viewer checks as generated-output checks and use the master bundle wrapper unless you are debugging a lower-level script.

Git And LFS

CAD exchange files, generated render/topology assets, assets/**, and benchmarks/** may be LFS-tracked. Never disable LFS filters for git add, commits, or other object-writing operations. Local hooks live in .githooks and delegate build checks through scripts/git-hooks/pre-commit.

10 KiB Raw Permalink Blame History