# 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.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 ` 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 ` 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`: ```bash npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --shutdown-after 12h ``` Every returned Viewer URL must include `?dir=`, commonly `/models`, and `file=` 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`.