|
| 1 | +# AGENTS.md |
| 2 | +<!-- vale off --> |
| 3 | + |
| 4 | +## Scope |
| 5 | + |
| 6 | +This file is for **AI agents** working within NHS Notify repositories. |
| 7 | +Humans should read `README.md` and the docs for how we actually work day to day. |
| 8 | +Keep anything language or tool-specific in nested `AGENTS.md` files (for example under `infrastructure/terraform` or `lambdas`). |
| 9 | + |
| 10 | +## Repository Layout (high level) |
| 11 | + |
| 12 | +At a glance, the main areas are: |
| 13 | + |
| 14 | +- `infrastructure/terraform/` – Terraform components, and shared modules for AWS accounts and environments. |
| 15 | +- `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`. |
| 16 | +- `src/` and `utils/` – Shared code and utilities (for example `utils/logger`). |
| 17 | +- `docs/` – Documentation site, ADRs, RFCS, and other long‑form docs. |
| 18 | +- `.github/workflows/` and `.github/actions/` – GitHub Actions workflows and composite actions. |
| 19 | +- `scripts/` – Helper scripts and tooling used by humans and workflows. |
| 20 | +- `tests/` – Cross‑cutting tests and harnesses for the repo. |
| 21 | + |
| 22 | +Agents should look for a nested `AGENTS.md` in or near these areas before making non‑trivial changes. |
| 23 | + |
| 24 | +## Root package.json – role and usage |
| 25 | + |
| 26 | +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. |
| 27 | + |
| 28 | +- 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. |
| 29 | +- Scripts: Provides top-level commands that fan out across workspaces using `--workspaces` (lint, typecheck, unit tests) and project-specific runners (e.g. `lambda-build`). |
| 30 | +- 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. |
| 31 | +- 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. |
| 32 | + |
| 33 | +Agent guidance: |
| 34 | + |
| 35 | +- Before adding or removing a workspace, update the root `workspaces` array and ensure CI scripts still succeed with `npm run lint`, `npm run typecheck`, and `npm run test:unit` at the repo root. |
| 36 | +- When adding repo-wide scripts, keep names consistent with existing patterns (e.g. `lint`, `lint:fix`, `typecheck`, `test:unit`, `lambda-build`) and prefer `--workspaces` fan-out. |
| 37 | +- 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. |
| 38 | +- Validate changes by running the repo pre-commit hooks: `make githooks-run`. |
| 39 | + |
| 40 | +Success criteria for changes affecting the root `package.json`: |
| 41 | + |
| 42 | +- `npm run lint`, `npm run typecheck`, and `npm run test:unit` pass at the repo root. |
| 43 | +- Workspace discovery is correct (new projects appear under `npm run typecheck --workspaces`). |
| 44 | +- No regression in lambda build tooling (`npm run lambda-build`). |
| 45 | + |
| 46 | +## What Agents Can / Can’t Do |
| 47 | + |
| 48 | +Agents **can**: |
| 49 | + |
| 50 | +- Propose changes to code, tests, GitHub workflows, Terraform, and docs. |
| 51 | +- Suggest new scripts, Make targets, or composite actions by copying existing patterns. |
| 52 | +- Run tests to validate proposed solutions. |
| 53 | + |
| 54 | +Agents **must not**: |
| 55 | + |
| 56 | +- Create, push, or merge branches or PRs. |
| 57 | +- Introduce new technologies, providers, or big architectural patterns without clearly calling out that an ADR is needed. |
| 58 | +- Invent secrets or hard‑code real credentials anywhere. |
| 59 | + |
| 60 | +## Working With This Repo |
| 61 | + |
| 62 | +- All dependencies can be setup using the command `make config` from the repository root. |
| 63 | +- **Don’t guess commands.** Derive them from what’s already here or ask for guidance form the human user: |
| 64 | + - Prefer `Makefile` targets, `scripts/`, `.github/workflows/`, and `.github/actions/`. |
| 65 | +- For Terraform, follow `infrastructure/terraform/{components,modules}` and respect `versions.tf`. |
| 66 | +- Keep diffs small and focused. Avoid mixing refactors with behaviour changes unless you explain why. |
| 67 | + |
| 68 | +## Quality Expectations |
| 69 | + |
| 70 | +When proposing a change, agents should: |
| 71 | + |
| 72 | +- Keep code formatted and idiomatic (Terraform, TypeScript, Bash, YAML). |
| 73 | +- Stick to existing patterns where available (for example `utils/logger`, composite actions under `.github/actions`). |
| 74 | +- Use available information on best practices within the specific area of the codebase. |
| 75 | +- **Always** run local pre-commit hooks from the repo root with: |
| 76 | + |
| 77 | + ```sh |
| 78 | + pre-commit run \ |
| 79 | + --config scripts/config/pre-commit.yaml |
| 80 | + ``` |
| 81 | + |
| 82 | + to catch formatting and basic lint issues. Domain specific checks will be defined in appropriate nested AGENTS.md files. |
| 83 | + |
| 84 | +- Suggest at least one extra validation step (for example `npm test` in a lambda, or triggering a specific workflow). |
| 85 | +- 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. |
| 86 | + |
| 87 | +## Security & Safety |
| 88 | + |
| 89 | +- All agent-generated changes **must** be reviewed and merged by a human. |
| 90 | +- Provide a concise, clear summary of the proposed changes to make human review easier (what changed, why (refer directly to the guidance in relevant Agents.MD files when applicable), and how it was validated). It should be directly pastable into the PR description and make it clear that AI assistance was used. |
| 91 | +- Never output real secrets or tokens. Use placeholders and rely on the GitHub/AWS secrets already wired into workflows. |
| 92 | + |
| 93 | +## Escalation / Blockers |
| 94 | + |
| 95 | +If you are blocked by an unavailable secret, unclear architectural constraint, missing upstream module, or failing tooling you cannot safely fix, stop and ask a single clear clarifying question rather than guessing. |
0 commit comments