Docs: Add AGENTS.md files to guide AI coding assistants

[jimbojw]

Summary

We currently lack AGENTS.md files in the repository. AGENTS.md is an open, vendor-agnostic standard (now stewarded by the Agentic AI Foundation under the Linux Foundation) for providing context and conventions to AI coding assistants. It's supported by GitHub Copilot, Gemini, Codex, Cursor, and others. Given our monorepo structure with three distinct workspaces, adding targeted AGENTS.md files would significantly reduce the chance of AI-assisted changes introducing bugs or violating conventions.

Proposed files

We recommend adding 4 files — one at the root and one in each npm workspace package.

1. Root AGENTS.md — 🔴 High priority

Orients agents to the monorepo shape, build order, and cross-cutting conventions.

Suggested contents:

• Architecture overview — 3 workspace packages (frontend, functions, utils) + firestore/ rules + docs/ + scripts/
• Dependency graph — utils is a shared library consumed by both frontend and functions; always build utils first
• How to get running — npm ci at root, then run_locally.sh; Node ≥22 required
• Linting & formatting — Prettier + ESLint; lint-staged via Husky on pre-commit; @typescript-eslint/no-explicit-any is error
• CI — cloudbuild.yaml drives all builds; _DEPLOYMENT_TYPE controls what runs (test/functions/frontend/rules/indexes/all)
• Testing policy — each workspace has its own npm test; functions tests need Java 21 for the Firebase emulator
• Firebase config — firebase.json for local dev, firebase-test.json for emulator tests, .firebaserc.example for project aliases; firestore/ holds security rules, DB rules, indexes
• Stage system — experiments are composed of "stages" (chat, survey, chip negotiation, ranking, etc.); adding a new stage type touches all three workspaces (utils/src/stages/, functions/src/stages/, frontend/src/components/stages/)

2. utils/AGENTS.md — 🔴 High priority

Prevents cascading breakage by documenting the shared type/validation layer and stage patterns.

Suggested contents:

• Purpose — shared TypeScript types, validation functions, and utilities; published as a workspace package consumed by frontend and functions
• File naming conventions — <entity>.ts (types), <entity>.validation.ts (validation), <entity>.test.ts (tests); for stages: <stage_type>_stage.ts, <stage_type>_stage.validation.ts, <stage_type>_stage.manager.ts, <stage_type>_stage.prompts.ts, <stage_type>_stage.utils.ts
• How to add a new stage type — create files following the naming pattern in src/stages/, register in stage.ts and stage.handler.ts, add JSON schema export in export-schemas.ts
• Variables system — variables.ts / variables.utils.ts / variables.template.ts implement a template variable system for prompts
• Build — npm run build (uses tsup); must be rebuilt before frontend or functions pick up changes
• Testing — npm test; tests are colocated with source files

3. functions/AGENTS.md — 🔴 High priority

Documents backend endpoint/trigger patterns, emulator testing, and the LLM agent system.

Suggested contents:

• Purpose — Firebase Cloud Functions: HTTP callable endpoints + Firestore document triggers
• File naming — <entity>.endpoints.ts (callable functions), <entity>.utils.ts (business logic), <entity>.utils.test.ts (tests); stage-specific logic in src/stages/<stage_type>.*
• Trigger system — document triggers in src/triggers/; see the existing src/triggers/README.md for the full list and their Firestore paths
• Agent (LLM) participants — agent.utils.ts and agent_participant.utils.ts manage how LLM agents participate in experiments; prompt construction via structured_prompt.utils.ts
• Testing — npm test runs against Firebase emulator (requires Java 21); integration test in cohort_definitions.integration.test.ts is large and slow
• Endpoint conventions — endpoints are registered in src/index.ts; each returns structured responses
• Data access — uses src/data.ts as a Firestore data access layer; never write raw Firestore calls in endpoint files

4. frontend/AGENTS.md — 🟡 Moderate priority

Supplements the existing frontend/README.md with AI-agent-specific guidance on component and service patterns.

Suggested contents:

• Purpose — Lit Element + MobX single-page app; built with Webpack
• Component architecture — src/components/ organized by feature area (17 subdirectories); src/pair-components/ are reusable primitives (button, textarea, icon, tooltip, menu)
• Service layer — MobX-based services in src/services/; firebase.service.ts for DB access, auth.service.ts for login, experiment.manager.ts and experiment.editor.ts are the largest/most complex
• Stage components — src/components/stages/ has ~87 files; each stage type has config, preview, and answer components
• Styling — Material 3 Design via SASS variables in src/sass/; src/pair-components/shared.css for base styles; use SASS variables, not hardcoded values
• Local dev — copy firebase_config.example.ts → firebase_config.ts, then npm run start; dev server at localhost:4201

Where AGENTS.md files are not needed

Directory	Rationale
firestore/	Only 4 files; rules are self-documenting. Root AGENTS.md can cover the key points
scripts/	Small Python utility package (codegen + doctor script); too small to warrant its own file
docs/	Jekyll site for end-user docs; standard conventions, rarely a target for AI-assisted code changes
emulator_test_config/	Static config files; rarely changed
.github/	Standard GitHub config

Implementation notes

• The root file should be written first since the others can reference it.
• Contents should be kept concise and factual; AGENTS.md is not meant to duplicate the full docs site but to provide just enough context for effective AI assistance.