AGENTS.md — Operating Rules & Contracts for AI Agents

Scope: Ambient Scribe + Guardrailed Clinical Decision Support (CDS).
System of Record (SoR): The EHR (OpenEMR/OpenMRS/Bahmni) for appointments, prescriptions, patient data, problems, allergies, vitals, labs, final notes.
Stack: JavaScript/TypeScript-first (Next.js + Node APIs).
Non-goals (v1): No full EHR. No autonomous clinical decisions. No claims/billing UI. Coding suggestions are read-only in v1.

1) Mission & Outcomes

Mission: Help clinicians produce high-quality notes quickly and surface defensible, cited suggestions—without altering core clinic ops that live in the EHR.

Primary Outcomes

Median note edit time ≤ 90 seconds for common visits.
Citation precision@1 ≥ 90% (human adjudicated).
EHR write reliability ≥ 99% with retries.
Zero “never events” (e.g., unsafe Rx suggestions without human review).

Secondary Outcomes

Latency p95 for evidence lookups ≤ 2s.
ASR word error rate (WER) ≤ 12% in clinic acoustics (EN + Hindi/Bengali variants as available).

2) Non-negotiable Guardrails (READ FIRST)

Human-in-the-loop required. Never auto-finalize a note or prescription. Require an explicit “review/attest” action (
```
ack: human_review=true
```
) before any write to EHR.
Evidence (“Receipts”) required. Every clinical suggestion must include cited sources with quoted spans, URLs, and version metadata (effective date, version hash, retrieved time).
EHR-only writes. Do not own appointments, prescriptions, conditions, allergies, vitals, or final notes. Write them to the EHR via the adapter only, or attach PDFs as
```
DocumentReference
```
if APIs are missing.
No secrets in code. Use environment variables. Never hardcode tokens, PHI, or API keys.
PHI minimization. Prefer feature abstraction for model calls; if PHI must traverse LLMs, ensure zero-retention settings or VPC inference paths are used.
TypeScript everywhere. New code must be in TS with strict typing, zod/typed contracts where relevant.
Retry + audit. All EHR writes are queued and retried; emit immutable audit events with timestamps and user IDs.

Do/Don’t Quick Table

Do	Don’t
Use `EhrAdapter` for all EHR interactions	Call EHR REST/FHIR directly from random modules
Attach citations before showing advice	Render advice without sources or version info
Save final note as PDF via `DocumentReference`	Persist final notes only in app DB
Generate Rx via `MedicationRequest`	Generate Rx PDFs instead of EHR orders when API exists
Queue writes with BullMQ	Fire-and-forget writes
Keep prompts in `/packages/prompts`	Scatter prompt strings across codebase

3) System Topology

Next.js (apps/web) ──▶ Node APIs (apps/api, Fastify/Nest)
   │                            │
   │ Live transcript, edit UI   ├──▶ Scribe Service (LLM → SOAP JSON + flags) 
   │ Evidence panel             ├──▶ Receipts Service (RAG → citations+versioning)
   │ Schedule view (read-only)  └──▶ EHR Adapter (FHIR/OpenEMR/OpenMRS; queued writes)
   │
Postgres (app state, audit) • Redis (BullMQ) • Object storage (audio blobs, optional)

4) Canonical Interfaces (Contracts)

4.1 SOAP Note (internal JSON)

export interface SoapNote {
  subjective: { cc?: string; hpi?: string; meds?: string[]; allergies?: string[] };
  objective: { vitals?: Record<string, string | number>; exam?: string; labs?: string[] };
  assessment: Array<{ problem: string; rationale?: string; citations?: Citation[] }>;
  plan: Array<{ problem: string; orders?: string[]; instructions?: string; followUp?: string }>;
}

export interface Citation {
  title: string;
  url: string;
  sectionPath?: string;
  quote: string;
  versionHash: string;
  effectiveFrom?: string;   // ISO date if provided by source
  retrievedAt: string;      // ISO timestamp
  confidence: number;       // 0..1
}

4.2 EHR Adapter (TypeScript interface)

export interface EhrAdapter {
  upsertPatient(p: Fhir.Patient): Promise<Fhir.Patient>;
  createEncounter(e: Fhir.Encounter): Promise<Fhir.Encounter>;
  createDocumentReference(d: Fhir.DocumentReference): Promise<Fhir.DocumentReference>;
  createMedicationRequest(m: Fhir.MedicationRequest): Promise<Fhir.MedicationRequest>;
  listAppointments(params: { start?: string; end?: string }): Promise<Fhir.Bundle>;
}

Rule: All writes must go through this adapter. If a method is not supported by a site, throw a capability error and fall back to a PDF +
DocumentReference
workflow where applicable.

4.3 API Endpoints (apps/api)

POST /scribe/transcribe

→

{ audioRef }

→

{ transcript, speakers }

POST /scribe/compose

→

{ transcript, patientCtx }

→

{ soap, flags[] }

POST /receipts/attach

→

{ section: 'assessment'|'plan', text }

→

{ citations[] }

POST /ehr/attach-document

→

{ patientId, encounterId, pdfBase64, type }

→

{ docRefId, auditId }

POST /ehr/create-medication-request

→

{ patientId, encounterId, medication, dosage }

→

{ id, auditId }

```
GET  /ehr/appointments?start&end
```
→ FHIR
```
Bundle
```
(read-only)

4.4 Queue Contract (BullMQ)

Job payload:

type EhrJob =
 | { type: 'DocumentReference.create'; payload: Fhir.DocumentReference }
 | { type: 'MedicationRequest.create'; payload: Fhir.MedicationRequest }
 | { type: 'Condition.create'; payload: Fhir.Condition }  // phase 2
 | { type: 'Procedure.create'; payload: Fhir.Procedure }; // phase 2

Job result:

{ ok: true, resourceId: string, statusCode: number }

On failure: retry with exponential backoff; on terminal failure log

audit_event

with stack and sanitized request body.

5) Canonical Workflows (Happy Paths)

5.1 Visit → Note → EHR

Capture audio (edge or browser) →
```
/scribe/transcribe
```
.
Compose SOAP draft →
```
/scribe/compose
```
.
For each assessment/plan item →
```
/receipts/attach
```
→ add citations.
Clinician edits & attests (
```
ack: human_review=true
```
).
Render PDF of final note.
Queue write:
```
DocumentReference.create
```
with the PDF attachment.
Store audit event with
```
patientId
```
,
```
encounterId
```
,
```
docRefId
```
(once written).

5.2 Prescription (EHR as SoR)

Clinician selects medication & dosage from clinic formulary (or search).
Create
```
MedicationRequest
```
via adapter.
If adapter reports unsupported, generate Rx PDF and attach via
```
DocumentReference
```
.
Record audit event with resulting resource ID or
```
docRefId
```
.

5.3 Read-only Scheduling

Call
```
listAppointments
```
with timeframe.
Render day/week views.
Never mutate appointments from this app.

6) Prompting & Receipts Rules

Keep prompts in
```
/packages/prompts
```
with unit tests.
No advice without evidence. Always call
```
/receipts/attach
```
to fetch citations—quote the exact supporting span.
Include version metadata:
```
versionHash
```
,
```
effectiveFrom
```
(if available),
```
retrievedAt
```
.
If sources update, emit a diff alert and mark existing advice as “review needed.”
Disallow language implying autonomy (e.g., “The system prescribes…”). Use “Suggest,” “Consider,” “Evidence supports.”

Example evidence payload:

{
  "citations": [
    {
      "title": "NICE NG128",
      "url": "https://example.org/ng128#4.1",
      "sectionPath": "4.1 Indications",
      "quote": "Offer CTA to adults with red-flag X within 6 hours...",
      "versionHash": "c0b1b8",
      "effectiveFrom": "2024-11-15",
      "retrievedAt": "2025-09-19T08:42:00Z",
      "confidence": 0.82
    }
  ]
}

7) Security, Privacy, Compliance

Consent: Ensure patient consent capture for recording is enabled at clinic level (config flag).
PHI minimization: Prefer abstraction (e.g., “adult chest pain + hypotension”) in LLM calls.
Transport: Enforce HTTPS, TLS 1.2+.
Secrets:
```
.env
```
, secret manager stub; never commit secrets.
Data retention: Audio transient by default. Optional retention policy per clinic with explicit consent.
Audit: Log every suggestion, edit, and EHR write with timestamp, user ID, and hash of payload (no raw PHI in logs).

8) Capability Matrix & Site Profiles

Create one JSON per site in

/configs/sites/<siteId>.json

{
  "ehr": "openemr",
  "baseUrl": "https://ehr.local/fhir/R4",
  "auth": "oauth2",
  "capabilities": {
    "MedicationRequest.create": "supported",
    "DocumentReference.create": "supported",
    "Appointment.search": "supported",
    "Condition.create": "supported",
    "Procedure.create": "partial"
  }
}

Agents must check capabilities before attempting writes; fall back to PDF attach when writes are unsupported.

9) Testing & Evaluation

Unit tests: prompts, parsers, mappers, adapter stubs.
Contract tests: run against local EHR sandbox (Docker Compose).
Eval sets:
- ASR fixtures (
```
/tests/fixtures/asr
```
  ), compute WER.
- Receipts fixtures (
```
/tests/fixtures/receipts
```
  ), compute precision@1/@3 via golden spans.
CI gates:
- Receipts precision@1 ≥ 0.90 on fixtures.
- Adapter contract tests must pass for
```
DocumentReference
```
  and (if supported)
```
MedicationRequest
```
  .

10) Failure Handling Playbook

EHR write 4xx (validation): Surface actionable message to clinician; keep job in DLQ with red badge; allow “Edit & Retry.”
EHR write 5xx/network: Auto-retry with backoff up to 5 times; show “Pending sync” badge.
Receipts empty/no sources: Mark suggestion as “No evidence found”; do not show advice text until evidence exists or clinician overrides with reason.
ASR low confidence: Prompt rephrase or confirm key fields (name, drug, dose).

11) Code Style & Repo Rules

Language: TypeScript strict mode.
Formatting: Prettier + ESLint.
Commits: Conventional Commits; small PRs (<400 LOC).
Docs: Update
```
/docs/ADR
```
when making architectural changes.
Prompts: versioned; include examples and adversarial cases.
Telemetry: No PHI in logs; use IDs/hashes.

12) Quick Start for Agents

Install deps:
```
pnpm i
```
Start infra:
```
docker compose up -d
```
(Postgres, Redis, optional MinIO)
Run API:
```
pnpm -C apps/api dev
```
Run Web:
```
pnpm -C apps/web dev
```
Seed site profile: put a JSON in
```
/configs/sites/dev.json
```
and set
```
SITE_ID=dev
```
in
```
.env
```
Smoke tests:
```
pnpm test
```

13) Roadmap Hooks (for future tasks)

Coding phase 2: Add
```
Condition.create
```
(ICD-10/11),
```
Procedure.create
```
; suggest codes with receipts; clinician approves; write to EHR.
FHIR Provenance: Generate provenance bundles linking final notes to citation artifacts.
Multilingual ASR: Bengali/Hindi models; UI localization.
International presets: Rx formats, units, and date/time localization per market.

14) Glossary (Agent-friendly)

SOAP: Subjective, Objective, Assessment, Plan note structure.
CDS: Clinical Decision Support (advice generation; here guarded by receipts).
Receipts: Our evidence payload (citations with quoted spans + version metadata).
EHR: Electronic Health Record (OpenEMR/OpenMRS/Bahmni).
FHIR: HL7 FHIR standard; R4 endpoints for Patient, Encounter, DocumentReference, MedicationRequest, etc.
DocumentReference: FHIR resource to store/attach documents (e.g., final PDF note, Rx PDF fallback).

Reminder: CDS decides nothing on its own here—clinicians do. The agent’s job is to assist, cite, and safely write to the EHR.

AGENTS.md — Operating Rules & Contracts for AI Agents

Scope: Ambient Scribe + Guardrailed Clinical Decision Support (CDS).
System of Record (SoR): The EHR (OpenEMR/OpenMRS/Bahmni) for appointments, prescriptions, patient data, problems, allergies, vitals, labs, final notes.
Stack: JavaScript/TypeScript-first (Next.js + Node APIs).
Non-goals (v1): No full EHR. No autonomous clinical decisions. No claims/billing UI. Coding suggestions are read-only in v1.

1) Mission & Outcomes

Mission: Help clinicians produce high-quality notes quickly and surface defensible, cited suggestions—without altering core clinic ops that live in the EHR.

Primary Outcomes

Median note edit time ≤ 90 seconds for common visits.
Citation precision@1 ≥ 90% (human adjudicated).
EHR write reliability ≥ 99% with retries.
Zero “never events” (e.g., unsafe Rx suggestions without human review).

Secondary Outcomes

Latency p95 for evidence lookups ≤ 2s.
ASR word error rate (WER) ≤ 12% in clinic acoustics (EN + Hindi/Bengali variants as available).

2) Non-negotiable Guardrails (READ FIRST)

Human-in-the-loop required. Never auto-finalize a note or prescription. Require an explicit “review/attest” action (
```
ack: human_review=true
```
) before any write to EHR.
Evidence (“Receipts”) required. Every clinical suggestion must include cited sources with quoted spans, URLs, and version metadata (effective date, version hash, retrieved time).
EHR-only writes. Do not own appointments, prescriptions, conditions, allergies, vitals, or final notes. Write them to the EHR via the adapter only, or attach PDFs as
```
DocumentReference
```
if APIs are missing.
No secrets in code. Use environment variables. Never hardcode tokens, PHI, or API keys.
PHI minimization. Prefer feature abstraction for model calls; if PHI must traverse LLMs, ensure zero-retention settings or VPC inference paths are used.
TypeScript everywhere. New code must be in TS with strict typing, zod/typed contracts where relevant.
Retry + audit. All EHR writes are queued and retried; emit immutable audit events with timestamps and user IDs.

Do/Don’t Quick Table

Do	Don’t
Use `EhrAdapter` for all EHR interactions	Call EHR REST/FHIR directly from random modules
Attach citations before showing advice	Render advice without sources or version info
Save final note as PDF via `DocumentReference`	Persist final notes only in app DB
Generate Rx via `MedicationRequest`	Generate Rx PDFs instead of EHR orders when API exists
Queue writes with BullMQ	Fire-and-forget writes
Keep prompts in `/packages/prompts`	Scatter prompt strings across codebase

3) System Topology

Next.js (apps/web) ──▶ Node APIs (apps/api, Fastify/Nest)
   │                            │
   │ Live transcript, edit UI   ├──▶ Scribe Service (LLM → SOAP JSON + flags) 
   │ Evidence panel             ├──▶ Receipts Service (RAG → citations+versioning)
   │ Schedule view (read-only)  └──▶ EHR Adapter (FHIR/OpenEMR/OpenMRS; queued writes)
   │
Postgres (app state, audit) • Redis (BullMQ) • Object storage (audio blobs, optional)

4) Canonical Interfaces (Contracts)

4.1 SOAP Note (internal JSON)

export interface SoapNote {
  subjective: { cc?: string; hpi?: string; meds?: string[]; allergies?: string[] };
  objective: { vitals?: Record<string, string | number>; exam?: string; labs?: string[] };
  assessment: Array<{ problem: string; rationale?: string; citations?: Citation[] }>;
  plan: Array<{ problem: string; orders?: string[]; instructions?: string; followUp?: string }>;
}

export interface Citation {
  title: string;
  url: string;
  sectionPath?: string;
  quote: string;
  versionHash: string;
  effectiveFrom?: string;   // ISO date if provided by source
  retrievedAt: string;      // ISO timestamp
  confidence: number;       // 0..1
}

4.2 EHR Adapter (TypeScript interface)

export interface EhrAdapter {
  upsertPatient(p: Fhir.Patient): Promise<Fhir.Patient>;
  createEncounter(e: Fhir.Encounter): Promise<Fhir.Encounter>;
  createDocumentReference(d: Fhir.DocumentReference): Promise<Fhir.DocumentReference>;
  createMedicationRequest(m: Fhir.MedicationRequest): Promise<Fhir.MedicationRequest>;
  listAppointments(params: { start?: string; end?: string }): Promise<Fhir.Bundle>;
}

Rule: All writes must go through this adapter. If a method is not supported by a site, throw a capability error and fall back to a PDF +
DocumentReference
workflow where applicable.

4.3 API Endpoints (apps/api)

POST /scribe/transcribe

→

{ audioRef }

→

{ transcript, speakers }

POST /scribe/compose

→

{ transcript, patientCtx }

→

{ soap, flags[] }

POST /receipts/attach

→

{ section: 'assessment'|'plan', text }

→

{ citations[] }

POST /ehr/attach-document

→

{ patientId, encounterId, pdfBase64, type }

→

{ docRefId, auditId }

POST /ehr/create-medication-request

→

{ patientId, encounterId, medication, dosage }

→

{ id, auditId }

```
GET  /ehr/appointments?start&end
```
→ FHIR
```
Bundle
```
(read-only)

4.4 Queue Contract (BullMQ)

Job payload:

type EhrJob =
 | { type: 'DocumentReference.create'; payload: Fhir.DocumentReference }
 | { type: 'MedicationRequest.create'; payload: Fhir.MedicationRequest }
 | { type: 'Condition.create'; payload: Fhir.Condition }  // phase 2
 | { type: 'Procedure.create'; payload: Fhir.Procedure }; // phase 2

Job result:

{ ok: true, resourceId: string, statusCode: number }

On failure: retry with exponential backoff; on terminal failure log

audit_event

with stack and sanitized request body.

5) Canonical Workflows (Happy Paths)

5.1 Visit → Note → EHR

Capture audio (edge or browser) →
```
/scribe/transcribe
```
.
Compose SOAP draft →
```
/scribe/compose
```
.
For each assessment/plan item →
```
/receipts/attach
```
→ add citations.
Clinician edits & attests (
```
ack: human_review=true
```
).
Render PDF of final note.
Queue write:
```
DocumentReference.create
```
with the PDF attachment.
Store audit event with
```
patientId
```
,
```
encounterId
```
,
```
docRefId
```
(once written).

5.2 Prescription (EHR as SoR)

Clinician selects medication & dosage from clinic formulary (or search).
Create
```
MedicationRequest
```
via adapter.
If adapter reports unsupported, generate Rx PDF and attach via
```
DocumentReference
```
.
Record audit event with resulting resource ID or
```
docRefId
```
.

5.3 Read-only Scheduling

Call
```
listAppointments
```
with timeframe.
Render day/week views.
Never mutate appointments from this app.

6) Prompting & Receipts Rules

Keep prompts in
```
/packages/prompts
```
with unit tests.
No advice without evidence. Always call
```
/receipts/attach
```
to fetch citations—quote the exact supporting span.
Include version metadata:
```
versionHash
```
,
```
effectiveFrom
```
(if available),
```
retrievedAt
```
.
If sources update, emit a diff alert and mark existing advice as “review needed.”
Disallow language implying autonomy (e.g., “The system prescribes…”). Use “Suggest,” “Consider,” “Evidence supports.”

Example evidence payload:

{
  "citations": [
    {
      "title": "NICE NG128",
      "url": "https://example.org/ng128#4.1",
      "sectionPath": "4.1 Indications",
      "quote": "Offer CTA to adults with red-flag X within 6 hours...",
      "versionHash": "c0b1b8",
      "effectiveFrom": "2024-11-15",
      "retrievedAt": "2025-09-19T08:42:00Z",
      "confidence": 0.82
    }
  ]
}

7) Security, Privacy, Compliance

Consent: Ensure patient consent capture for recording is enabled at clinic level (config flag).
PHI minimization: Prefer abstraction (e.g., “adult chest pain + hypotension”) in LLM calls.
Transport: Enforce HTTPS, TLS 1.2+.
Secrets:
```
.env
```
, secret manager stub; never commit secrets.
Data retention: Audio transient by default. Optional retention policy per clinic with explicit consent.
Audit: Log every suggestion, edit, and EHR write with timestamp, user ID, and hash of payload (no raw PHI in logs).

8) Capability Matrix & Site Profiles

Create one JSON per site in

/configs/sites/<siteId>.json

{
  "ehr": "openemr",
  "baseUrl": "https://ehr.local/fhir/R4",
  "auth": "oauth2",
  "capabilities": {
    "MedicationRequest.create": "supported",
    "DocumentReference.create": "supported",
    "Appointment.search": "supported",
    "Condition.create": "supported",
    "Procedure.create": "partial"
  }
}

Agents must check capabilities before attempting writes; fall back to PDF attach when writes are unsupported.

9) Testing & Evaluation

Unit tests: prompts, parsers, mappers, adapter stubs.
Contract tests: run against local EHR sandbox (Docker Compose).
Eval sets:
- ASR fixtures (
```
/tests/fixtures/asr
```
  ), compute WER.
- Receipts fixtures (
```
/tests/fixtures/receipts
```
  ), compute precision@1/@3 via golden spans.
CI gates:
- Receipts precision@1 ≥ 0.90 on fixtures.
- Adapter contract tests must pass for
```
DocumentReference
```
  and (if supported)
```
MedicationRequest
```
  .

10) Failure Handling Playbook

EHR write 4xx (validation): Surface actionable message to clinician; keep job in DLQ with red badge; allow “Edit & Retry.”
EHR write 5xx/network: Auto-retry with backoff up to 5 times; show “Pending sync” badge.
Receipts empty/no sources: Mark suggestion as “No evidence found”; do not show advice text until evidence exists or clinician overrides with reason.
ASR low confidence: Prompt rephrase or confirm key fields (name, drug, dose).

11) Code Style & Repo Rules

Language: TypeScript strict mode.
Formatting: Prettier + ESLint.
Commits: Conventional Commits; small PRs (<400 LOC).
Docs: Update
```
/docs/ADR
```
when making architectural changes.
Prompts: versioned; include examples and adversarial cases.
Telemetry: No PHI in logs; use IDs/hashes.

12) Quick Start for Agents

Install deps:
```
pnpm i
```
Start infra:
```
docker compose up -d
```
(Postgres, Redis, optional MinIO)
Run API:
```
pnpm -C apps/api dev
```
Run Web:
```
pnpm -C apps/web dev
```
Seed site profile: put a JSON in
```
/configs/sites/dev.json
```
and set
```
SITE_ID=dev
```
in
```
.env
```
Smoke tests:
```
pnpm test
```

13) Roadmap Hooks (for future tasks)

Coding phase 2: Add
```
Condition.create
```
(ICD-10/11),
```
Procedure.create
```
; suggest codes with receipts; clinician approves; write to EHR.
FHIR Provenance: Generate provenance bundles linking final notes to citation artifacts.
Multilingual ASR: Bengali/Hindi models; UI localization.
International presets: Rx formats, units, and date/time localization per market.

14) Glossary (Agent-friendly)

SOAP: Subjective, Objective, Assessment, Plan note structure.
CDS: Clinical Decision Support (advice generation; here guarded by receipts).
Receipts: Our evidence payload (citations with quoted spans + version metadata).
EHR: Electronic Health Record (OpenEMR/OpenMRS/Bahmni).
FHIR: HL7 FHIR standard; R4 endpoints for Patient, Encounter, DocumentReference, MedicationRequest, etc.
DocumentReference: FHIR resource to store/attach documents (e.g., final PDF note, Rx PDF fallback).

Reminder: CDS decides nothing on its own here—clinicians do. The agent’s job is to assist, cite, and safely write to the EHR.

AGENTS.md — Operating Rules & Contracts for AI Agents

Related Skills

Markdown Converter

Nano Banana Pro

1password