AGENTS.md

1# AGENTS.md
2 
3This repository is built to be understandable by humans and coding agents.
4 
5## Mission
6 
7Build MedLens+ as a safety-first, longitudinal medical report intelligence platform.
8 
9## Clinical Golden Rules (Non-Negotiable)
10 
111. Never diagnose disease.
122. Never prescribe medication.
133. Never suggest dosage changes.
144. Never claim "you have X disease."
155. Never replace professional consultation.
166. Always use uploaded report reference ranges, not internet-generic ranges.
177. Always show caution when comparing reports from different labs.
18 
19## Engineering Standards
20 
21- Follow typed contracts and schema-first design.
22- Keep frontend and backend decoupled by language/runtime.
23- Share cross-language contracts via OpenAPI/JSON schema, not shared runtime code.
24- Add tests for parser, normalization, trends, and safety filters.
25- Any AI flow change must include prompt/version metadata.
26 
27## Branch Strategy (Main-First)
28 
29- Branch **from `main`** (production baseline)
30- Open PRs to **`develop`** (features) or **`main`** (hotfixes)
31- **Naming:** [`docs/07-open-source/03-NAMING_CONVENTIONS.md`](docs/07-open-source/03-NAMING_CONVENTIONS.md) — `feat/TKT-NNN-slug`, conventional commits (body ≤100 chars/line), semantic PR title
32- Promotion: `develop` → `main` (maintainers)
33- After `main` updates, `sync-develop.yml` fast-forwards `develop` when trees match (see [`docs/07-open-source/04-BRANCHING_STRATEGY.md`](docs/07-open-source/04-BRANCHING_STRATEGY.md))
34 
35## Ticket Source
36 
37- [GitHub Project #2](https://github.com/users/itxSaaad/projects/2) — not local `planning/tickets/`
38 
39## PR Requirements
40 
41- Link a GitHub issue (`Closes #NNN`) from the [Project Board](https://github.com/users/itxSaaad/projects/2)
42- Mention user impact and safety impact
43- Include test evidence
44- Include privacy/security notes
45 
46## Done Criteria
47 
48- Functional acceptance criteria met
49- Tests pass locally and in CI
50- Docs updated
51- Safety and privacy checklist complete
52 
53## Agent Work Order
54 
551. Read ticket on [Project #2](https://github.com/users/itxSaaad/projects/2)
562. Branch with correct name (`feat/TKT-NNN-slug` or `chore/scope` per naming doc)
573. Validate architecture alignment
584. Implement with tests; commits must pass commitlint locally
595. Update docs and changelog
606. Open PR with template + `Closes #NNN`; run `pnpm lint` before push
61