From b852bbf91cb9fd5a16073abe2ef70f7401766a8a Mon Sep 17 00:00:00 2001 From: Jacek Date: Wed, 20 May 2026 21:53:17 -0500 Subject: [PATCH 1/2] docs(repo): Expand AGENTS.md with toolchain, changeset, and commit rules --- .changeset/agents-md-expand.md | 2 ++ AGENTS.md | 27 +++++++++++++++++++++++---- 2 files changed, 25 insertions(+), 4 deletions(-) create mode 100644 .changeset/agents-md-expand.md diff --git a/.changeset/agents-md-expand.md b/.changeset/agents-md-expand.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/agents-md-expand.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/AGENTS.md b/AGENTS.md index 786c572a61f..cdef8d6c30c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,27 @@ # AGENTS.md -Clerk's JavaScript SDK and library monorepo. +Clerk JavaScript SDK monorepo. -## Guidelines +## Rules -- Non-major releases in `packages/clerk-js` and `packages/ui` are pushed out to consuming applications without requiring explicit package updates. Extra care must be put into any changes to these packages. -- The API exposed from the core Clerk class in `packages/clerk-js/src/core/clerk.ts` is a contract that is depended on by internal and external consumers. Changes to this API must be done in a major version to avoid breakage. +- Non-major releases in `packages/clerk-js` and `packages/ui` are pushed out to consuming applications without requiring explicit package updates. This means a new `clerk-js` runtime can load into an app pinned to an older `@clerk/nextjs` (or any other framework SDK) version, so changes must remain backwards-compatible with SDK versions already in the wild, not just the current monorepo state. Removing or renaming anything an older SDK still calls will break production for those users. Extra care must be put into any changes to these packages. +- The API exposed from the core Clerk class in `packages/clerk-js/src/core/clerk.ts` is a contract that is depended on by internal and external consumers (including older SDK versions still loading the latest `clerk-js`). Changes to this API must be done in a major version to avoid breakage. + +## Toolchain + +- pnpm only (`only-allow pnpm`). Node `>=24.15`, pnpm `>=10.33`. +- `pnpm install` from root. + +## Changesets + +- Every PR needs one. `pnpm changeset` for package changes, `pnpm changeset:empty` for tooling/repo-only. +- Empty changesets: two `---` delimiters, no body. + +## Commits + +- Conventional commits, `type(scope):` required (commitlint enforces). +- scope = package name without `@clerk/`, or `repo` / `release` / `e2e`. `clerk-js` uses `js`. + +## More + +`docs/CONTRIBUTING.md` for dev setup, testing, JSDoc, publishing. From 9ecc102550ec57b77f52dda7ca48ea39603c770a Mon Sep 17 00:00:00 2001 From: Jacek Date: Thu, 21 May 2026 07:35:08 -0500 Subject: [PATCH 2/2] docs(repo): Add pnpm, changeset, and commit rules inline to avoid repeat agent failures --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4d69b363c6a..f46e16aa046 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,9 @@ Clerk's JavaScript SDK and library monorepo. - Non-major releases in `packages/clerk-js` and `packages/ui` are pushed out to consuming applications without requiring explicit package updates. This means a new `clerk-js` runtime can load into an app pinned to an older `@clerk/nextjs` (or any other framework SDK) version, so changes must remain backwards-compatible with SDK versions already in the wild, not just the current monorepo state. Removing or renaming anything an older SDK still calls will break production for those users. Extra care must be put into any changes to these packages. - The API exposed from the core Clerk class in `packages/clerk-js/src/core/clerk.ts` is a contract that is depended on by internal and external consumers (including older SDK versions still loading the latest `clerk-js`). Changes to this API must be done in a major version to avoid breakage. +- Use `pnpm` only. `npm` and `yarn` are blocked by `preinstall`. Node `>=24.15`, pnpm `>=10.33`. +- Every PR needs a changeset. `pnpm changeset` for package changes, `pnpm changeset:empty` for tooling/repo-only. Empty changesets are two `---` delimiters with no body. +- Commits must be conventional: `type(scope):` (commitlint enforces). `scope` is the package name without `@clerk/`, or `repo` / `release` / `e2e`. `clerk-js` uses scope `js`. ## References