CCM-16068 - Revised AGENTS.md

Author: rhyscoxnhs

AGENTS.md

@@ -11,8 +11,9 @@ Keep anything language or tool-specific in nested `AGENTS.md` files (for example
 
 At a glance, the main areas are:
 
+- `pnpm-workspace.yaml` - Defines packages, dependency versions, and package installation options.
 - `infrastructure/terraform/` – Terraform components, and shared modules for AWS accounts and environments.
-- `lambdas/` – TypeScript lambda projects (each with their own `package.json`, Jest config, etc.). Root level packages.json defines workspaces and scripts. Tests for the lambda are stored in `lambdas/{name}/src/__test`.
+- `lambdas/` – TypeScript lambda projects (each with their own `package.json`, Jest config, etc.). Root level packages.json defines scripts. Tests for the lambda are stored in `lambdas/{name}/src/__test`.
 - `src/` and `utils/` – Shared code and utilities (for example `utils/logger`).
 - `docs/` – Documentation site, ADRs, RFCS, and other long‑form docs.
 - `.github/workflows/` and `.github/actions/` – GitHub Actions workflows and composite actions.
@@ -21,18 +22,31 @@ At a glance, the main areas are:
 
 Agents should look for a nested `AGENTS.md` in or near these areas before making non‑trivial changes.
 
+## Root pnpm-workspace.yaml - role and usage
+
+The root `pnpm-workspace.yaml` is the manifest for configuring the pnpm tool, and any workspace packages (if added).
+
+- Packages: Declares the set of workspace packages (e.g. under `lambdas/`, `utils/`, `tests/`, `scripts/`). Agents should add a new package path here when introducing a new workspace package if the packages entry is present.
+- Catalogs: Defines named version catalogs (`lint`, `test`, `tools`) that centralise dependency version ranges. Workspace packages reference these with the `catalog:<name>` protocol (e.g. `"jest": "catalog:test"`) instead of hardcoding version ranges in each `package.json`.
+
+Agent guidance for catalogs:
+
+- When adding a dependency that belongs to an existing catalog category, add the version range to the appropriate catalog in `pnpm-workspace.yaml` and reference it as `"catalog:<name>"` in the consuming `package.json`.
+- Do not hardcode version ranges in workspace `package.json` files for dependencies that already exist in a catalog — always use the `catalog:` protocol.
+- When updating a dependency version, change it in the catalog entry only; all workspace packages referencing that catalog entry will pick up the new version automatically.
+- If a dependency does not fit any existing catalog, create a new catalog with a suitable name and add the version range there. All dependencies must be managed through catalogs — never hardcode version ranges directly in a `package.json`.
+
 ## Root package.json – role and usage
 
-The root `package.json` is the orchestration manifestgit co for this repo. It does not ship application code; it wires up shared dev tooling and delegates to workspace-level projects.
+The root `package.json` is the orchestration manifest for this repo. It does not ship application code; it wires up shared dev tooling and delegates to workspace-level projects.
 
-- Workspaces: Declares the set of npm workspaces (e.g. under `lambdas/`, `utils/`, `tests/`, `scripts/`). Agents should add a new workspace path here when introducing a new npm project.
-- Scripts: Provides top-level commands that fan out across workspaces using `--workspaces` (lint, typecheck, unit tests) and project-specific runners (e.g. `build-archive`).
+- Scripts: Provides top-level commands that fan out across workspaces using `--recursive` / `-r` (lint, typecheck, unit tests) and project-specific runners (e.g. `build-archive`).
 - Dev tool dependencies: Centralises Jest, TypeScript, ESLint configurations and plugins to keep versions consistent across workspaces. Workspace projects should rely on these unless a local override is strictly needed.
 - Overrides/resolutions: Pins transitive dependencies (e.g. Jest/react-is) to avoid ecosystem conflicts. Agents must not remove overrides without verifying tests across all workspaces.
 
 Agent guidance:
 
-- Before adding or removing a workspace, update the root `workspaces` array in `pnpm-workspace.yaml` and ensure CI scripts still succeed with `pnpm run lint`, `pnpm run typecheck`, and `pnpm run test:unit` at the repo root.
+- Before adding or removing a workspace, update the root `packages` array in `pnpm-workspace.yaml` and ensure CI scripts still succeed with `pnpm run lint`, `pnpm run typecheck`, and `pnpm run test:unit` at the repo root.
 - When adding repo-wide scripts, keep names consistent with existing patterns (e.g. `lint`, `lint:fix`, `typecheck`, `test:unit`, `build-archive`) and prefer `pnpm -r run` fan-out.
 - Do not publish from the root. If adding a new workspace intended for publication, mark that workspace package as `private: false` and keep the root as private.
 - Validate changes by running the repo pre-commit hooks: `make githooks-run`.
@@ -81,7 +95,7 @@ When proposing a change, agents should:
 
   to catch formatting and basic lint issues. Domain specific checks will be defined in appropriate nested AGENTS.md files.
 
-- Suggest at least one extra validation step (for example `npm test` in a lambda, or triggering a specific workflow).
+- Suggest at least one extra validation step (for example `pnpm test` in a lambda, or triggering a specific workflow).
 - Any required follow up activites which fall outside of the current task's scope should be clearly marked with a 'TODO: CCM-12345' comment. The human user should be prompted to create and provide a JIRA ticket ID to be added to the comment.
 
 ## Security & Safety