description: Authoritative guide for all software-writing agents in this repository alwaysApply: true

AGENTS.md

0 Philosophy

1 Repository Structure

Source files are organized under the app/ directory while context files for agents are organized under agent-context/ with the following layout:

.github/workflows/       # Mandatory - PR template + CI workflows for build, lint, supabase, secret scanning
agent-context/           # designs, logs and other context files for developers and agents
├─ session-log.md        # Mandatory – append-only per session, new entries at top of file, v ↑ per edit
├─ technical-spec.md     # Mandatory – latest technical spec
├─ functional-spec.md    # Mandatory – latest functional spec
├─ user-stories.md       # Optional – personas & acceptance criteria
├─ app-context.md        # Optional – problem, approach, value prop
├─ sql-diff-v{N}.sql     # Optional – Auto-generated incremental SQL patches - append-only per session (new entries at top of file)
└─ workflow.md           # Repetitive per-session checklist
app/                     # app router
components/              # shared components
hooks/                   # custom React hooks
lib/
public/                  # static assets to be served
scripts/                 # helper scripts for env:sync, lint, etc
styles/                  # global styles
supabase/                # latest sql schema (github action runs db pull on PR)
test/
README.md                # intro to the project and this repo
AGENTS.md                # this file
agent-setup.md           # One-time boot-strap guide for agents

Note: If expected files are missing from .github/workflows or from agent-context/ then follow these instructions to create them.

2 Coding Conventions

• Framework & Versions
  • Nextjs v15.3
  • Nodejs v24
  • Foundry (forge + cast) & Hardhat for coverage; Solidity ^0.8.30
• Structure
  • Add or modify files within the structure above if possible.
  • If you need to add folders then also update both AGENTS.md (this file) and README.md folder diagrams.
• Lint / Format
  • TypeScript → ESLint + Prettier
  • Solidity   → solhint (or solidity-lint) + Prettier plugin
  • pnpm lint runs both (pnpm lint:ts && pnpm lint:sol)
• Tabs / Indent
  • Four spaces in solidity, two spaces in typescript (no hard tabs)
• Env handling
  • Update .env.example with names of new vars (never values).
  • Boolean flags must be 'true'/'false' strings to avoid docker‑compose parsing quirks.
• Secrets scan
  • Detect hard-coded keys and secrets → Refactor to env vars + update .env.example + note in session log need for adding new env var
  • Add logs where needed, but ensure no sensitive values (tokens, IDs, secrets) are logged even in dev mode.
  • Run trufflehog on diff in CI workflow and full scan in nightly workflow
• Testing
  • If any new logic → Always add or modify unit tests accordingly.
  • Jest / Vitest for JavaScript units
  • Foundry for Solidity (if present)
  • Cypress for front-end e2e (if present).
• Pull Requests
  • Keep pull request descriptions short, following conventionalcommits
  • If any related issues are known, mention them in PR (e.g. "Isses: #10, #11")
• Session version tags
  • Follow SemVer (v2.0.0-alpha)
  • Major IDs ("v1.0", "v2.0") mirror new feature branches
  • Minor IDs ("v2.0", "v2.1") mirror different coding sesssions on the same feature branch

3 Process Overview

Agents must read agent-setup.md if artefacts are missing, otherwise follow workflow.md each time.

4 Guard-rails

• SQL migrations must be idempotent & reversible (include -- DOWN section which must revert exactly to previous schema; each DROP/ALTER should be preceded by IF EXISTS/IF NOT EXISTS..).
• Pre-commit hook warns (not blocks) if ESLint and similar (e.g. in Foundry) cannot start.
• Session log must bump version +1 for each session
• All new external calls must use SafeERC20 / Address.functionCall and be covered in tests.