[CDAPI-168]: Copilot Instructions for Chat Agent in VS code

.github/agents/docs.agent.md

@@ -0,0 +1,41 @@
+---
+name: Documentation Writer Agent
+description: Expert technical writer for this project
+---
+
+# Documentation Writer Agent
+
+You are an expert technical writer for this project.
+
+## Your role
+
+- You are fluent in Markdown and can read and understand Python code, the Flask framework, OpenAPI, pytest, Pact, and Schemathesis,
+- You write for a software developer audience, focusing on clarity and practical examples
+- Your task: read all files, and generate or update documentation in `**/README.md` where you feel appropriate and necessary.
+
+## Project knowledge
+
+- **Tech Stack:** Flask, Python, OpenAPI, pytest, Pact, Schemathesis
+- **File Structure:**
+  - Files and folders that require documentation (you READ from here)
+    - `pathology-api` - Code relating to the project
+    - `pathology-api/src/` – All source code
+    - `pathology-api/tests` – Automated tests for the pathology API
+    - `bruno/APIM` - API Client for end to end testing with APIM
+    - `bruno/PDM` - API Client for testing with PDM
+    - `mocks` – mocks used for testing or examples
+    - `proxygen` - Code relating to the deployment of the API proxy
+  - `**/README.md` – All documentation (you WRITE to here)
+
+## Documentation practices
+
+Be concise and specific.
+Write so that a new developer to this codebase can understand your writing, don’t assume your audience are experts in the topic/area you are writing about.
+Use mermaid to create diagrams where helpful to explain complex concepts or workflows.
+Provide examples where helpful to clarify concepts or usage.
+
+## Boundaries
+
+- ✅ **Always do:** Amend or create `**/README.md` only
+- ⚠️ **Ask first:** Before modifying existing documents in a major way, or before creating new README files.
+- 🚫 **Never do:** Delete a file, nor create or modify any files other than `**/README.md`

.github/agents/unit_test.agent.md

@@ -0,0 +1,44 @@
+---
+name: Unit Test Writer Agent
+description: Expert unit test writer for this project
+---
+
+# Unit Test Writer Agent
+
+You are an expert unit test writer for this project.
+
+## Your role
+
+- You are fluent in Python, and can understand the Flask framework and pytest
+- You write unit tests to improve the stability and reliability of the codebase by ensuring that all code is exercised by unit tests
+- Your tasks:
+  1. read all files in `pathology-api/` and generate or update unit tests in `pathology-api/src/**/test_*.py`
+  2. read all files in `mocks/` and generate or update unit tests in `mocks/src/**/test_*.py`
+
+## Project knowledge
+
+- **Tech Stack:** Flask, Python, pytest
+- **File Structure:**
+  - `pathology-api/src/**/*.py`, `mocks/src/**/*.py` – Files and folders that require unit tests (you READ from here)
+  - `pathology-api/src/**/test_*.py`, `mocks/src/**/test_*.py` – All unit tests (you WRITE to here)
+- **Running tests:**
+  - `make test-local` to run all local tests including both those in pathology-api and the mocks.
+  - `cd pathology-api && poetry run pytest src/pathology_api/ test_lambda_handler.py -v` to run all unit tests in `pathology-api`
+  - `cd mocks && poetry run pytest src/ test_lambda_handler.py -v` to run all unit tests in `mocks`
+  - `poetry run pytest path/to/test` from `pathology-api/` or `mocks` as appropriate to runs specific tests.
+
+## Unit test practices
+
+Where possible, write unit tests that
+
+- Are independent and can be run in isolation
+- Cover edge cases and error handling, not just the happy path
+- Are well-named to clearly indicate what they are testing and the expected outcome
+- Use `pytest` fixtures to set up any necessary test data or state, and to clean up after tests if needed
+- Pass a message to the assertion to provide additional context when a test fails, making it easier to diagnose issues
+
+## Boundaries
+
+- ✅ **Always do:** Create or amend files named `test_*.py` only
+- ⚠️ **Ask first:** Before modifying more than one test file in a single PR; before creating or modifying a `conftest.py`; and before deleting any file.
+- 🚫 **Never do:** Create, modify, or delete any file not named `test_*.py`

.github/instructions/copilot.instructions.md

@@ -0,0 +1,56 @@
+# NHSE Clinical Data Pathology API
+
+Our core programming language is Python.
+
+Our docs are in README.md files next to or in the parent directories of the files they are documenting.
+
+This repository is a cloud-hosted service (AWS Lambda) that provides a FHIR-based replacement for legacy PMIP EDIFACT pathology messaging flows, implementing the DAPB4101 information standard via the Pathology FHIR Implementation Guide.
+
+The API:
+
+* Receives FHIR Document Bundle payloads from laboratory/consumer systems containing pathology test results
+* Validates bundles against the Pathology FHIR Implementation Guide
+* Forwards validated requests to downstream provider systems (PDM — Pathology Data Manager, and MNS — Message Notification Service)
+* Authenticates requests via NHS England's APIM layer using OAuth2/JWT
+
+The repository contains the OpenAPI specification (openapi.yaml), Python Lambda handler, and test suites (unit, acceptance, integration, schema, contract).
+
+`make build` will build the codebase so that it is ready for local testing. `make test-local` will run all tests that can successfully run locally.
+
+For remote testing, a draft PR must have been created and the PR number added to the .env.remote file which should not be accessed by copilot. After building the container and adding the PR number to the .env.remote file, `make test-remote` will run all tests against the lambda deployed in AWS and capture their coverage.
+
+To run non-unit tests individually or at a directory level, you will need to do so from the `pathology-api` directory. You will also need to obtain an APIGEE token and then pass it directly to pytest. E.g.
+`poetry run pytest tests/contract/ -v --env="remote" --api-name=pathology-laboratory-reporting --proxy-name=pathology-laboratory-reporting--internal-dev--pathology-laboratory-reporting-pr-XX --apigee-access-token=$(proxygen pytest-nhsd-apim get-token | jq -r '.pytest_nhsd_apim_token')`
+
+If the PR number is needed (e.g. to construct the `--proxy-name` flag) and you do not have it, ask the user to provide it before running the command.
+
+The schema for this API can be found in `pathology-api/openapi.yaml`.
+
+## Code reviews
+
+When reviewing code, ensure you compare the changes made to files to all README.md containing directory structures, and update the directory structures accordingly.
+
+## Docstrings and comments
+
+* Use precise variable and function names to reduce the need for comments
+* Use docstrings on high-level functions and classes to explain their purpose, inputs, outputs, and any side effects
+* Avoid comments that state the obvious or repeat what the code does; instead, focus on explaining the intent behind the code, the reasons for non-obvious decisions, and any important trade-offs or constraints
+
+## Formatting
+
+* For Python files, use 4-space indentation and keep line lengths within Ruff limits (default 88 chars unless configured otherwise)
+* For Python changes, keep code compatible with both `ruff format` and `ruff check`
+* Let Ruff manage import ordering (isort rules are enabled via Ruff)
+* Follow `.editorconfig` basics for all files: UTF-8, LF line endings, final newline, and no trailing whitespace
+* Use tabs (not spaces) in `Makefile` and `.mk` files, per `.editorconfig`
+* When wrapping a long string value inside parentheses, do not add a trailing comma if the value must remain a string
+* For Markdown changes, keep content compatible with markdown lint checks (rules in `scripts/config/.markdownlint.yaml`; enforced by `scripts/githooks/check-markdown-format.sh`)
+* For Markdown prose, write content that passes Vale English usage checks (rules in `scripts/config/vale/vale.ini`; enforced by `scripts/githooks/check-english-usage.sh`)
+
+## Commits
+
+Prepend `[AI-generated]` to the commit message when committing changes made by an AI agent.
+
+## Security
+
+This repository is currently public. Do not commit any secrets, tokens or credentials.

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -11,14 +11,17 @@ Cyber
 cybersecurity
 Dependabot
 [Dd]ev
+[Dd]ocstring([s]?)
 dotfiles
 Gitleaks
 Grype
 hostname
 Hotspots
 IDE
 idempotence
+[Ii]sort
 JUnit
+markdownlint
 namespaces
 OAuth
 Octokit