# AGENTS.md Read these files at the start of every session before doing any work: 1. `agents-docs/AGENT_WORKFLOW.md` — workflow and operating rules 2. `agents-docs/LESSONS.md` — durable rules learned from past corrections; apply any that match this session's work 3. `agents-docs/AGENTS_FEATURES.md` — when and how to update feature docs 4. `agents-docs/FEATURES.md` — feature index 5. `agents-docs/ENGINEERING.md` — engineering standards 6. `agents-docs/CONTEXT-MAP.md` — index of bounded contexts in this repo Reference on-demand (when the workflow triggers them — see `agents-docs/AGENT_WORKFLOW.md` §§ 4–5): - `agents-docs/AGENTS_CONTEXT.md` — contract for updating `CONTEXT.md` / `CONTEXT-MAP.md` - `agents-docs/AGENTS_ADRS.md` — contract for writing architecture decision records When working in a subdomain, also read its `CONTEXT.md` first: - Product client (Angular 21): `toju-app/CONTEXT.md` - Desktop shell (Electron main + preload): `electron/CONTEXT.md` - Signaling server (Express + WebSocket): `server/CONTEXT.md` - End-to-end tests (Playwright): `e2e/CONTEXT.md` - Marketing site (Angular 19): `website/CONTEXT.md` - Application documentation (Docusaurus): `docs-site/CONTEXT.md` --- MetoYou (also called Toju) is a desktop-first, P2P Discord-style chat application managed as an npm-workspaces monorepo. It bundles an Angular 21 product client, an Electron 39 desktop shell with TypeORM + sql.js for local persistence, a small Node/TypeScript Express signaling server with WebSocket-based realtime, a Playwright end-to-end suite, an Angular 19 marketing site, and a Docusaurus app/plugin documentation site that ships inside the Electron build. Voice and screen-share are WebRTC, with RNNoise denoising via a WASM audio worklet. ## CRITICAL — Non-negotiable rules for all agents ### Test-Driven Development (MANDATORY) **Write tests before implementation code.** When creating or changing anything: 1. STOP — do not write implementation first 2. Write failing tests (RED) 3. Run tests and confirm failure (`npm run test` for the product client; `npm run test:e2e` for end-to-end; place spec files colocated with source, suffix `.spec.ts`) 4. Write minimal code to pass tests (GREEN) 5. Refactor while keeping tests green This applies to all code — Angular components and services, NgRx effects/reducers, Electron IPC handlers, server CQRS handlers, websocket message handlers, plugin runtime, and domain logic. If the code lives in a package without a configured test runner (server, website, docs-site), surface that gap before adding logic there. ### Lint correctness (MANDATORY) Before completing any task: 1. Run `npm run lint` from the repo root (ESLint 9 flat config in `eslint.config.js` covers every package) 2. Fix all errors 3. Do not consider work complete until it exits with code 0 ### Type / build correctness (MANDATORY) Type checks live in build scripts: - Product client (`toju-app/`): `npm run build` (Angular CLI runs `tsc` with strict settings) - Electron (`electron/`): `npm run build:electron` (invokes `tsc -p tsconfig.electron.json`) - Server (`server/`): `cd server && npm run build` (invokes `tsc`) If your change touches one of these packages, run the corresponding build and ensure it exits 0 before marking work complete. ## Most important rule After any change that affects API contracts, schemas, invariants, workflows, or major behavior: update the relevant `agents-docs/features/.md` as part of the same task — not as a follow-up. New feature area → create `agents-docs/features/.md` and add an entry to `agents-docs/FEATURES.md` (alphabetical). The product client already maintains per-domain READMEs under `toju-app/src/app/domains//README.md`. When the change is fully internal to one of those bounded contexts and its surface stays the same, the domain README is the right place to update; cross-context contracts (websocket envelopes, IPC channels, server routes, plugin manifests) belong in `agents-docs/features/`. ## Structure of further instructions - **Agent workflow & operating rules:** `agents-docs/AGENT_WORKFLOW.md` - **Agent lessons (durable cross-session rules):** `agents-docs/LESSONS.md` - **Engineering standards:** `agents-docs/ENGINEERING.md` - **Feature documentation contract:** `agents-docs/AGENTS_FEATURES.md` - **CONTEXT documentation contract:** `agents-docs/AGENTS_CONTEXT.md` - **ADR contract:** `agents-docs/AGENTS_ADRS.md` - **Feature index:** `agents-docs/FEATURES.md` - **Feature docs:** `agents-docs/features/` - **Architecture decisions:** `agents-docs/adr/` - **Context map:** `agents-docs/CONTEXT-MAP.md` - **Product-client domain:** `toju-app/CONTEXT.md` - **Desktop-shell domain:** `electron/CONTEXT.md` - **Server domain:** `server/CONTEXT.md` - **E2E suite domain:** `e2e/CONTEXT.md` - **Marketing-site domain:** `website/CONTEXT.md` - **App-docs domain:** `docs-site/CONTEXT.md` Keep this file minimal. Do not duplicate detailed rules here. ## Completion checklist Before marking work complete: - [ ] Tests written before implementation - [ ] All tests passing (`npm run test`, plus `npm run test:e2e` if behavior is user-visible) - [ ] `npm run lint` passes - [ ] Affected package builds: `npm run build` / `npm run build:electron` / `cd server && npm run build` - [ ] Naming conventions followed (kebab-case files; domain `*.rules.ts` / `*.model.ts` / `*.component.ts` suffixes) - [ ] Errors handled - [ ] Feature docs updated if contract/schema/invariant changed (see `agents-docs/AGENTS_FEATURES.md`) - [ ] `CONTEXT.md` updated if a domain term was resolved or introduced (see `agents-docs/AGENTS_CONTEXT.md`) - [ ] ADR written if a hard-to-reverse decision was made (see `agents-docs/AGENTS_ADRS.md`) - [ ] Lesson recorded in `agents-docs/LESSONS.md` if this session produced a correction, revert, or hidden constraint (see triggers in `agents-docs/AGENT_WORKFLOW.md`) - [ ] PR opened with summary and linked issues (`Fixes #` / `Relates to #`) - [ ] Gitea Workflows checks passing