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,23 @@ 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.
+
 ## 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 +87,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