Add AGENTS.md documenting the repo's conventions (#4256)

* Add AGENTS.md documenting the repo's conventions Codifies what is currently tribal knowledge or only discoverable by reading CI config: the view model / view contract, the rule that nothing reads the page, Clean Code ordering, the three test layers, and reuse-before-you-build. The root AGENTS.md is the always-loaded minimum and routes to docs/agents/, so an agent loads only the detail its task needs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Allow either hand at the commit, and measure continuous redraws Committing from the agent rules out running it where there is no git identity, a sandbox included. Either is now fine: commit on the user's word where the setup allows it, or write the message and hand it over. Redrawing continuously is the other addition. A level meter reported a fresh value every animation frame, so its whole menu reconciled sixty times a second, silence included, and nobody noticed until review. A PR that adds anything of the kind now says what it costs, or better, counts the redraws — commits rather than render calls, since React runs a component it then discards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-13 21:59:30 +00:00 · 2026-09-11 15:12:15 +02:00
parent 2cac2d7e8b
commit a58a5f615f
7 changed files with 322 additions and 0 deletions
@@ -0,0 +1,54 @@
+# AGENTS.md — Element Call
+
+MatrixRTC (MSC4143) + LiveKit video calling, shipped standalone, as a widget in
+Element Web and Element X, as embedded packages, and as a React component in a
+host's page. It is the MatrixRTC reference implementation.
+
+## Non-negotiables
+
+- Features and UI changes need a pre-approved issue. No issue, no review.
+- Exactly one `PR-*` label per PR. CI enforces it; it drives the changelog.
+- New behaviour ships with unit tests, a story if it renders, and an e2e spec if it
+  is user-facing. All three.
+- Reuse an existing component. If you genuinely cannot, say so in the PR body and
+  name what you rejected — never add a new one silently.
+- Nothing reads the page. No `window.location`, `document.body`, `window.inner*`,
+  `@media`, global `i18next` or the `widget` global — take it from a provider.
+- The change works standalone, as a widget and as a component. Say what you checked.
+- Every gate below is green before you push.
+- Hand off after the first implementation, before the quality pass. Then commit on
+  the user's word where the setup allows it, or hand them the message.
+
+## Read before you
+
+| …                                | …                                                          |
+| -------------------------------- | ---------------------------------------------------------- |
+| start a task of any size         | [docs/agents/workflow.md](docs/agents/workflow.md)         |
+| touch call logic or a view model | [docs/agents/architecture.md](docs/agents/architecture.md) |
+| write any code                   | [docs/agents/code-style.md](docs/agents/code-style.md)     |
+| write a test, story or e2e spec  | [docs/agents/testing.md](docs/agents/testing.md)           |
+| open a PR                        | [CONTRIBUTING.md](CONTRIBUTING.md)                         |
+| implement from a feature spec    | [FEATURES_SPEC/AGENTS.md](FEATURES_SPEC/AGENTS.md)         |
+
+## Gates
+
+```sh
+pnpm lint            # tsc, oxlint, knip, component externals
+pnpm format          # oxfmt
+pnpm test            # vitest: unit and storybook projects
+pnpm i18n:check
+```
+
+`knip` fails on dead code; a file deliberately inert ahead of its consumer goes in
+`knip.ts` `ignoreFiles` with a reason.
+
+## A good PR
+
+- One slice, under ~400 changed lines, green on its own, linked to its issue.
+- View model + marble tests, thin view, a story per state, an e2e spec.
+- Any new shared component called out explicitly, with why nothing existing fit.
+- Template filled for real: what, why, before/after screenshots, repro steps.
+- Anything that redraws continuously — an animation frame, a stream — says what it
+  costs, or better, counts the redraws in a test.
+- Branch `<handle>/<topic>`. Plain imperative commit subjects, no prefixes.
+- Once review starts, fix forward. Never force-push a regeneration over a review.