AGENTS.md — Deliberate Lab (root)

Deliberate Lab is a platform for running online research experiments on human + LLM group dynamics. This file orients AI coding assistants to the monorepo structure, conventions, and workflows.

Keeping AGENTS.md in sync

These AGENTS.md files document conventions that should be followed by default. If a user request conflicts with the guidance here, raise the concern — ask which takes precedence (their idea or the documented convention) before proceeding. Do not modify AGENTS.md files unless the user explicitly asks you to.

Git safety & worktree workflow

This repository follows a bare Git repository + sibling worktrees layout with a triangle workflow (origin fork vs upstream canonical). Operations are governed by the worktree type:

Committing and pushing in feature worktrees (<id>-<slug>/)

• Staging and committing: Once an implementation plan is approved and changes are verified, the agent is encouraged to stage and create local commits following Conventional Commits (feat:, fix:, chore:, etc.). Align commit scopes and PR metadata with the 6 repository layers (see Decision 0004). Report the commit in the walkthrough.
• Pushing to origin: Pushing feature branches to your personal fork (origin) is safe and encouraged—GitHub preserves commit history even across rebase force-pushes (--force-with-lease).
• Pushing main: Pushing fast-forwarded main to origin/main to keep your fork in sync with upstream is safe and expected.
• Post-Action Reviews: Upon completing a PR, major feature milestone, or pairing session, consider running a retrospective using the retrospective skill to reflect on friction, capture overturned proposals, and anchor fast-follow items without in-flight scope creep.

[!CAUTION] Never run destructive or hard-to-reverse git commands without confirmation:

• git reset --hard (except when refreshing pr-<number> evaluation mirrors per the eval-pr skill)
• git clean -fd
• git branch -D (always use safe delete git branch -d)
• Overwriting or discarding uncommitted user changes

Architecture

This is an npm workspaces monorepo with three packages:

Other top-level directories:

• firestore/ — Firestore security rules, database rules, and indexes
• docs/ — Jekyll documentation site (GitHub Pages)
• scripts/ — pip-installable Python API client (deliberate_lab) with auto-generated Pydantic types + a Node.js doctor script (see scripts/AGENTS.md)
• emulator_test_config/ — Static config for Firebase emulator imports

The Firestore data model (document hierarchy, trigger paths) is documented in functions/AGENTS.md.

Dependency graph

utils ──► frontend
  │
  └────► functions
  ·
  ·····► scripts/types.py  (auto-generated via npm run update-schemas)

utils is a shared library consumed by both frontend and functions. Always build utils first — the other two workspaces depend on it.

Getting started

• Orient yourself first: Run the workspace overview diagnostic script upon entering the workspace to inspect the bare repo layout, active worktrees, remotes, and verify Node.js readiness: ./.agents/skills/workspace-overview/scripts/workspace-overview.sh
• Node 22 is strictly required (see .nvmrc and functions/package.json). Because non-interactive subshells often lack shell initialization (like NVM) or inherit a mismatched host Node version, prefer persistent terminal sessions if available in your agent harness so that an initialized Node 22 environment persists across command invocations throughout the session.
• Install all dependencies from the repo root: npm ci
• Run everything locally: ./run_locally.sh (in the repo root)
• Diagnose setup problems: npm run doctor

run_locally.sh copies required config files (.firebaserc, firebase_config.ts, index.html) if they are missing, builds utils and functions, starts file watchers for both, launches the Firebase emulators (with seed data from emulator_test_config/), and serves the frontend at http://localhost:4201.

Run npm commands from the repo root using --workspace (or -w):

npm run build -w utils
npm test -w functions
npm run start -w frontend

Python tooling (uv, pyright) in scripts/ is the exception — run those from the scripts/ directory where pyproject.toml lives.

Linting & formatting

• Prettier formats .json, .ts, .html, .scss, and .css files
• ESLint uses the flat config format (eslint.config.mjs); the project does not have a .eslintrc.* file
• @typescript-eslint/no-explicit-any is set to error — do not use any
• Husky + lint-staged runs both Prettier and ESLint on pre-commit for the same file set (*.{json,ts,html,scss,css})
• Frontend files get browser globals; everything else gets Node globals

CI

cloudbuild.yaml drives all builds. The _DEPLOYMENT_TYPE substitution variable controls which steps run:

GitHub Actions (.github/workflows/ci.yaml) also runs a schema sync check: if types in utils change, docs/assets/api/schemas.json and scripts/deliberate_lab/types.py must be regenerated or CI will fail. Run npm run update-schemas from the repo root to fix this (requires Python 3.12+ and uv — see scripts/AGENTS.md for setup).

Testing

Each workspace has its own npm test:

npm test -w utils       # Jest; unit tests colocated with source
npm test -w functions   # Jest; requires Java 21 for Firebase emulator
npm test -w frontend    # Jest

Functions tests run against the Firebase emulator using firebase-test.json. The integration test in cohort_definitions.integration.test.ts is large and slow.

Firebase config

Import convention

Both frontend and functions import from utils using the npm workspace package name:

import {StageKind, ExperimentConfig} from '@deliberation-lab/utils';

Do not use relative paths to reach into utils/src/ — always import from @deliberation-lab/utils.

Stage system

Experiments are composed of ordered stages (chat, survey, chip negotiation, ranking, etc.). The StageKind enum in utils/src/stages/stage.ts lists all stage types.

Adding a new stage type touches all three workspaces:

1. utils/src/stages/ — types, validation, manager, prompts
2. functions/src/stages/ — backend endpoint + trigger logic
3. frontend/src/components/stages/ — config, preview, and answer UI components

See each workspace's AGENTS.md for detailed guidance.

Skills

Reusable AI agent skills are defined in .agents/skills/. Each skill is a directory containing a SKILL.md instruction file (with YAML frontmatter) and optional helper scripts, examples, and resources.

To inspect GitHub issues and pull requests, use the gh skill scripts (./.agents/skills/gh/scripts/gh-issue-view.sh <number> for issues or ./.agents/skills/gh/scripts/gh-pr-view.sh <number> for PRs with CI checks and inline reviews) to stream complete context without terminal truncation.

Decisions

Architectural, toolchain, and governance precedents are recorded in .agents/decisions/ as lightweight Decision Records with YAML frontmatter (see 0001-record-agent-decisions.md). Consult these records just-in-time when resolving architectural or policy ambiguity:

Common pitfalls

1. Forgetting to rebuild utils — frontend and functions consume the compiled output in utils/dist/. After changing utils source, rebuild it (npm run build -w utils) before testing downstream workspaces, or changes won't be picked up.
2. Running npm from a subdirectory — always run from the repo root with -w <workspace> (see above).
3. Editing scripts/deliberate_lab/types.py by hand — this file is auto-generated and will be overwritten by npm run update-schemas.
4. Missing Java 21 for functions tests — the Firebase emulator requires Java 21. Unit-only tests can be run without it via npm run test:unit -w functions.
5. Forgetting to run npm run update-schemas — if you change types in utils, CI will fail the schema sync check until schemas are regenerated.