# AGENTS.md > **Scope — read this first.** Despite the filename, this file is a **human > code-review guideline** (review principles + P0/P1/P2 severity framing). It is > **not** an AI-agent operating context. AI coding tools (Cursor, Copilot, > Windsurf, Claude Code) should load **[`CLAUDE.md`](CLAUDE.md)** for the > operational rules: tech stack, conventions, commands, safe-working rules, and > stop conditions. Use this file only when reviewing a pull request or diff. ## Repository expectations This repository is a production-focused supplier development platform. Core goal: Build the best application in the world for supplier development, with world-class business logic, UX, security, scalability, and enterprise readiness. ## Review guidelines - Review this codebase like a top-tier principal engineer, principal product designer, and principal security architect. - Prioritize logic correctness, security, reliability, performance, usability, scalability, maintainability, and enterprise readiness. - Be concrete. Name exact files, modules, components, queries, flows, and risks. - Flag hidden logic flaws, edge cases, missing validation, missing telemetry, and weak role or permission handling. - Focus strongly on Supabase auth, RLS, database access, API boundaries, client/server trust assumptions, and Vercel production readiness. - Evaluate mobile usability, desktop usability, navigation clarity, UI consistency, and admin ergonomics. - Treat poor UX in core workflows as a serious issue. - Treat weak production hardening and missing security protections as high severity. - Recommend the best implementation path, not just problem descriptions. - Prefer precise, high-signal findings over generic praise. - Include prioritized remediation steps. ## Done when A review is only complete if it: - identifies critical and high-severity issues - explains why they matter - proposes concrete implementation steps - prioritizes findings into P0, P1, and P2 - gives a final verdict on production readiness, enterprise readiness, and sales readiness ## Responsibility boundaries This file (`AGENTS.md`) holds the human-review guidelines and severity framing (P0 / P1 / P2). Use it when an engineer reviews a pull request or diff. It is distinct from the operational Claude Code configuration: - `CLAUDE.md`: repo-level Claude Code operating context for tech stack, repository conventions, the Claude Code Setup registry, and project-specific operating rules. - `.claude/agents/**`: concrete Claude Code subagent definitions (`architecture-reviewer`, `security-reviewer`, `code-quality-reviewer`). These are read-only review subagents invoked via `@` mention or via the `/review` orchestrator. Their internal checklists are the source of truth for what each subagent reviews; this file does not duplicate them. - `.claude/skills/**`: concrete Claude Code skill definitions (`/review`, `/check`, `/check-full`, `architecture-rails`, `supabase-migration-review`, `service-role-audit`). The slash skills are explicit user invocations; the auto-loaded skills inject reference content when working in matching path zones. Human reviewers use this file's principles. The Claude Code subagents and skills are tools that can assist a human review or pre-screen a diff, but they do not replace the human judgement called for in the Review guidelines and Done-when sections above. ## Diff-scoping guidance A review of a pull request is scoped to the diff under review. The reviewer's attention is on the changed lines, the changed behaviour, and the boundaries those changes touch. - Review the changed files first. Read the diff end-to-end before forming conclusions. - Use repository context only where it is needed to understand the risk of the change. Open neighbouring files when the diff cannot be evaluated in isolation; do not browse unrelated areas of the codebase. - Do not re-review existing app code that the diff does not touch or depend on. Pre-existing issues are out of scope unless the diff makes them materially worse or unblocks a required fix. - Keep findings tied to changed lines, changed behaviour, or directly affected boundaries (auth, RLS, API contract, customer adapter, public surface, error handling, telemetry). - Separate "must fix in this diff" findings (P0 / P1) from broader follow-up observations (P2 or out-of-scope notes). Use the existing P0 / P1 / P2 severity from the Done-when section to keep this split explicit. # SupplierPulse QAF V2 instructions for Codex and other coding agents These instructions apply to the entire repository unless a deeper `AGENTS.md` provides stricter rules. ## Source priority 1. Executable repository code 2. Tests, migrations, schemas and CI gates 3. Official QAF files, templates and User Guide 4. `docs/qaf-v2/` 5. Historical snapshots and HTML references ## Required behavior - Keep the comparison deterministic. - Never use an LLM to calculate QAF values or make binding mappings. - Never overwrite source QAF files. - Never silently discard cells, formulas, sheets, hidden structures or unknown data. - Keep verified-empty and not-computed states distinct. - Do not render a price bridge that does not reconcile. - Every quantitative output requires provenance. - Do not remove V1 functionality without parity evidence. - Do not create a second canonical field registry. - Do not calculate domain values in UI code. - Do not commit files under `.local/qaf-reference/`. - Do not weaken tests to make a change pass. - Run the repository gates specified by the active loop and leave a clean, committed worktree. - Work on one approved loop and one bounded ownership area at a time. ## Project playbooks Read and apply the Agent Skills playbooks stored under: - `.claude/skills/qaf-loop/SKILL.md` - `.claude/skills/qaf-determinism-gate/SKILL.md` - `.claude/skills/qaf-golden-corpus/SKILL.md` - `.claude/skills/qaf-review/SKILL.md` - `.claude/skills/qaf-loop-handover/SKILL.md` - `.claude/skills/qaf-confidentiality-guard/SKILL.md` - `.claude/skills/qaf-bmw-ui-review/SKILL.md` Codex should read the relevant `SKILL.md` directly when the task matches it. ## Required starting files - `docs/qaf-v2/00_START_HERE_AFTER_LOOP_1.md` - `docs/qaf-v2/baseline-inputs/06_Autonomous_Loop_Roadmap_v1.0.md` - `docs/qaf-v2/baseline-inputs/07_Requirements_Traceability_Matrix_v1.0.md` - `docs/qaf-v2/operating-model/AGENT_OPERATING_MODEL.md` - the latest loop report ## AUTONOMOUS MERGE AND DEPLOY POLICY > Dauerhafte Anweisung des Product Owners vom 2026-08-04 für dieses Repository. > Ergänzt die bestehenden Regeln, ersetzt keine davon. **Ein Pull Request allein gilt nicht als abgeschlossener Auftrag.** Verantwortet wird der vollständige Ablauf: analysieren, implementieren, testen, unabhängig reviewen, Fehler beheben, committen, pushen, PR erstellen und pflegen, CI überwachen, Review-Kommentare bearbeiten, nach bestandenen Gates mergen, den vorhandenen Deployment-Prozess ausführen oder überwachen, Smoke-Tests und Post-Deployment-Prüfungen durchführen, bei kritischen Fehlern sicher zurückrollen, Abschlussbericht erzeugen und anschließend mit dem nächsten freigegebenen Loop fortfahren. ### Merge ist erlaubt, wenn alles davon zutrifft - alle verbindlichen Tests grün - Typecheck, Lint und Build grün - Security- und Portability-Gates grün - Determinismusprüfungen bestanden - Reconciliation und Provenienz geprüft - keine offenen Review-Blocker - keine bekannte Regression - Migration und Rollback dokumentiert - keine unbeabsichtigten Dateien enthalten - keine Konflikte - alle vorgeschriebenen GitHub-Checks und Reviews erfüllt ### Unverhandelbar - Branch-Protection-, Compliance- oder Freigaberegeln werden weder umgangen noch abgeschwächt. - Kein Force-Push auf `main` oder `master`. - Kein Administrations-Override, um Pflichtprüfungen zu überspringen. - Keine Tests löschen, abschwächen oder durch stilles Catchen grün machen. ### Deployment Ausschließlich über die vorhandene Infrastruktur des Repositorys. Nach jedem erfolgreichen Merge: Deployment-Workflow vollständig beobachten, zuerst Preview oder Staging verwenden sofern vorhanden, Smoke- und E2E-Tests ausführen, danach Produktion sofern bestehende Regeln und Berechtigungen das erlauben, die konkret geänderte Funktion im Zielsystem prüfen, Logs, Healthchecks und Fehlerraten kontrollieren, sowie Deployment-ID, Commit, Umgebung und Prüfergebnisse dokumentieren. Bei kritischer Regression: Rollout stoppen, letzte stabile Version wiederherstellen, keine produktiven Daten löschen, Datenbank nur mit geprüfter Rückwärtsstrategie zurückrollen, Healthchecks danach erneut ausführen, Ursache dokumentieren und fachlich korrekt beheben. ### Keine Rückfrage mehr für Branch, Commit, Push, Pull Request, Review-Bearbeitung, Merge, Deployment, Smoke-Tests, sicheren Rollback, Start des nächsten Loops. ### Rückfrage weiterhin erforderlich bei - fehlender technischer Berechtigung - zwingender externer Freigabe - irreversibler Migration ohne sichere Rückwärtsstrategie - realem Risiko für produktive Daten - nicht auflösbarem fachlichem Konflikt - einer echten Produktentscheidung mit mehreren fachlich unterschiedlichen Ergebnissen