AGENTS.md · earthtojake/text-to-cad

Sections

1. Branch First
2. Release Workflow
3. Repo Map
4. Repo Rules
5. Environments
6. Checks
7. CAD Viewer
8. Git

First lines (shown under the repo's MIT license)

# AGENTS.md

Installing text-to-cad rather than developing it? Follow the Install section of
[README.md](README.md).

This repo is a workbench for CAD-related agent skills. Treat `skills/` as the
product and `models/` as the shared fixture/artifact area. Read this file, then
[CONTRIBUTING.md](CONTRIBUTING.md) for the workflows it points at; every other
document is one link from the README of the tree it belongs to (Repo Map).

## Branch First

`main` is the only branch you develop on: the source tree, and what releases
are cut from. Branch from `main` and open PRs against `main`; never push it
directly. There is no development symlink layout — every path in the tree is the
real file. Installers follow `latest`, and claude.ai's directory
`claude-plugin`: the plugin alone, one commit per release,
written only by `Publish Release` once the release is on PyPI (see below); never
commit to them. `main` stays an installable plugin too: every manifest and MCP
config lives at its root.

## Release Workflow

A pull request that changes `VERSION` is a release, and merging it releases it.
Never bump during normal development work, and never pick the bump yourself: if
a request to make or ship a release does not name patch, minor, major, or an
exact version, ask which one. A release pull request comes one of two ways:

- **Its own pull request**, for a release of what `main` already has — what
  "make a release" means unless the user names a pull request to carry it:
  dispatch `Prepare Release`
  (`gh workflow run release-prepare.yml --ref main -f bump=<patch|minor|major>`,
  or `-f set_version=X.Y.Z`). It opens `release/X.Y.Z` with the bump and never
  merges it.
- **On the pull request that should carry it**: on its branch,
  `scripts/release/bump-version.sh <patch|minor|major|X.Y.Z>` sets `VERSION` past
  `main`'s and stamps the derived metadata and every `cadgen==` pin with it.

Merge a release pull request only on the user's explicit word, once its checks
pass: the merge is the release. `Test` runs every job for a `VERSION` change, and
its Version Check vets the bump (a branch of this repository only, a version past
`main`'s and the latest tag, every stamp in step). `Publish Release`
(`release-publish.yml`) runs on the merge: it builds the plugin ZIP, the bundle
and the `cadgen` wheel, uploads the wheel to PyPI and waits until PyPI lists it,
and only then writes the install branches (`latest`, `claude-plugin`), deploys
the docs site, tags `v<VERSION>` and publishes the GitHub Release. A run that
stopped partway is finished by dispatching `Publish Release` on `main`;
`build-test` is the rehearsal branch, used only when the user asks to test the
pipeline; the standalone `Deploy Docs` workflow redeploys the docs site from a
ref without a release. The full flow, the resume path, the rehearsal and the
local fallbacks are [CONTRIBUTING.md's Releases](CONTRIBUTING.md#releases).

cadgen installs as ONE uvx command, `uvx --no-config --managed-python --python
3.13 --from cadgen==<VERSION> <tool>` (`cadgen._internal.launch`), which the
plugin server configs run. That installation registers itself and writes the
`cadgen` command, `~/.local/bin/cadgen`; every cadgen skill's SKILL.md runs
`cadgen +<VERSION>` through it (uvx cannot start in an agent's sandbox, the
command can). The release stamps every pin and `+<VERSION>` (`sync-version.mjs`),
and `scripts/release/check-version.sh` and the tests assert they all equal
`VERSION`. One installation is one engine: the server, every thread and every
skill command share one daemon ([CONTRIBUTING.md, "Development
dependencies"](CONTRIBUTING.md#development-dependencies)). In a checkout, install
`requirements-dev.txt` (the editable cadgen) and test in agent apps with
`scripts/install/dev_install.py`, which points both at the checkout.

## Repo Map

- `skills/`: agent skills and their references/scripts.
- `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `gemini-extension.json`, and the
  [Agent Plugins](https://agent-plugins.org) standard's `plugin.json` and `mcp.json`:
  agent plugin manifests. The repository root is the plugin package; its skills are
  `skills/` directly. Installers take it from the `latest` branch, which
  `scripts/release/plugin_branch.py` builds from this tree at each release.
- `models/` ([README](models/README.md)): the corpus of engine models, plain files, each
  built with `python model.py`; nothing installs it.
- `docs/migrations/`: the hand-migration guides between releases
  ([0.7 to 0.8](docs/migrations/migrating-0.7-to-0.8.md), 0.4 to 0.5).
- `apps/web/` ([README](apps/web/README.md)): the CAD Viewer's React client (the engine
  hosts `cadgen.viewer`'s HTTP app).
- `apps/mcp/` ([README](apps/mcp/README.md)): the CAD app agent hosts render: tabs in
  Codex, cards in Claude Desktop (its server is `cadgen mcp`).
- `packages/` ([README](packages/README.md)): the three shared packages.
  `packages/cadgen` ([README](packages/cadgen/README.md)) is the published distribution,
  not just the Python: the engine (`cadgen/engine`: models built into documents it holds,
  and the XBF, STEP, GLB, STL, 3MF and DXF files written from them; the daemon and its
  workers; exports; the OCCT stills; the verbs the cadgen skills' commands run), the
  `cadgen` command line (`cadgen/cli`), the CAD Viewer server (`cadgen/viewer`), the CAD
  app server (`cadgen/mcp`), and the JS assets they serve (`cadgen/_runtime`, built by
  `scripts/bundle/cadgen-runtime.sh`); skills consume it as an installed distribution.
  `packages/core` ([README](packages/core/README.md)) is `@text-to-cad/core`, shared
  CAD/runtime/client code without React; `packages/ui` ([README](packages/ui/README.md))
  is `@text-to-cad/ui`, the shared FileViewer, renderers, controls and styles.
- `apps/docs/` ([README](apps/docs/README.md)): documentation site.
- `apps/api/` ([README](apps/api/README.md)): `api.texttocad.dev`, its own Vercel project:
  cadgen's version feed (read from PyPI) and the CAD app's consented analytics.
- `tests/`: root-owned test suites for skills, packages, viewer services, and
  repo-wide policy.
- `scripts/` ([README](scripts/README.md)): durable repo commands grouped by purpose.
- [SECURITY.md](SECURITY.md): the trust boundary (the engine's door, the page's
  credentials) and how a vulnerability is reported.

## Repo Rules

- Boundaries and design laws live in each package's README: read
  [`packages/cadgen/README.md`](packages/cadgen/README.md) (the laws),
  [`packages/core/README.md`](packages/core/README.md),
  [`packages/ui/README.md`](packages/ui/README.md),
  [`apps/web/README.md`](apps/web/README.md), [`apps/docs/README.md`](apps/docs/README.md)
  and [`apps/api/README.md`](apps/api/README.md) before changing generation, rendering,
  storage, layout, or public interfaces.
- A README holds the laws; the mechanism each law constrains lives one link
  away, and the README names the link. Read the README, then follow the one
  link — not the tree. Where the mechanisms are: the engine's README
  (`packages/cadgen/src/cadgen/engine/README.md`: models, the daemon and its workers,
  documents, exports, the mesh, references, the build closure), `packages/core/docs/`,
  `packages/ui/docs/` (`settings-ui.md` is BINDING for any settings control) and
  `apps/web/docs/`; each README's table says what every document there is for.
- Ships-alone law: `packages/cadgen` (the built PyPI wheel) works in isolation
  outside this repo, so its markdown must not refer to anything outside the
  package — enforced by `tests/python/global/test_package_boundaries.py`.
  Repo-development guidance for it goes in `CONTRIBUTING.md`.
- The README and the docs site's homepage (its copy: `apps/docs/src/lib/content.ts`)
  share their structure, install message and commands: change them together.
  The README says more: the steps to install it yourself, and fuller notes under each install
  (`apps/docs/README.md`).
- 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.
- A skill must not import another skill, a `skills/` root module, or a
  repository-root module, and must not add `skills/`, the repository root, or a
  sibling skill directory to `sys.path`, `PYTHONPATH`, `NODE_PATH`, or any other
  runtime lookup path. Skills are independent of each other, not of everything.
- Shared runtime comes from the **`cadgen` distribution**. A skill that uses it
  defines `cadgen` and `python` in its SKILL.md as `cadgen +<VERSION>` above
  (the release stamps every pin); no skill installs cadgen
  any other way (no `requirements.txt` naming it), because a second installation
  is a second daemon. Skills do not vendor it: a skill script is a thin entrypoint whose
  parser and behaviour live in `cadgen.cli`. The engine draws every snapshot with
  OCCT, so no skill has a browser step. cadgen carries the JavaScript it serves too
  (the CAD Viewer client, the CAD app page), so a skill ships no runtime of its own. Not every
  skill needs cadgen (bambu-labs, dfam-check, dfm, gcode, sendcutsend,
  step-parts are cadgen-free); do not add the dependency to a skill that never invokes it.
- Keep samples and manual CAD/robot-description validation artifacts under
  `models/`. Automated tests must not read, build or import that sample corpus:
  generate small fixtures in fresh temporary directories or use tiny test-owned
  fixtures, with their own engine daemon (`CADGEN_ENGINE_DIR`) and cleanup. Repo `tmp/` is fine.
  Enforced by `tests/python/global/test_tests_are_self_contained.py`.
- Every test runs in CI. Each test file is reached by a runner under
  `scripts/test/`, every runner is called by a `test.yml` job on the changes that
  can break it, and a collector that finds nothing fails the run rather than
  reporting a group that never ran. A test no CI job runs is dead: wire it in or
  delete it. There are no manual-only test gates. Enforced by
  `tests/python/global/test_ci_workspace_selection.py`.
- Tests and CI are short and succinct. Test a contract, a user flow or a fixed bug,
  once, at the cheapest level that exercises the real path: a unit or jsdom test
  first, a real browser (WebGL) only for what needs one. Await the condition, never