Imported from nvmaditya/easy-pass (.agents/AGENTS.md). Install upstream with npx skills add nvmaditya/easy-pass --skill .agents. Copyright stays with the author.

AGENTS.md — EasyPass Mini Service Request Tracker

This file is always-on context for Antigravity CLI (via AGENTS.md — see SETUP-NOTES.md). It is read at the start of every session. Keep it short, current, and free of contradictions. Detailed requirements live in PRD.md; this file is operating instructions, not the spec itself.

0. Maintenance Protocol — this file is LIVING, not fixed

This is the most important section. Follow it before anything else in here.

1. If the user says something in conversation that contradicts, supersedes, or refines anything written below — a changed stack choice, a different access rule, a different time budget, a different priority order — stop and update this file first, before continuing with the unrelated task they asked for. Do not silently comply with the new instruction while leaving the old, now-wrong text in place.
2. The user's most recent statement wins. Treat this file as a cache of past decisions, not a source of truth that overrides what the user just told you.
3. Edit in place, don't just append. Find the specific section that's now wrong and rewrite it. An AGENTS.md with two contradictory bullet points about, say, whether viewers can create requests, is worse than useless — it's actively misleading on the next session.
4. Ask before overwriting anything security- or data-isolation-related. If the clash touches RLS rules, auth, or who-can-see-what, confirm you've understood the new rule correctly before editing — these are the parts of this project that are actually being graded. For everything else (naming, folder layout, minor tooling preferences), just update it and mention that you did.
5. Log it. Add a one-line, dated entry to the Changelog at the bottom of this file every time you edit it: what changed and why. Don't log routine reads, only edits.
6. Keep it lean. If an edit would push this file past ~200 lines, move the detail into PRD.md or a skill file and leave a pointer here instead. This file should stay skimmable.

1. What this project is

A miniature version of EasyPass's real product: a service request tracker where companies submit PRO/government service requests, and access is strictly scoped to the companies a user belongs to. See PRD.md for full requirements. Two things are non-negotiable and are what this whole exercise is testing:

• Data isolation must be enforced at the database layer (Postgres RLS), not just in application code.
• The ERP invoice sync must be idempotent — safe to re-run, no duplicates, correctly applies newer data over older data.

2. Stack

• Next.js (App Router) + TypeScript
• Supabase (Postgres + Auth), free tier
• No other backend framework, no ORM unless the user explicitly asks for one — use the Supabase JS client and raw SQL migrations.

3. Repo layout

/app                    Next.js App Router pages and routes
/app/api/mock-erp        Mock ERP payload route
/lib/supabase            Supabase client setup (server + browser variants)
/supabase/migrations      SQL migration files, including RLS policies
/supabase/seed.sql        Seed script (two users, two companies, sample requests)
/scripts/sync-invoices    Idempotent ERP sync script
/PRD.md                  Full requirements (source of truth for scope)
/NOTES.md                 AI usage log, RLS proof, sync proof, escalation question
/README.md                 Setup instructions from a clean clone
/.env.example              All required env vars, no real values

4. Data model (see PRD.md §4 for full DDL)

• companies(id, name)
• company_members(user_id, company_id, role) — role is admin or viewer
• service_requests(id, company_id, title, status, created_at) — status is submitted / in_progress / completed
• invoices(...) — columns designed against the mock ERP payload, with a unique constraint on external_id to make upserts possible

5. Access rules (non-negotiable, enforce via RLS)

• A user sees only companies they're a member of (via company_members), and only service_requests rows whose company_id is one of those companies.
• Only admin members can INSERT requests or UPDATE a request's status.
• viewer members can SELECT only.
• Do not rely on WHERE user_id = ... filters in application code as the only protection. RLS policies must hold even if queried directly against the database with a different client. App-level checks are allowed as a UX nicety (hide the "create" button from viewers) but never as the actual security boundary.

6. Available subagents (ported to .agents/skills/)

Subagents have been ported to Antigravity CLI skills (flat markdown files directly under .agents/skills/).

7. Active hooks (.agents/hooks.json / .agents/hooks/)

• PreToolUse blocks destructive bash (rm -rf, DROP TABLE, DROP POLICY without a matching CREATE POLICY in the same diff) and blocks any git commit/git push that would include a file matching .env (not .env.example).
• PostToolUse on SQL migration edits: runs supabase db lint (or psql --dry-run equivalent) so broken SQL is caught immediately, not at deploy time.
• PostToolUse on .ts/.tsx edits: runs tsc --noEmit and eslint on the changed file.
• SessionStart: prints a reminder of the ~6 hour time-box and today's elapsed time if tracked.

Hooks are deterministic — they fire every time regardless of what the model decides. Use them (not an AGENTS.md instruction) for anything that must never be skipped, like the secrets check.

8. Available skills (flat markdown files directly under .agents/skills/)

• rls-policy-patterns.md — canonical Supabase RLS patterns for membership-scoped multi-tenant data, including the recursive-policy trap and how to avoid it.
• idempotent-upsert-sync.md — the ON CONFLICT ... DO UPDATE pattern for safely re-running an import against a flaky upstream source with an updated_at tiebreaker.
• supabase-nextjs-scaffold.md — conventions for server vs. client Supabase clients in the App Router, env var naming, auth helper setup.
• notes-md-writer.md — evidentiary bar for NOTES.md: what counts as proof vs. what counts as an unverified claim.

9. Commands

npm run dev              # local dev server
npm run seed              # run supabase/seed.sql against local/dev DB
npm run sync:invoices      # run the idempotent ERP sync
npm run test               # any automated tests (bonus, optional)

(If actual script names differ once the app exists, update this section — don't leave placeholder commands that don't work.)

10. Time-boxing

Total budget is ~6 hours honestly tracked: Part A ~3h, Part B ~1–1.5h, Part C (NOTES.md) ~30–45min. If time runs out, stop and write the "what I'd do with more time" section in NOTES.md rather than pushing further into an unverified feature. Working + explained beats complete + unexplained — this is stated explicitly in the brief and is a grading criterion, not a suggestion.

11. Things Antigravity should never do on this project

• Never mark RLS as "done" without having actually run the cross-user test described in PRD.md §7 — don't just assert the policy "should" work.
• Never fabricate NOTES.md content (test results, AI prompts used, row counts) — if something wasn't actually run this session, say so and flag it as a gap.
• Never commit real Supabase keys, service role keys, or .env — only .env.example.
• Never silently drop the "AI got something wrong" requirement in NOTES.md — this is explicitly graded, don't write a NOTES.md implying flawless AI output.

12. Git workflow

• Remote: https://github.com/nvmaditya/easy-pass.git (public repo, origin).
• Push after each phase: After each implementation phase is successfully built and tested, commit all changes with a descriptive message and push to origin/main. Don't batch everything into one final commit — incremental, phase-by-phase pushes so the commit history reflects the build progression.
• Commit message format: phase N: <short description> (e.g. phase 1: scaffold Next.js + Supabase clients).
• Never commit .env, .env.local, or any file containing real keys — only .env.example. The existing PreToolUse hook enforces this.

Changelog

• 2026-07-14 — Initial version created from the EasyPass take-home brief.
• 2026-07-14 — Migrated to AGENTS.md for Antigravity CLI structure.
• 2026-07-14 — Updated AGENTS.md with flat skills layout and hooks.json paths.
• 2026-07-14 — Added §12 Git workflow: push to nvmaditya/easy-pass after each phase.