Imported from tusharsurani/Online-Verification-System-for-Weighing-Measuring-Instruments (AGENTS.md). Install upstream with npx skills add tusharsurani/Online-Verification-System-for-Weighing-Measuring-Instruments. Copyright stays with the author.

AGENTS.md

Instructions for AI Agents Working on This Repository

Auto-loaded by Antigravity (and other AGENTS.md-compatible tools) at the start of every session. Read this first, every time, before generating or editing any code.

This project's full specification lives in the files referenced below. Load and read all of them, in this order, before taking any action:

@PRD.md @Architecture.md @Rules.md @Design.md @Phases.md

1. Document Map — What to Consult, and When

If a request from the user conflicts with one of these files, flag the conflict explicitly rather than silently picking one side — these documents represent decisions already made for this project; don't quietly override them.

2. Order of Precedence

1. Security and data-integrity rules in Rules.md and Architecture.md — never compromised, even for "just for the demo" shortcuts. Propose a clearly-labeled temporary stub instead (e.g. a mock email sender that logs to console) rather than skipping validation, auth checks, or hashing logic.
2. Architecture.md's schema, API shape, and data-access approach — raw SQL via the pg pool, no ORM (§2). Do not introduce a new table, column, endpoint shape, or a different data-access pattern without updating this file in the same change.
3. Phases.md's ordering and autonomy levels — do not start a later phase's work before the current phase's exit criteria are met, and do not treat a review-driven phase as agent-driven just because it seems faster.
4. Design.md governs all visual output, including the deliberate exceptions it defines (the gold accent's restricted usage, the Certificate Card's no-hover static treatment). Do not introduce ad hoc colors, fonts, or component patterns not defined there — extend Design.md explicitly if a new pattern is genuinely needed.
5. Rules.md's conventions — naming, file placement, response envelope shape — apply to every file touched, not just new features.

3. Working Style Expectations

• Small, reviewable changes. Complete one endpoint or page fully — including loading/error/empty states per Rules.md §7 and Design.md §3's skeleton/empty-state spec — over half-implementing several at once.
• Never fabricate data model fields on the fly. If a page needs a field not in Architecture.md's schema, add it there first, with a migration, before using it anywhere else.
• Always wire the full path. A feature isn't done when the backend endpoint works in isolation — it's done when the frontend page calling it renders correctly with real seeded data, per the phase's exit criteria.
• Say when something is a stub. If a real integration isn't feasible now (e.g. real SMS sending), implement a clearly-labeled stub (// STUB: replace with real SMS gateway before production) rather than pretending it's complete.
• Verify visually, not just structurally, for anything UI-facing. Use the browser tool to actually render the page and compare it against Design.md's spec — confirming the right Tailwind classes exist in the code is not the same as confirming it looks right.
• If the browser/verification tool fails, say so immediately and explicitly — per Rules.md §11, state the fallback verification actually performed rather than silently presenting an unverified UI change as confirmed. Don't let a tool failure quietly become a skipped verification step.
• Re-read the relevant doc section before touching a file you haven't touched this session — these files exist precisely so context isn't lost between sessions or agents.

4. Autonomy Levels (see Phases.md for the authoritative per-phase list)

• Agent-driven phases (0, 2, 5, most of 6): proceed through the full checklist without pausing for approval at each file. Flag only genuine ambiguity.
• Review-driven phases (1, 3, parts of 4 and 7): propose the approach for each major step and wait for explicit confirmation before implementing. These are the phases touching auth, data integrity, certificate hashing, fraud thresholds, or anything expensive to unwind.
• When a phase mixes both (e.g. Phase 4's alert plumbing vs. its fraud thresholds), treat each sub-part according to its own designation, not the phase as a whole.

5. Common Requests and How to Handle Them

• "Add a quick field to the users table" → Update Architecture.md's schema table first, then write the migration, then the data-access function, then anywhere it's consumed.
• "Make this page look better" → Re-check Design.md first; the answer is almost always "apply the existing card / badge / button spec correctly," not "invent a new visual style."
• "Skip auth for now, I'll add it later" → Decline per Rules.md §5; offer instead to seed a test user and log in as them.
• "This is taking too long, just hardcode the dashboard numbers" → Decline per Rules.md §7; offer the minimal real aggregation query instead.
• "Use an ORM, raw SQL is annoying" → This is an Architecture.md §2 change, not a quick swap — flag it explicitly and confirm before switching, since it affects every controller already written.
• "Add a new role" / "change what GATC can do" → This is a PRD.md and Architecture.md change first (role definitions, requireRole allow-lists), not just a frontend tweak.

6. What Good Output Looks Like in This Repo

A completed unit of work always includes, together, not separately:

1. The migration/schema change (if any), reflected in Architecture.md.
2. The backend model/service/controller/route, following Rules.md and the raw-SQL approach in Architecture.md §2.
3. The frontend page/component consuming it, following Design.md, verified visually via the browser tool.
4. At least the lightweight tests described in Rules.md §10.
5. Confirmation that it matches its Phases.md phase's exit criteria before moving to the next phase.

If any of these five is missing, the work is not finished — say so rather than presenting it as complete.