Prd2 agentforge

.cursor/rules/AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc

@@ -0,0 +1,59 @@
+---
+description: >-
+  PRD2 Modernized (patient dashboard Next.js) — sub-agent roles, default models, and
+  governance aligned with Documentation/PRD2_MODERNIZED.md and AUDIT_PRD2_MODERNIZED.md.
+globs:
+  - frontend/**
+  - Documentation/**
+alwaysApply: false
+---
+
+# AGENT_TEAM PRD2 MODERNIZED — subagent roster
+
+**Requirements and doc canon:** [`Documentation/PRD2_MODERNIZED.md`](../../Documentation/PRD2_MODERNIZED.md), [`Documentation/ARCHITECTURE_PRD2_MODERNIZED.md`](../../Documentation/ARCHITECTURE_PRD2_MODERNIZED.md), [`Documentation/AUDIT_PRD2_MODERNIZED.md`](../../Documentation/AUDIT_PRD2_MODERNIZED.md). All Next.js paths below live under **`frontend/`** (see [`prd2-patient-dashboard-modernization` skill](../skills/prd2-patient-dashboard-modernization/SKILL.md)).
+
+Cursor does not spawn separate runnable subagents from this file; use it to **assume the correct role**, **pick models** at delegation time (Chat/Composer settings), and **hand off** with explicit role prompts.
+
+**Cross-track:** If a change touches **both** `interface/modules/custom_modules/oe-module-clinical-copilot/**` and **`frontend/`** or **Modernized `Documentation/`**, follow [`.cursor/rules/AGENT-TEAM-PRD2-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-Subagents-Roster.mdc) and [`.cursor/rules/PRD-2-AgentForge-Agent-Roster.mdc`](PRD-2-AgentForge-Agent-Roster.mdc) for the module **and** this file for the dashboard track.
+
+**Human Lead:** Monica Peters — Architecture approval, security sign-off, deployment authorization, final sign-off on all documents. NOT an AI agent.
+
+## PRD2 Modernized roles (Next.js + governance docs)
+
+Where a role omits a model, default to **GPT-4o-mini** for narrow tasks and **GPT-4o** or **Claude Sonnet** for architecture/security reviews.
+
+| Role                    | Suggested model                        | Responsibilities                         |
+| ----------------------- | -------------------------------------- | ---------------------------------------- |
+| **Planner Agent**       | **claude-sonnet-4-20250514 or gpt-4o** | Planning, decomposition, task assignment. Does NOT spawn Workers until human Lead Architect has signed off on ADR-001 through ADR-006 in [`Documentation/AUDIT_PRD2_MODERNIZED.md`](../../Documentation/AUDIT_PRD2_MODERNIZED.md). |
+| **auth-implementer**    | **claude-sonnet-4-20250514**           | OAuth2/OIDC flow only. `frontend/lib/auth/`, `frontend/app/api/auth/`, `frontend/app/login/`. Does NOT touch FHIR, components, or deployment. |
+| **fhir-client-builder** | **claude-sonnet-4-20250514**           | FHIR types, client, and hooks only. `frontend/lib/fhir/`, `frontend/hooks/`. Does NOT build UI or touch auth. |
+| **card-component-builder** | **claude-sonnet-4-20250514**        | All clinical card UI components. `frontend/components/cards/`, `frontend/components/shared/`. Consumes hooks from fhir-client-builder. Enforces three-state pattern (Loading/Error/Empty) on all cards per ADR-005. |
+| **layout-shell-builder**   | **claude-sonnet-4-20250514**        | Dashboard shell, patient banner, page routing. `frontend/components/layout/`, `frontend/app/dashboard/`. Consumes cards as children. |
+| **deployment-verifier**    | **claude-sonnet-4-20250514**        | Deployment config, Playwright tests, final integration verification. Does NOT write application code. |
+| **Security Audit Agent** | **claude-sonnet-4-20250514**           | Review-only gate, not a code author. Reviews auth-implementer output for token exposure (Risk R-001). Reviews proxy route for SSRF. Verifies no PHI in client code. |
+| **Performance Agent**   | **gpt-4o-mini**                        | Rendering, bundles, caching; align with architecture latency goals. |
+| **Documentation Agent** | **gpt-4o-mini**                        | Repo docs, onboarding, architecture alignment (respect fork doc policy). |
+| **Verification Agent**  | **gpt-4o-mini** (+ CI/tests)           | Regression mindset, schema/runtime validation, E2E scenarios. |
+
+## Agent governance (non-negotiable)
+
+- No autonomous deployment.
+- No unsupervised merge approval.
+- Human accountability mandatory.
+- All outputs auditable.
+- Rollback capability preserved.
+- Planner Agent must confirm ACR checklist item completion in [`Documentation/AUDIT_PRD2_MODERNIZED.md`](../../Documentation/AUDIT_PRD2_MODERNIZED.md) before marking task as complete.
+
+## Quick delegation map (Modernized)
+
+- **Next.js UI components** → card-component-builder + layout-shell-builder.
+- **FHIR data fetching** → fhir-client-builder.
+- **Auth / token / proxy** → auth-implementer + Security Audit Agent + [`.cursor/rules/PRD2-Modernized-Frontend-Security.mdc`](PRD2-Modernized-Frontend-Security.mdc).
+- **Playwright / parity** → deployment-verifier + Verification Agent + [`prd2-patient-dashboard-modernization` skill](../skills/prd2-patient-dashboard-modernization/SKILL.md).
+- **Clinical CoPilot module** (PDF, RAG, EHR Writer) → [`.cursor/rules/AGENT-TEAM-PRD2-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-Subagents-Roster.mdc).
+
+## Related
+
+- [`.cursor/rules/PRD2-Modernized-Scope-and-Docs.mdc`](PRD2-Modernized-Scope-and-Docs.mdc) — scope, branch discipline, PHP monolith boundary.
+- [`.cursor/skills/agent-team-prd2/SKILL.md`](../skills/agent-team-prd2/SKILL.md) — delegation pattern for both rosters.
+- [`.cursor/rules/PRD-1-AgentForge-Clinical-Copilot.mdc`](PRD-1-AgentForge-Clinical-Copilot.mdc) — fork `master` / upstream policy.

.cursor/rules/AGENT-TEAM-PRD2-Subagents-Roster.mdc

@@ -0,0 +1,53 @@
+---
+description: >-
+  PRD2 Clinical CoPilot (PHP module) — sub-agent roles, default models, and governance.
+  Detailed responsibilities and flow: PRD-2-AgentForge-Agent-Roster.mdc.
+globs:
+  - interface/modules/custom_modules/oe-module-clinical-copilot/**
+alwaysApply: false
+---
+
+# AGENT_TEAM PRD2 Clinical CoPilot — subagent roster
+
+**Scope:** `interface/modules/custom_modules/oe-module-clinical-copilot/**` — PRD 2 AgentForge Clinical CoPilot, **not** the patient dashboard Next.js track.
+
+**Authoritative detail:** Full model responsibilities, flow diagram, citation contract, and CoPilot-specific non-negotiables live in [`.cursor/rules/PRD-2-AgentForge-Agent-Roster.mdc`](PRD-2-AgentForge-Agent-Roster.mdc). Module README and local architecture notes live under the module tree.
+
+Cursor does not spawn separate runnable subagents from this file; use it to **assume the correct role**, **pick models** at delegation time (Chat/Composer settings), and **hand off** with explicit role prompts.
+
+**Cross-track:** If a change touches **both** this module and **`frontend/`** or Modernized **`Documentation/`**, follow this roster **and** [`.cursor/rules/AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc) plus path-specific rules.
+
+**Human Lead:** Monica Peters — Architecture approval, security sign-off, deployment authorization, final sign-off on all documents. NOT an AI agent.
+
+## Clinical CoPilot roles (summary)
+
+| Role | Default model | Why (summary) |
+| ---- | ------------- | ------------- |
+| **Lead Agent** | **GPT-4o** | Planning, decomposition, complex system prompts; final grounded answer after verification. |
+| **Supervisor** | **GPT-4o-mini** | Routing: when to run file processing, summarization/evidence path, EHR persistence; inspectable handoffs. |
+| **Subagent 1 — File Processor** | **Gemini 1.5 Flash** | Large context for patient PDFs / messy OCR. |
+| **Subagent 2 — Summarizer** | **Llama 3.1 70B** | Structured JSON; guideline-oriented synthesis / clinical summaries. |
+| **Subagent 3 — EHR Writer** | **GPT-4o-mini** | OpenEMR-shaped writes via **server-controlled** APIs/hooks only (no direct DB). |
+
+## Agent governance (non-negotiable)
+
+- No autonomous deployment.
+- No unsupervised merge approval.
+- Human accountability mandatory.
+- All outputs auditable.
+- Rollback capability preserved.
+
+Modernized-track gates (ADR/ACR, [`Documentation/AUDIT_PRD2_MODERNIZED.md`](../../Documentation/AUDIT_PRD2_MODERNIZED.md)) apply only to **PRD2 Modernized** work — see [`.cursor/rules/AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc).
+
+## Quick delegation map (Clinical CoPilot)
+
+- **PDF / multimodal intake** → Subagent 1 — File Processor (Gemini 1.5 Flash).
+- **Guideline / RAG synthesis** → Subagent 2 — Summarizer (Llama 3.1 70B).
+- **Structured writes to OpenEMR** → Subagent 3 — EHR Writer (GPT-4o-mini) **after** server validation pipeline.
+- **Patient dashboard Next.js / FHIR UI** → [`.cursor/rules/AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc).
+
+## Related
+
+- [`.cursor/skills/agent-team-prd2/SKILL.md`](../skills/agent-team-prd2/SKILL.md) — delegation pattern for both rosters.
+- [`.cursor/rules/PRD-1-AgentForge-Clinical-Copilot.mdc`](PRD-1-AgentForge-Clinical-Copilot.mdc) — fork `master` / upstream policy.
+- [`.cursor/rules/PRD-2-AgentForge-Clinical-Copilot.mdc`](PRD-2-AgentForge-Clinical-Copilot.mdc) — git / module scope for this product line.

.cursor/rules/AgentForge-Railway-Docker.mdc

@@ -0,0 +1,23 @@
+---
+description: Preserve docker/agentforge-railway for Railway.com deployment of local dev branches
+alwaysApply: true
+---
+
+# Agentforge — Railway Docker layout
+
+The directory **`docker/agentforge-railway/`** (including its **`upstream/`** subtree and top-level files such as `Dockerfile`, `Dockerfile.flex`, `README.md`, and env examples) is **intentional fork infrastructure**: it enables deploying **this repository’s local development branches** to **[Railway](https://railway.com/)**.
+
+## Do
+
+- Treat edits under `docker/agentforge-railway/**` as **deployment-sensitive**: change only when you are **explicitly** improving or fixing the Railway build/deploy path.
+- After meaningful changes, verify the Railway-oriented flow still matches what `docker/agentforge-railway/README.md` describes (or update that README in the same change).
+
+## Do not
+
+- **Delete, rename, or “simplify away”** `docker/agentforge-railway/` during broad Docker refactors, upstream merges, or cleanup unless the user explicitly requests that and accepts losing Railway deploy from this tree.
+- **Replace** this tree wholesale with stock OpenEMR docker paths without reconciling Railway build context, entrypoints, and documented env vars.
+- Move Railway-specific assets out of `docker/agentforge-railway/` into random paths without updating deployment docs and Railway project settings.
+
+## Quick check
+
+- Unrelated task touching `docker/` → **leave `docker/agentforge-railway/` unchanged** unless the task is specifically about Railway or this image.

.cursor/rules/PRD-1-AgentForge-Clinical-Copilot.mdc

@@ -0,0 +1,43 @@
+---
+description: >-
+  Fork-wide git policy: master mirrors upstream OpenEMR; feature work stays on
+  integration/topic branches. Complements product-specific rules (PRD-2 module,
+  PRD2 Modernized frontend).
+alwaysApply: true
+---
+
+# Agentforge fork — Git and module scope
+
+Full teammate procedure: [docs/SYNC_DEV_WITH_UPSTREAM.md](docs/SYNC_DEV_WITH_UPSTREAM.md). Skill: `.cursor/skills/sync-dev-with-upstream/SKILL.md`.
+
+## Branches
+
+- Do **feature work** on your **designated integration branch** or **short topic branches** cut from it — **not** on `master` for ongoing WIP.
+- Known integration branches in this fork (use the one that matches the product you are changing):
+  - **PRD 1 / AgentForge baseline:** `prd_1_agentforge_monigarr` (and topics from it).
+  - **PRD 2 Clinical CoPilot (PHP module):** `prd2_agentforge` (and topics from it) — see `.cursor/rules/PRD-2-AgentForge-Clinical-Copilot.mdc`.
+  - **PRD2 Modernized (patient dashboard Next.js):** `prd2_af_modernized` (and topics from it) — see `.cursor/rules/PRD2-Modernized-Scope-and-Docs.mdc`.
+- Treat **`master` as a mirror of `upstream/master`** ([openemr/openemr](https://github.com/openemr/openemr)). Do not use `master` as your long-lived integration branch for fork-only experiments.
+- **Do not push** routine dev work to **`origin/master`** and **never push** to the canonical upstream repo except a deliberate, reviewed contribution workflow agreed with maintainers (default: **never** push to `https://github.com/openemr/openemr`).
+- **feature work** and creating new feature work docker images must be aligned with CONTRIBUTING.md and README files.
+- Do not change CONTRIBUTING.md and README files.
+- New documentation must be aligned with CONTRIBUTING.md, README files and documentation in the master branch.
+
+## Staying current with upstream
+
+- When you need upstream changes, **merge or rebase `master` into your feature branch** (or topic branch) after updating local `master` from `upstream/master`. See `docs/SYNC_DEV_WITH_UPSTREAM.md`.
+- **Never** merge or rebase your feature branch **into** `master` as a substitute for keeping `master` aligned with upstream. Flow is upstream → `master` → feature branch, not feature → `master` unless you are deliberately preparing a clean contribution to upstream.
+
+## What not to commit casually
+
+Avoid large or unrelated edits under paths such as:
+
+- `.phpstan/`
+- `.github/workflows/`
+- Broad or “random” sweeps under `src/` (or similar) unless you are **intentionally** contributing that work to upstream in a **focused, reviewable PR**.
+
+## Custom module (`oe-module-clinical-copilot`)
+
+- Prefer **all** custom module changes under:
+  - `interface/modules/custom_modules/oe-module-clinical-copilot/`
+- Add only the **minimal wiring** the upstream tree expects (for example, a **single** `composer.json` PSR-4 autoload entry for your namespace). That pattern is normal for in-tree modules; do not scatter module logic across the repo when it can live under the module directory.

.cursor/rules/PRD-2-AgentForge-Agent-Roster.mdc

@@ -0,0 +1,73 @@
+---
+description: PRD 2 Clinical CoPilot — default LLM roles and model picks for Lead, Supervisor, and SubAgents.
+globs:
+  - interface/modules/custom_modules/oe-module-clinical-copilot/**
+alwaysApply: false
+---
+
+# PRD 2 AgentForge — default agent roster (runtime LLMs)
+
+This rule complements `.cursor/rules/PRD-2-AgentForge-Clinical-Copilot.mdc` (git/module scope). It applies **only** to the Clinical CoPilot module under `interface/modules/custom_modules/oe-module-clinical-copilot/`. For **patient dashboard modernization** (Next.js under `frontend/`), use `.cursor/rules/PRD2-Modernized-Scope-and-Docs.mdc`, [`.cursor/rules/AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc), and the skill `prd2-patient-dashboard-modernization`.
+
+**Delegation roster (Clinical CoPilot):** [`.cursor/rules/AGENT-TEAM-PRD2-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-Subagents-Roster.mdc). **Modernized dashboard roster:** [`.cursor/rules/AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc`](AGENT-TEAM-PRD2-MODERNIZED-Subagents-Roster.mdc). Module context: `interface/modules/custom_modules/oe-module-clinical-copilot/README.md`.
+
+## Scope and doc alignment
+
+- PRD 2 AgentForge is implemented under `interface/modules/custom_modules/oe-module-clinical-copilot/`.
+- Do **not** change repo-root `CONTRIBUTING.md` or upstream **README** files. Operational detail for this module lives in `interface/modules/custom_modules/oe-module-clinical-copilot/README.md` and any module-local docs; do not maintain a second copy under `oe-module-clinical-copilot/docs/` unless the module README directs it.
+- Feature branch discipline for **this** product line: `prd2_agentforge` (see PRD-2-AgentForge-Clinical-Copilot rule).
+
+## Default model roster
+
+| Role | Responsibility (concise) | Default model |
+|------|---------------------------|---------------|
+| **Lead agent** | Final grounded answer; merges patient-record facts vs guideline evidence; citation contract at response boundary | **GPT-4o** *or* **Claude 3.5 Sonnet** (choose one per deployment; document in env/config) |
+| **Supervisor** | Routing only: when to run file processing, summarization/evidence path, EHR persistence step; **inspectable** handoffs | **GPT-4o-mini** |
+| **SubAgent 1 — File Processor** | Multimodal ingest: lab PDF + intake form; structured extraction with citations/bboxes; output is **untrusted** until validated | **Gemini 1.5 Flash** |
+| **SubAgent 2 — Summarizer** | Guideline-oriented synthesis over retrieved chunks (hybrid RAG + rerank); keeps evidence separate from patient facts | **Llama 3.1 70B** |
+| **SubAgent 3 — EHR Writer** | Proposes **structured** writes (FHIR/OpenEMR-shaped); **no direct DB access** — persistence only via server-controlled pipeline after validation | **GPT-4o-mini** |
+
+**Provider routing** (API keys, endpoints) is configuration-only; never commit secrets.
+
+## Map to PRD 2 “supervisor + two workers”
+
+- **intake-extractor (PRD)** → **SubAgent 1 (File Processor)** (Gemini 1.5 Flash).
+- **evidence-retriever (PRD)** → **SubAgent 2 (Summarizer)** over **retrieve_guidelines** / hybrid RAG output (Llama 3.1 70B). **Retrieval** (sparse + dense + rerank) stays **deterministic application code**, not an LLM.
+- **EHR Writer** is not a third PRD “worker” in the syllabus sense: it is the **persistence-facing subagent** that formats validated artifacts for the **server-side** `attach_and_extract` / write pipeline — consistent with ARCHITECTURE.md write boundary (model does not write the DB).
+
+**Lead agent** runs **after** supervisor-orchestrated steps and **verification**, producing the user-facing response (maps to the PRD “answer model” fed only top grounded evidence).
+
+## Non-negotiables
+
+- **Extraction is untrusted** until schema-valid, citation-linked, and passed through verification (module README / local architecture docs, audit trail).
+- **Citation contract**: `{source_type, source_id, page_or_section, field_or_chunk_id, quote_or_value}`; PDF bounding-box overlay in UI where applicable (PRD).
+- **Observability**: tool sequence, latency by step, tokens, cost estimate, retrieval hits, extraction confidence, eval outcome — **no raw PHI** in logs (USERS.md, PRD).
+- **Eval gate**: 50-case golden set, boolean rubrics, PR-blocking CI/hook; blocks meaningful regression (risk register / PRD).
+
+## Flow (reference)
+
+```mermaid
+flowchart TB
+  userNode[User]
+  supNode[Supervisor_GPT4o_mini]
+  fpNode[FileProcessor_Gemini15Flash]
+  sumNode[Summarizer_Llama31_70B]
+  ehrNode[EhrWriter_GPT4o_mini]
+  verifyNode[VerificationGate]
+  leadNode[Lead_GPT4o_or_Claude35]
+
+  userNode --> supNode
+  supNode --> fpNode
+  supNode --> sumNode
+  supNode --> ehrNode
+  fpNode --> verifyNode
+  sumNode --> verifyNode
+  ehrNode --> verifyNode
+  verifyNode --> leadNode
+  leadNode --> userNode
+```
+
+## What this rule does not do
+
+- It does **not** replace implementation: model IDs and routing belong in **env/config** inside the module.
+- It does **not** override PRD-2 git/module scope; it **complements** it.