From c9d2324f614339c102a4388db02e53cbc42a52e8 Mon Sep 17 00:00:00 2001 From: Wenjix Date: Sun, 14 Jun 2026 14:57:25 -0700 Subject: [PATCH] docs(AGENTS): add build/test/run + Cursor Cloud notes (salvaged from #3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Folds the generally-useful run notes from the Cursor Cloud setup PR (#3) into the existing AGENTS.md: the offline plan-pr / --plan-only flow, --scored for local input, live-command credentials, and the ~/.cursor canvas-mirror flag. Corrects #3's now-stale gotcha — plan-pr is plan-only by design on main (cli.ts dispatches planOnly: true) — and notes prebuild auto-cleans dist. Drops #3's package-lock change, since main standardized on the npmjs registry in #6. --- AGENTS.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5bdf912..0f15a88 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,3 +13,28 @@ Operational guidance for humans and coding agents working in this repo. regenerate the lockfile against another registry. Rationale, verification, and removal conditions live in `docs/dependencies.md` (removal tracked in #5). - **Auditing:** `npm audit --audit-level=moderate` (npmjs registry required). + +## Build, test & run + +Single Node.js/TypeScript CLI — no server, no watch mode. + +- Commands: `npm run build` (tsc), `npm test` (builds, then `node --test dist/test/*.test.js`), + `npm run typecheck`. `build`/`test` clean `dist/` first (`prebuild`), so stale compiled output + from a branch switch can't leak into a run. +- After editing `src/`, rebuild and invoke with `node dist/src/cli.js ` (no `npm link` step). +- **Offline / no-credentials runs:** `plan-pr ` is plan-only by design — it builds the + DAG → state → report → Canvas without calling Cursor Cloud. It still reads the PR's findings from + GitHub unless you pass them locally with `--scored `, which makes the run + fully offline: + `node dist/src/cli.js plan-pr https://github.com/OWNER/REPO/pull/N --scored clusters.scored.json`. + On the lower-level `explore`/`triage-pr` commands the same cloud-skip is the `--plan-only` flag. +- **Live commands** — `run-pr`, `post-pr`, `run-dag`, and `triage-pr` without `--plan-only` — call + Cursor Cloud and/or GitHub and need `CURSOR_API_KEY` plus an authenticated `gh` CLI. Without them + the runner still completes, recording per-task `ERROR`/`SKIPPED` instead of crashing. +- Run artifacts are written under `.quorum/` (gitignored). + +## Cursor Cloud + +- The cloud-agent environment runs `npm install` on startup (configured in Cursor, not in the repo). +- Use `--no-canvas-mirror` on offline/CI runs so the runner doesn't write into the Cursor managed + canvases directory under `~/.cursor`.