Skip to content

Commit 3dc3bcf

Browse files
jamesthompson26-nhsjamesthompson26-nhs
committed
CCM-12833: AgentsMD Nested - DO NOT MERGE
1 parent 3467ab2 commit 3dc3bcf

File tree

6 files changed

+974
-0
lines changed

6 files changed

+974
-0
lines changed

‎agents.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
## Core Agent Guidance (Platform-Agnostic)
2+
3+
This file now focuses on cross-cutting agent usage principles that apply regardless of technology (Terraform, TypeScript, frontend). Technology-specific detail has moved to:
4+
5+
| Domain | Location |
6+
|--------|----------|
7+
| Terraform (Infra workflow, IAM, modules) | `infrastructure/terraform/agents-terraform.md` |
8+
| TypeScript (Lambdas, shared packages, frontend) | `lambdas/agents-typescript.md` |
9+
10+
_Last reorganised: 2025-11-07_
11+
12+
### 1. Engagement Model
13+
Human creates branch & supplies ticket context (JIRA ID, acceptance criteria, scope, non-goals). Agent never creates branches or merges; it produces validated changes then stops.
14+
15+
### 2. Agent Responsibilities (Invariant)
16+
1. Operate only inside provided branch.
17+
2. Minimise surface area of change; no speculative refactors.
18+
3. Apply existing naming, logging, validation, and security patterns.
19+
4. Annotate unavoidable deviations with a concise rationale comment (`// agent: rationale <brief>` or `# agent: rationale <brief>`).
20+
5. Run relevant quality gates (typecheck, lint, tests, terraform validate) before handover.
21+
6. Produce a handover summary (files touched, IAM delta, risks, rollback hint).
22+
23+
### 3. Quality Gates (Selector)
24+
| Scenario | Required Gates |
25+
|----------|----------------|
26+
| Pure Terraform change | `terraform fmt`, `terraform validate` |
27+
| Lambda / TypeScript code | `npm run typecheck`, `npm run lint`, `npm run test:unit` |
28+
| Frontend (React/Next) | Above + accessibility tests if UI affected |
29+
| Mixed (Infra + Code) | Union of both sets |
30+
31+
Optional (on demand): gitleaks, trivy, syft, scorecard.
32+
33+
### 4. Adding a New Lambda (Workspace & Build Integration)
34+
Follow this process so monorepo workspaces, build scripts and infra remain consistent:
35+
36+
1. Create folder: `lambdas/<function-name>` using kebab-case.
37+
2. Scaffold contents:
38+
- `package.json` (private, name `@notify/<function-name>`, scripts: `build`, `typecheck`, `lint`, `test:unit`).
39+
- `tsconfig.json` (extends root or sibling lambda config).
40+
- `jest.config.ts` (mirroring existing lambda configs).
41+
- `build.sh` invoking `esbuild` bundling to `dist/`.
42+
- `src/` with entry file exporting `handler` and domain modules.
43+
- `__tests__/` with at least happy path + one failure case.
44+
3. Add workspace entry in root `package.json` under `workspaces` (maintain alphabetical grouping by top-level path).
45+
4. Run: `npm install` at root to ensure workspace linking.
46+
5. Add infrastructure module invocation (Terraform) in appropriate `.tf` file referencing new lambda dist path & env vars.
47+
6. Provide minimal IAM policy document (`data "aws_iam_policy_document"`) granting least privilege.
48+
7. Update any shared environment variable local maps if new keys required.
49+
8. Execute quality gates for both infra & TS (see table above).
50+
9. Include in handover summary: workspace addition, new module file(s), IAM diff, test coverage note.
51+
52+
### 5. Monorepo Workspace Conventions
53+
Root `package.json` uses npm workspaces. Keep order logical (group by area). When adding a lambda ensure:
54+
```
55+
"workspaces": [
56+
"data-migration/user-transfer",
57+
"frontend",
58+
"lambdas/authorizer",
59+
"lambdas/backend-api",
60+
"lambdas/backend-client",
61+
"lambdas/cognito-triggers",
62+
"lambdas/download-authorizer",
63+
"lambdas/event-publisher",
64+
"lambdas/sftp-letters",
65+
"lambdas/<new-function>",
66+
"packages/event-schemas",
67+
...
68+
]
69+
```
70+
Position `<new-function>` with existing lambda block (keep alphabetical within that block to reduce diff churn).
71+
72+
### 6. CI / Automation Notes
73+
- Scorecard workflow (`.github/workflows/scorecard.yml`) runs on `main` push & scheduled; agent changes should not adjust it unless explicitly tasked.
74+
- Future CI additions (tests, security scans) should live in dedicated workflow files named by concern (`test.yml`, `security.yml`).
75+
- Do not embed secrets in workflow; reference pre-defined repository secrets.
76+
- Pin action versions (use commit SHA or semver tag) for reproducibility.
77+
- If adding a workflow, include a short comment header with purpose and contact.
78+
79+
### 7. Commit Guidelines (Universal)
80+
Format: `<JIRA-ID> <imperative summary>` (no trailing period). Keep commits cohesive (infra vs code). Avoid mixing refactor with feature unless mandated.
81+
82+
### 8. Rationale Comment Pattern
83+
Keep to a single line:
84+
```hcl
85+
# agent: rationale increase memory (PDF generation spikes >512MB)
86+
```
87+
```ts
88+
// agent: rationale temporary union type until schema v2 lands
89+
```
90+
Remove obsolete rationales before handover if decision becomes standard.
91+
92+
### 9. Rollback Considerations
93+
- Infra: prefer additive changes; for destructive (table rename, pipe removal) document pre-change state.
94+
- Code: if altering handler signature, note previous export contract.
95+
- Provide one-line rollback instruction in handover summary.
96+
97+
### 10. Escalation / Blockers
98+
If blocked by unavailable secret, unclear architectural constraint, or missing upstream module, stop and ask a single clarifying question rather than guessing.
99+
100+
### 11. Where to Go for Detail
101+
- Terraform specifics: `infrastructure/terraform/agents.md`
102+
- TypeScript & Lambda specifics: `lambdas/agents.md`
103+
- Shared schemas & events: `packages/event-schemas/agents.md`
104+
- Scripts: `scripts/agents.md`

‎frontend/agents.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# TypeScript Style & Ways of Working (Agents & Copilot)
2+
3+
> Extracted from root `agents.md` Section 16 (2025-11-07). Terraform-specific guidance now lives in `infrastructure/terraform/agents-terraform.md`.
4+
5+
This document defines conventions for TypeScript across Lambdas, shared packages and the Next.js frontend. It complements Terraform guidance (security, determinism, least privilege) with code-level consistency, testability and readability. Use these rules for both autonomous agent code generation touching TypeScript and interactive AI pair programming (Copilot).
6+
7+
## 1. Project Structure & Module Boundaries
8+
- Each Lambda function lives in `lambdas/<function-name>` with `src/`, `__tests__/`, build script (`build.sh` using `esbuild`), output in `dist/`.
9+
- Backend API Lambdas: thin entry file delegating to API handler factory.
10+
```ts
11+
export const handler = createHandler(templatesContainer());
12+
```
13+
- Domain logic separated from transport (e.g. `api/` vs `domain/`). Keep handler composition pure/injectable.
14+
- Shared packages expose `index.ts` re-export barrels.
15+
16+
## 2. Naming Conventions (ESLint-Enforced)
17+
Follow the repository ESLint configuration rather than relying on this document for exhaustive rules. Key points are enforced automatically:
18+
| Concern | Enforcement Source |
19+
|---------|--------------------|
20+
| Filenames (kebab-case for files) | Custom/file naming lint rules & PR review |
21+
| Exported functions/constants camelCase | ESLint stylistic rules |
22+
| Types & interfaces PascalCase | `@typescript-eslint/naming-convention` |
23+
| Handler export name `handler` | Manual review + tests referencing handler |
24+
| Zod schemas prefixed with `$` | Convention (add if missing); not auto-enforced |
25+
| Factory functions suffix `create`/`make` | Convention to enhance intent |
26+
27+
Agent guidance: Run `npm run lint` and fix reported issues; do not duplicate rule text here. If a required naming change would create wide churn, limit edits to touched lines and add a `// agent: rationale partial naming normalisation` comment if inconsistent legacy remains.
28+
29+
## 3. Import Ordering (ESLint-Enforced)
30+
Ordering (built-ins → external → internal aliases → relative) is governed by ESLint (`import/order`). Agents should:
31+
1. Avoid manual reordering of untouched blocks unless lint fails.
32+
2. Preserve grouping and let `--fix` handle spacing/blank lines.
33+
3. If adding a new import, place it in the correct group; run `npm run lint:fix` to auto-format.
34+
35+
Do not include example blocks; the linter output will indicate misplacement. Add rationale comment only if a deliberate cycle prevents ideal ordering.
36+
37+
## 4. Types vs Interfaces
38+
Use `type` for unions/intersections; `interface` for extensible object shapes. Use `z.infer<typeof $Schema>` for types derived from Zod.
39+
40+
## 5. Runtime Validation & Schema Design
41+
- Validate all external input with Zod at the boundary; parse early.
42+
- Use `.extend`, `.intersection`, `.omit` to compose.
43+
- Include `.meta({ id: '...' })` for identification.
44+
45+
## 6. Environment Variables & Configuration
46+
- Validate env vars (Zod object). Coerce numeric values.
47+
- Parse complex JSON only after validation.
48+
- Throw early if required vars absent.
49+
50+
## 7. Error Handling Patterns
51+
- API handlers return structured success/failure objects; avoid throwing for expected validation failures.
52+
- Batch SQS: validate each record; DLQ or skip unprocessable payloads.
53+
54+
## 8. Functional Composition & Dependency Injection
55+
- Use factory functions returning handlers.
56+
- Containers construct dependency graph (clients, repositories, loggers) and return pure objects.
57+
- Avoid global singletons except for AWS SDK efficiency; pass constructed clients.
58+
59+
## 9. CSV / Data Processing
60+
- Deterministic header set from union of record keys; sorted alphabetically.
61+
- RFC4180 escaping (double quotes, wrap fields containing comma/quote/newline).
62+
- Keep transformation functions pure and test them.
63+
64+
## 10. Testing Conventions
65+
- Jest config per package; test files `__tests__/<name>.test.ts`.
66+
- Mock AWS SDK v3 clients by overriding `send`.
67+
- Use shared test helper factories (e.g. `makeSQSRecord`, `createMockLogger`).
68+
- Assert observable response shapes; avoid internal implementation details.
69+
70+
## 11. Async & Promise Handling
71+
Use `async/await`. Sequential `for...of` loops for ordered processing; `Promise.all` only for independent operations.
72+
73+
## 12. Logging
74+
- Use structured `winston` logger; inject via container.
75+
- Log identifiers (templateId, clientId) not full sensitive payloads.
76+
77+
## 13. Security & PII
78+
- Never log secrets or personal data; redact or summarise.
79+
- Centralise CSP construction with nonce in frontend middleware.
80+
81+
## 14. Performance & Memory
82+
- Lambda memory: 512 MB default (light); 2048 MB for heavy tasks (PDF, complex transform). Justify deviations with comment.
83+
- Avoid unnecessary JSON (de)serialization cycles.
84+
85+
## 15. Formatting & Lint
86+
Formatting (quotes, semicolons, trailing commas, spacing) and stylistic concerns are entirely delegated to ESLint/Prettier configuration in the repo. Agent process:
87+
1. After code changes run: `npm run lint` and `npm run lint:fix` (if permitted) to apply canonical style.
88+
2. Do not handcraft style changes beyond what the linter requires for the modified lines.
89+
3. If large unrelated formatting noise appears, revert non-essential edits to minimise diff surface.
90+
91+
Examples are intentionally omitted; rely on linter output for corrections.
92+
93+
## 16. Export Strategy
94+
- Prefer named exports. Use barrel `index.ts` for re-exports. Avoid CommonJS patterns.
95+
96+
## 17. Utility Patterns
97+
- Inline single-use pure utilities; extract to `utils/` if reused >2 times.
98+
- Group regex or security policies in top-level constants.
99+
100+
## 18. Testing Edge Cases (Minimum)
101+
For each handler include: happy path, missing/invalid auth/env, validation failure, empty batch (no-op).
102+
103+
## 19. Error Object Shape
104+
Standard failure JSON: `{ statusCode, technicalMessage, details? }`. No internal stack traces to clients.
105+
106+
## 20. Comment Standards
107+
- Use `//` for brief notes; block comments only for multi-line protocol references.
108+
- Link external specs (e.g. CloudEvents) where relevant.
109+
110+
## 21. AI / Agent Usage Notes (TypeScript)
111+
- Provide a mini contract before requesting generation: inputs, outputs, error modes, key edge cases.
112+
- Reject suggestions lacking types or validation.
113+
- Ensure new handlers follow dependency injection & logging patterns.
114+
- Use commit convention `<JIRA-ID> <imperative summary>`.
115+
- Annotate any deviation with `// agent: rationale <brief>`.
116+
117+
## 22. Quality Gates (When TS code is generated/modified)
118+
Run locally before handover:
119+
```bash
120+
npm run typecheck
121+
npm run lint
122+
npm run test:unit
123+
```
124+
(Include accessibility tests if frontend changes: `npm run test:accessibility`.)

0 commit comments

Comments
 (0)