Skip to content

Commit 52fd2ff

Browse files
earthtojakeearthtojake
committed
Document release workflow branches
1 parent 271f673 commit 52fd2ff

3 files changed

Lines changed: 96 additions & 112 deletions

File tree

‎AGENTS.md‎

Lines changed: 69 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -3,63 +3,87 @@
33
This repo is a workbench for CAD-related agent skills. Treat `skills/` as the
44
product and `models/` as the shared fixture/artifact area.
55

6+
## Branch And Layout First
7+
8+
Before changing code, branch from `dev`, not `main`; PRs should target `dev`.
9+
Do not start development work from `main`. The `dev` branch intentionally uses
10+
symlinks across generated runtime, viewer-local package, and plugin package
11+
paths. When a path is symlinked, follow the link and edit the source target.
12+
Use `main` as the production clone/release branch only.
13+
14+
## Release Workflow
15+
16+
Normal development work targets `dev` and should not bump release metadata. To
17+
start a release, run the `Prepare Release` workflow from `dev`; it creates a
18+
`release/<version>` branch, updates repo-owned version files, and opens a PR
19+
back to `dev`. After that PR merges, the production-branch builder bundles the
20+
symlinked checkout into real generated outputs and pushes the result to
21+
`build-test` for now, later `main`.
22+
23+
The `Release Tag` workflow runs from that production branch. It checks the
24+
production layout, creates the semver git tag from the repo-owned version, and
25+
opens a draft GitHub Release. Use `scripts/release/bump-version.sh` and
26+
`scripts/release/publish-github-release.sh` only as local/manual fallbacks for
27+
the GitHub workflows.
28+
629
## Repo Map
730

831
- `skills/`: agent skills and their references/scripts.
932
- `plugins/`: versioned agent plugin packages that bundle repo skills.
1033
- `models/`: sample and durable CAD/robot-description fixtures.
1134
- `viewer/`: editable CAD Viewer source app.
12-
- `packages/cadjs`: shared JS CAD/render/runtime code, UI-framework agnostic.
13-
- `packages/cadpy`: shared Python STEP/GLB/topology artifact code.
14-
- `packages/cadpy_metadata`: dependency-free Python metadata helpers vendored
15-
into generated URDF/SRDF/SDF skill runtimes.
35+
- `packages/`: shared source packages copied or vendored into consuming
36+
runtimes.
1637
- `docs/`: documentation site.
1738
- `tests/`: repo-wide policy tests that are not owned by one package, skill, or
1839
app runtime.
1940
- `scripts/`: durable repo commands grouped by purpose.
2041

2142
## Repo Rules
2243

23-
- Keep root guidance short. Put domain workflows, CLI details, and validation policy in the relevant `skills/<skill>/SKILL.md` or `references/` file.
44+
- Keep root guidance short. Put domain workflows, CLI details, and validation
45+
policy in the relevant `skills/<skill>/SKILL.md` or `references/` file.
2446
- Keep relevant Markdown docs current when changing behavior, commands, or repo
2547
layout, but do not bloat `AGENTS.md`; use it only for durable repo-level
2648
rules and pointers.
2749
- Read `CONTRIBUTING.md` before committing, rebasing, resolving generated-file
2850
conflicts, or bumping release versions.
29-
- Branch from `dev` for development and open PRs against `dev`. Keep `dev` in
30-
symlink layout with `scripts/dev/setup-symlinks.sh`; production users should clone `main`.
51+
- Keep the `dev` checkout in symlink layout with
52+
`scripts/dev/setup-symlinks.sh`.
3153
- Each skill must be self-contained and independent at runtime. A skill must
32-
not refer to or import or depend on code from another skill, from `skills/` root, or from
33-
repository-root modules. Do not add `skills/`, the repository root, or sibling
34-
skill directories to `sys.path`, `PYTHONPATH`, `NODE_PATH`, or similar runtime
35-
lookup paths. Shared runtime helpers must live under `packages/` as the source
36-
of truth and be vendored/generated from there into each consuming skill
37-
runtime; do not keep shared helper modules directly under `skills/`.
38-
- Edit sources first, then regenerate explicit derived outputs. Do not hand-edit generated skill runtimes or bundled package copies.
54+
not refer to or import or depend on code from another skill, from `skills/`
55+
root, or from repository-root modules. Do not add `skills/`, the repository
56+
root, or sibling skill directories to `sys.path`, `PYTHONPATH`, `NODE_PATH`,
57+
or similar runtime lookup paths. Shared runtime helpers must live under
58+
`packages/` as the source of truth and be vendored/generated from there into
59+
each consuming skill runtime; do not keep shared helper modules directly under
60+
`skills/`.
61+
- Edit the source reached by the `dev` symlink layout first, then regenerate
62+
explicit derived outputs when a production-output task requires it.
3963
- Write all test, sample, permanent, and generated CAD/robot-description
4064
artifacts under `models/`, including STEP/STP, STL, GLB, DXF, URDF, SRDF,
4165
SDF, and G-code outputs. Do not create ad hoc artifact directories elsewhere.
4266
- Reserve `scripts/` for durable repo commands. Do not write temporary,
4367
one-off, or local-only helper scripts there; use `tmp/` or `/tmp` instead.
44-
- `viewer/`, `packages` are the source of truth for CAD Viewer and shared CAD runtime behavior. Duplicate files under skills such as `skills/cad-viewer/scripts/viewer`, `skills/cad-viewer/scripts/packages/`, `skills/cad/scripts/packages/`, and snapshot runtimes are generated copies that should not be edited.
45-
- When changing skill behavior that uses `packages/cadjs`, `packages/cadpy`, or `skills/cad-viewer/scripts/viewer`, edit the root source in `packages/*` or `viewer/*`, then rebundle the generated skill copies. Never patch the copies as the lasting fix.
46-
- `plugins/cad/skills/` is a generated production plugin package copy of
47-
the root `skills/` sources. Edit `skills/*` first, then run
48-
`scripts/bundle/bundle-plugin.sh` to refresh the plugin copy; do not hand-edit
49-
plugin skill copies.
50-
- `viewer/packages/*` contains generated viewer-local package copies for
51-
standalone viewer deployments. Edit `packages/*` first; the cad-viewer skill
52-
production bundle refreshes those copies.
53-
- `packages/cadjs` must stay reusable/non-React; app UI and workflow state belong in `viewer/`.
54-
- `packages/cadpy` owns reusable Python artifact generation; skills should use bundled package code, not sibling skill imports.
55-
- Create new packages like `packages/cadpy_metadata` when it doesn't make sense to bundle heavy requirements of other cadpy skills (prefix new packages with `cadpy_*`).
56-
- Use path-targeted search, validation, and `git status`; avoid broad scans over generated CAD/LFS artifacts unless the task requires them.
68+
- Development symlinks mark generated or copied paths. If a file is under a
69+
symlinked runtime, viewer package, or plugin package path, edit the symlink
70+
target/source path instead of treating the copy as independent.
71+
- When source changes affect generated runtimes or plugin packages, refresh or
72+
check them with the master bundle wrapper, `scripts/bundle/bundle.sh`. Use
73+
lower-level bundle scripts only when debugging the wrapper itself.
74+
- `packages/cadjs` must stay reusable/non-React; app UI and workflow state
75+
belong in `viewer/`.
76+
- `packages/cadpy` owns reusable Python artifact generation; skills should use
77+
bundled package code, not sibling skill imports.
78+
- Create lightweight shared Python packages under `packages/cadpy_*` when a
79+
helper should not inherit heavier package dependencies.
80+
- Use path-targeted search, validation, and `git status`; avoid broad scans over
81+
generated CAD/LFS artifacts unless the task requires them.
5782
- Keep release versioning in lockstep: the git tag, plugin manifests and
5883
`plugins/*/VERSION`, package manifests/locks, Python `pyproject.toml` files,
5984
and any other repo-owned release version numbers should all match. The
60-
current release version is `0.1.15`. Use the `Prepare Release` GitHub
61-
workflow for normal release bumps; `scripts/release/bump-version.sh` is the
62-
local fallback described in `CONTRIBUTING.md`.
85+
current release version is `0.1.15`. Follow the release workflow above and
86+
the detailed fallback commands in `CONTRIBUTING.md`.
6387

6488
## Environments
6589

@@ -74,19 +98,20 @@ Run the smallest path-targeted check that covers the change. Use broad wrappers
7498
when touching shared surfaces or before handoff:
7599

76100
- Code tests: `scripts/test/test.sh`
101+
- Focused test runners: `scripts/test/test-js.sh`,
102+
`scripts/test/test-docs.sh`, `scripts/test/test-python.sh`,
103+
`scripts/test/test-global.sh`
77104
- Development symlink layout: `scripts/dev/setup-symlinks.sh --check`
78105
- Release version metadata: `scripts/release/check-version.sh`
79-
- All generated runtime freshness: `scripts/bundle/bundle.sh --check`
80-
- Skill production output freshness: `scripts/bundle/bundle-skill.sh <skill-id> --check`
81-
- CAD Viewer or `packages/cadjs`: `npm --prefix packages/cadjs test`, `npm --prefix viewer run test`, `npm --prefix viewer run build`, `scripts/bundle/bundle-skill.sh cad-viewer --check`
82-
- Plugin packages: `scripts/bundle/bundle-plugin.sh --check`
106+
- Generated runtime and plugin freshness: `scripts/bundle/bundle.sh --check`
107+
- CAD Viewer or `packages/cadjs`: `npm --prefix packages/cadjs test`,
108+
`npm --prefix viewer run test`, `npm --prefix viewer run build`
83109
- Docs site: `npm --prefix docs run check`
84-
- Python package, skill, and server tests: `scripts/test/test-python.sh`
85-
- Repo-wide policy tests: `scripts/test/test-global.sh`
86110
- Targeted Python tests: `./.venv/bin/python -m unittest <changed test paths>`
87111

88-
When changing generated outputs, run the matching master bundle command without
89-
`--check`, then rerun it with `--check`.
112+
When a task intentionally writes production outputs locally, run
113+
`scripts/bundle/bundle.sh`, rerun `scripts/bundle/bundle.sh --check`, and restore
114+
the development symlink layout afterward if you are continuing on `dev`.
90115

91116
## CAD Viewer
92117

@@ -98,25 +123,17 @@ artifacts stay in one place.
98123
For root dev-server iteration, use the URL printed by Viewer commands; do not
99124
assume a fixed dev port unless you pass Vite's standard `--port` flag.
100125

101-
When modifying Viewer behavior, always run the root source app in dev mode for iteration;
102-
do not run the generated viewer from the cad-viewer skill while developing.
126+
When modifying Viewer behavior, always run the root source app in dev mode for
127+
iteration; do not run the generated viewer from the cad-viewer skill while
128+
developing.
103129

104130
```bash
105131
npm --prefix viewer run dev -- --host 127.0.0.1
106132
```
107133

108-
For packaged skill runtime review:
109-
110-
```bash
111-
npm --prefix skills/cad-viewer/scripts/viewer run serve -- --host 127.0.0.1 --port 4178 --shutdown-after 12h
112-
```
113-
114-
For cad-viewer skill handoffs, probe port `4178` first and reuse it when
115-
`/__cad/server` reports `app: "cad-viewer"`, `dynamicRoot: true`, and
116-
`serverApiVersion >= 2`; use `viewerVersion` in that response to sanity-check
117-
the running build. If a legacy root-bound Viewer or non-Viewer process occupies
118-
the port, try the next port. Return links with an absolute `?dir=` on every URL
119-
and an absolute `?file=...` for each requested file.
134+
Packaged Viewer runtime and handoff details belong in the `cad-viewer` skill
135+
instructions. Treat packaged Viewer checks as generated-output checks and use
136+
the master bundle wrapper unless you are debugging a lower-level script.
120137

121138
## Git And LFS
122139

‎scripts/README.md‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -118,15 +118,16 @@ fallback, but the workflow path is preferred.
118118

119119
## CI
120120

121-
- `test.yml`: runs code tests on `dev`, `build-test`, `main`, and PRs.
122-
- `check-version.yml`: checks release metadata on `dev`, `build-test`, `main`,
123-
and PRs.
124-
- `check-builds.yml`: checks production bundle freshness on `build-test` and
125-
`main`.
126-
- `check-symlinks.yml`: checks the development symlink layout on `dev` and PRs
127-
targeting `dev`.
128-
- `prepare-release.yml`: manually opens a release metadata PR against `dev`.
129-
- `build-test-branch.yml`: temporary release builder from `dev` to
130-
`build-test`; this will target `main` once the flow is trusted.
131-
- `release-tag.yml`: temporary production tag/release workflow for `build-test`;
132-
this will target `main` once the flow is trusted.
121+
| Workflow | Branches/events | Purpose |
122+
| -------- | --------------- | ------- |
123+
| `test.yml` | pushes to `dev`, `build-test`, `main`; PRs to those branches | Runs the broad code test wrapper. |
124+
| `check-version.yml` | pushes to `dev`, `build-test`, `main`; PRs to those branches | Verifies repo-owned release metadata is internally consistent. |
125+
| `check-symlinks.yml` | pushes to `dev`; PRs targeting `dev` | Verifies the development checkout keeps generated-copy paths symlinked to source. |
126+
| `check-builds.yml` | pushes to `build-test` and `main`; PRs targeting those branches | Verifies production branches contain bundled generated outputs instead of symlinks. |
127+
| `prepare-release.yml` | manual dispatch from `dev` | Bumps version metadata on `release/<version>` and opens a release PR back to `dev`. |
128+
| `build-test-branch.yml` | pushes to `dev`; manual dispatch | Temporary release builder that bundles `dev` and pushes production output to `build-test`; this will target `main` once trusted. |
129+
| `release-tag.yml` | pushes to `build-test`; manual dispatch | Temporary production release workflow that tags the bundled commit and creates a draft GitHub Release; this will target `main` once trusted. |
130+
131+
In short: `dev` is the editable symlink branch, `build-test` is the temporary
132+
production-output proving branch, and `main` is the eventual production branch
133+
for user clones and published releases.

‎viewer/README.md‎

Lines changed: 14 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
# CAD Viewer
22

3-
CAD Viewer is a browser workbench for inspecting CAD files, robot-description
4-
files, and generated CAD artifacts from a URL-selected local root directory or
5-
hosted catalog. It is built for engineering review loops where a developer or
6-
agent needs to open a model quickly, understand the source tree, copy stable
7-
`@cad[...]` references, and verify generated assets without leaving the
8-
browser.
3+
CAD Viewer is a browser workbench for inspecting CAD files,
4+
robot-description files, and generated CAD artifacts from a URL-selected local
5+
directory or hosted catalog. It is built for engineering review loops where you
6+
need to open a model quickly, understand the source tree, copy stable
7+
`@cad[...]` references, and verify generated assets without leaving the browser.
98

109
## Features
1110

@@ -28,10 +27,8 @@ Run these commands from this directory:
2827

2928
```bash
3029
npm install
31-
npm run dev
3230
npm run test
3331
npm run build
34-
npm run serve
3532
```
3633

3734
For local development, start the dev server and then pass absolute local paths
@@ -58,25 +55,10 @@ to render that file and hides the file explorer sidebar and breadcrumbs. With
5855
neither `?dir=` nor `?file=`, the Viewer shows an empty prompt asking for one of
5956
those parameters.
6057

61-
Agent handoff links from the cad-viewer skill should still include an absolute
62-
`?dir=` on every returned URL, plus an absolute `file=` value for each requested
63-
file. The session-storage fallback is for same-tab navigation, not for durable
64-
review links.
65-
66-
This workbench keeps generated package copies under `packages/` so the viewer
67-
can build from a standalone `viewer/` deploy root. Edit the source of truth in
68-
`../packages/*`; the cad-viewer production runtime build refreshes the
69-
viewer-local copies before handoff:
70-
71-
```bash
72-
npm run runtime:bundle
73-
```
74-
75-
Refresh and install the viewer-local Python artifact package when iterating on
76-
local STEP regeneration:
58+
Install the local Python artifact package when iterating on local STEP
59+
regeneration:
7760

7861
```bash
79-
npm run runtime:bundle
8062
python -m pip install -r requirements.txt
8163
```
8264

@@ -97,18 +79,15 @@ python -m pip install -r requirements.txt
9779
and MoveIt2.
9880
- `moveit2_server/`: optional Python websocket backend for SRDF controls.
9981

100-
The shared non-React CAD runtime source lives in `../packages/cadjs` in this
101-
workbench. Keep reusable parsing, rendering, sidecar, selector, and topology
102-
logic there instead of editing generated viewer-local package copies.
103-
10482
## Common Commands
10583

10684
```bash
10785
npm run dev # Vite dev server with local CAD API middleware
108-
npm run agent:start # Agent launcher: dev symlink uses Vite, package uses dist/
86+
npm run agent:start # Launcher that chooses dev or production serve mode
10987
npm run build # Production frontend build
11088
npm run serve # Serve dist/ with the local or hosted backend
11189
npm run test # Discover and run all JS tests
90+
npm run upload:blob # Upload a hosted catalog and supported viewer assets
11291
```
11392

11493
`npm run test` uses `scripts/run-tests.mjs`, which discovers
@@ -129,8 +108,8 @@ Important environment variables:
129108
is absent and a `?dir=` or stored active directory is available.
130109
- `VIEWER_SERVER_LIFETIME_MS`: optional server lifetime in milliseconds for
131110
local dev and production servers. When unset, there is no automatic shutdown.
132-
- `VIEWER_GITHUB_URL`: optional top-bar GitHub link target. Defaults to this
133-
repository; the version label links to the matching GitHub release tag.
111+
- `VIEWER_GITHUB_URL`: optional top-bar GitHub link target. When set, the
112+
version label links to the matching GitHub release tag.
134113
- `VIEWER_ALLOWED_HOSTS`: extra hostnames accepted by local Vite dev and
135114
production servers.
136115
- `VIEWER_MOVEIT2_WS_URL`: optional websocket URL for SRDF MoveIt2 controls.
@@ -162,11 +141,10 @@ Vercel's system environment variables (`VERCEL_PROJECT_PRODUCTION_URL`,
162141
`VERCEL_URL`, then `VERCEL_BRANCH_URL`).
163142

164143
Upload a catalog and supported viewer assets from a local directory with
165-
`npm --prefix viewer run upload:blob -- models`.
166-
The repo-level `scripts/viewer/upload-viewer-models-catalog.sh` command uploads
167-
`models/` to the configured Blob prefix. Uploads exclude `mechbench/`,
144+
`npm run upload:blob -- /path/to/models`. Uploads exclude `mechbench/`,
168145
`mechbench2/`, `7dof_arm/`, and Python source files by default; public Blob
169-
catalogs omit Python source paths and URLs.
146+
catalogs omit Python source paths and URLs. Add a `.vieweruploadignore` file or
147+
pass `--exclude <pattern>` for project-specific upload filters.
170148

171149
Production builds contain the frontend and initial catalog module only. CAD
172150
assets are served by a backend and are not copied into `dist/`.
@@ -178,9 +156,6 @@ assets are served by a backend and are not copied into `dist/`.
178156
- [Browser storage](./docs/storage.md): URL, `localStorage`, and
179157
`sessionStorage` ownership.
180158
- [MoveIt2 server](./docs/moveit2-server.md): optional SRDF websocket backend.
181-
- `cadjs` render pipeline: shared render APIs used by the viewer, docs, and
182-
snapshot runtime. In this workbench, see
183-
`../packages/cadjs/docs/render-pipeline.md`.
184159

185160
## Verification
186161

@@ -189,18 +164,9 @@ Run the focused viewer checks before handing off viewer changes:
189164
```bash
190165
npm run test
191166
npm run build
192-
npm run runtime:check
193167
```
194168

195169
For UI behavior changes, also run `npm run dev -- --host 127.0.0.1`, open the
196170
printed URL with `?dir=/absolute/root&file=/absolute/root/path/to/model.step`,
197171
and check that the app renders, selection works, and the browser console is
198172
clean.
199-
200-
When changing Viewer source that feeds the cad-viewer skill runtime, refresh the
201-
generated runtime from the repository root:
202-
203-
```bash
204-
scripts/bundle/bundle-skill.sh cad-viewer
205-
scripts/bundle/bundle-skill.sh cad-viewer --check
206-
```

0 commit comments

Comments
 (0)