Imported from divyanshupatel17/TEMPLATE (AGENTS.md). Install upstream with npx skills add divyanshupatel17/TEMPLATE. Copyright stays with the author.

AGENTS.md

Instructions for AI coding assistants working in this repository. Single source of truth; CLAUDE.md only points here.

This project uses the template from github.com/divyanshupatel17/TEMPLATE — check there for the current version of universal rules and doc formats before assuming this repo has drifted from them.

What this is

2-4 lines — product, platform, package/domain name, one-line current status.

Repository layout

mobile/                          # e.g. Android app (Kotlin, Compose, Gradle)
website/                         # e.g. marketing site
admin/                           # e.g. operator console
backend/
  supabase/                      Migrations, edge functions, config
  workers/<name>/                Cloudflare Worker(s)
design/                          Source art, mockups — not consumed at build time
media/                           Video, audio, large binaries
docs/                            Permanent documentation, see index below
.local/                          Untracked, never committed

Delete rows this project doesn't have. This is a monorepo — state whether build systems cross project boundaries, e.g. "no build system crosses a project boundary."

Each of mobile/, website/, admin/ keeps its own README.md with a Structure section (feature-first vs. service/layer-first) — they're allowed to differ from each other. Read that file before assuming where a file lives, and update it in the same change whenever that app's folder structure changes.

Docs index

Add one row per docs/other/*.md file this project has, e.g.: | Widget catalog | docs/other/widget_catalog.md |

Docs upkeep — do this before finishing any task, not just when asked

• Stale docs: if a change invalidates what a doc says (architecture, a widget count, a category status), update that doc in the same change. A stale doc is worse than no doc.
• Reusable bug fix: append one row to docs/ISSUES_AND_LESSONS.md in the same change. Skip one-off typos; only patterns likely to recur.
• A significant issue you investigated or are still working through (a production bug with real phases, a blocked setup task, anything with a status that isn't just "done"): open or update a docs/audit/NNN_*.md file — don't leave the only record in chat history or .local/.
• End of session: before reporting a task complete, re-check whether anything above applies to what you just did. Don't wait to be asked.

Build and test commands

Dev servers: fill in ports. Full detail: docs/DEPLOYMENT.md.

Universal rules

• Understand existing code before changing it. Never guess when the answer is in the codebase.
• Smallest correct change. No unrelated refactors, cleanup, or features.
• Reuse existing architecture, naming, components, and tokens before creating new ones.
• Fix root causes, not symptoms.
• Ask only when ambiguity could materially change behavior, architecture, data, security, or UX.
• Comments: default to none. Add one only for a non-obvious WHY, 2-3 lines max, never restating what the code already says.
• No em/en dash or hyphen in user-facing UI text — reword instead. Code comments are exempt.
• Never commit, push, merge, reset, or delete a branch without asking first — every time, even mid-task, even if a prior commit this session was approved.
• git mv for moves, so history follows.
• Never discard uncommitted changes. Don't modify unrelated files.
• Secrets live outside the repo. Nothing real in .env.example or anywhere in .local/.
• D:\Secure (developer's machine only, specific to them — not portable, don't assume it exists on another machine or for another user): their personal cross-project secrets store — Android signing keystores (Keystores/), per-project credentials (projects/<name>/), and centralized Supabase account/token management (supabase/). Refer this folder for keystores, Firebase/ Supabase credentials, etc. if this project needs them — never copy its contents into the repo.
• Never mention Claude, Anthropic, or any AI tool in a commit, PR, or shipped UI string.
• Verification: review git diff, run the relevant linter/tests/build. Never claim something works without having actually run it.

Project-specific rules

This project's real constraints — data model, theming, platform quirks.

Naming conventions

• Directories: lowercase snake_case. Add language-specific casing, e.g. Kotlin PascalCase types/camelCase members; TS PascalCase components/camelCase utilities.
• Migrations: YYYYMMDDHHMM<SS>_snake_case_description.sql — the date/time prefix is when it was created, but the trailing 2 digits (<SS>) are a global serial number, not real seconds: list backend/supabase/migrations/, take the last file's trailing <SS>, use that + 1, every time, never reset per day and never reuse one. Real example (findr_app): 20260814180001_extensions.sql → ... → 20260814180013_...sql → next day 20260817180014_...sql (date changed, serial kept incrementing: 13 → 14).
• Design assets: descriptive, no size suffixes (icon.png, not icon-512.png).

Things you must never change automatically

Numbered list — what breaks production, what's coupled, what needs a human. Example shape:

1. Pushed database migrations. Files that have been applied are immutable — always add a new migration.
2. Release signing config. No debug-keystore fallback; a release must never ship debug-signed.

Repository workflow

See docs/GIT.md for the full commit/branch/PR/release spec. Summary: never commit without asking first; secrets are managed outside this repository.