Import CAD projects and cad-router v1
This commit is contained in:
Jerry
@@ -0,0 +1,188 @@
|
||||
# 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`:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
Reference in New Issue
Block a user