← Back to agents

AGENTS.md from dbartley18/Riva

Repository
⭐ 0 starsLast commit Aug 28, 2025

Riva — Codex Agent Rules

> Note: This document is a companion to the Engineering Handbook. For non‑negotiables, performance budgets, and precedence, see `Documentation/engineering_handbook.md`. If anything here conflicts with the Handbook, the Handbook wins.

**Version:** v0.1 **Date:** Aug 13, 2025 **Owner:** Devin **Applies to:** Any usage of **Codex/AI coding assistants** (e.g., CLI/chat/models in your IDE) in the Riva monorepo.

> Purpose: Make Codex generate code changes that respect our contracts, privacy, and performance budgets. These rules complement the **Coding Standards** and **Cursor Agent Rules**.

______________________________________________________________________

1) Mission & Non‑Negotiables

Refer to `Documentation/engineering_handbook.md` §1 for the authoritative mission and non‑negotiables. This Codex doc inherits those constraints.

______________________________________________________________________

2) Working Context (read‑in before coding)

  • **Repo layout (authoritative):** `apps/{api,worker,web}`, `packages/{core,graphs,connectors,tools,llm,storage,analytics}`, `infra/{db,deploy}`, `tests/{unit,e2e,graphs}`.
  • **Contracts:** `packages/core/schemas.py`, `packages/graphs/state/*`, `apps/api/routers/*`.
  • **Perf budgets:** See `Documentation/engineering_handbook.md` §3.

______________________________________________________________________

3) Codex Change Protocol (R‑P‑C‑E‑V)

1. **Read** the ask; open relevant files & standards. 1. **Plan** the diff: files to touch, DTOs, tests, migration if any. 1. **Change** code in small commits; keep functions pure where possible. 1. **Evaluate**: run `ruff`, `mypy --strict`, `pytest -q`, and all checks noted in '.github/workflows/ci.yml' before creating pull request and accepting code. Playwright where relevant. 1. **Validate** against AC & budgets; write PR body using template (below).

Always output a short **plan**, **files touched**, **commands run**, **test results**, and **follow‑ups** in chat.

______________________________________________________________________

4) File‑Type Rules

  • **API (FastAPI)**
  • DTOs in `packages/core/schemas.py`; routers under `apps/api/routers/*.py`.
  • Require `Idempotency-Key` on POST writes.
  • Map errors to **Problem+JSON**.
  • Inject `app.user_id` for RLS.
  • **LangGraph**
  • Node I/O = Pydantic models.
  • No network calls in `features/*` or `explain/*` nodes; fetch upstream in `sources/*`.
  • Emit domain events at flow boundaries; add OTel spans per node.
  • **Storage/Repos**
  • All DB access via repositories; migrations in `infra/db/alembic`.
  • Use parameterized SQL or SQLAlchemy Core; never string‑concat queries.
  • **Connectors**
  • Respect robots/TOS; throttle & cache; behind feature flags.
  • Identify user‑agent; structured error taxonomy.
  • **Frontend**
  • TS strict; React Query; shadcn/ui; Problem+JSON handling; a11y keyboard shortcuts.

______________________________________________________________________

5) Coding conventions — key reminders

  • See `Documentation/coding_standards.md` for authoritative coding rules; defer to it when in doubt.
  • Keep I/O typed (Pydantic DTOs); map API errors to Problem+JSON; run ruff, mypy --strict, and pytest before proposing completion.

______________________________________________________________________

6) Tests & Quality Gates

  • Unit tests for new code; graphs **golden tests** for outputs; contract tests for routers.
  • Coverage ≥ 70% on core libs and graph nodes.
  • Playwright flow: rec list → detail modal → variant → case.
  • Add performance micro‑benchmarks if touching hot paths.

______________________________________________________________________

7) Security & Privacy

  • Enforce RLS; every tenant table query must run with `SET LOCAL app.user_id`.
  • Redact PII on ingest; anonymize consulting client names.
  • Do not commit `.env` or secrets; use KMS/param store.
  • Gmail integration is **read‑only** in MVP.

______________________________________________________________________

8) Performance Budgets (must verify)

Authoritative budgets live in `Documentation/engineering_handbook.md` §3. Codex should enforce them during planning and validation and avoid introducing regressions.

______________________________________________________________________

9) Prohibited / Handle‑With‑Care

  • ❌ Network I/O in scoring/explain nodes.
  • ❌ Storing/logging secrets/PII.
  • ❌ Bypassing RLS or `app.user_id`.
  • ❌ Large PRs (>400 LOC) without decomposition.
  • ⚠️ Scrapers only behind flags & robots compliance.
  • ⚠️ LLM prompts must be schema‑validated; temp ≤ 0.2 in prod.

______________________________________________________________________

10) Prompt Patterns (ready to paste to Codex)

*“Implement `/api/v1/recommendations` (POST). Define `RecInput/RecOutput` in `packages/core/schemas.py`. Enforce `Idempotency-Key`, set `app.user_id` for RLS, return Problem+JSON on errors. Add contract tests in `tests/unit/api/test_recommendations.py`.”*

  • **Add recommendations endpoint**

*“Create `packages/graphs/nodes/features/extract.py` that computes similarity features between resume section embeddings and job chunk embeddings (pgvector). Define typed input/output, add retries & OTel spans, and write `tests/graphs/test_features_extract.py` with fixtures.”*

  • **Create features node**

*“Write an Alembic migration adding partial unique index on jobs `(company_norm,title_norm,(locations->>0)) WHERE is_active`. Update repo/DDL and unit tests.”*

  • **Write migration for dedupe**

*“Given JD and resume texts, produce 3–6 evidence pairs (resume span, JD line, capability label, confidence). Enforce JSON schema; add golden test.”*

  • **Evidence mapping**

*“Implement `ats/variant.py` node to generate ATS‑safe resume variant and a structured diff. Add unit tests; update export tool.”*

  • **ATS variant + diff**

______________________________________________________________________

11) PR Template (Codex must populate)

```

Summary

Problem → Approach → Result

Changes

  • Files touched
  • DTOs/migrations
  • Flags/configs

Tests

  • Unit / Graphs / E2E results

Observability

  • Tracing/metrics

Security & Privacy

  • RLS verified; no PII in logs; secrets safe

Performance

  • Budgets checked (numbers here)

Risks & Rollback

```

  • Known risks; rollback plan

______________________________________________________________________

12) Ready‑To‑Run Commands (Codex should suggest)

  • **Backend checks:** `ruff . && mypy --strict . && pytest -q`
  • **DB:** `alembic upgrade head` (then run seed/fixtures)
  • **Web:** `pnpm i && pnpm build && pnpm test`
  • **E2E:** `pnpm exec playwright test`
  • **Perf check:** `pytest -q tests/perf/test_hotpaths.py -k recommendations`

______________________________________________________________________

13) Acceptance (this doc)

  • These rules apply to all Codex‑assisted changes.
  • Deviations require explicit justification in the PR **Risks & Rollback** section.