The agent operating model

unswayed-backend is built by AI agents across many sessions, and possibly by several models at once. To keep that from descending into chaos — duplicated work, undocumented decisions, inconsistent quality — the repo carries an explicit operating model. This page explains what it is and why it's shaped this way. It is independent of the framework (it survived the move to NestJS unchanged).

The problem it solves

A language model has no memory of yesterday's session. Two agents working in parallel can't see each other's intentions. A human (or a different model) reviewing the work needs to understand it without a walkthrough. The operating model answers all three with one idea: persistent, shared, reviewable truth that lives in the repository.

The canonical manual: AGENTS.md

AGENTS.md is the one file every agent reads first. It's model-neutral, so it works for Claude Code, Cursor, Codex, Copilot, and others; CLAUDE.md and the README are thin pointers to it. It defines the reading order, the sources of truth, the testing bar, the documentation duty, the commit rules, and — most importantly — the Definition of Done.

The Definition of Done

A unit of work is "done" only when every one of these holds:

1. It was designed (and any hard-to-reverse choice recorded as an ADR).
2. It was tested first (TDD) — happy path, errors, and edges.
3. npm run verify is green (lint + typecheck + tests) and the 90% coverage gate holds on all four metrics.
4. The end-to-end flow passes against the real app (npm run test:e2e).
5. docs/ARCHITECTURE.md (structure), docs/FEATURES.md (registry), this wiki, and docs/ai/memory/ (memory) are all updated.
6. It's committed as the owner only — no co-author trailers.

The checklist is the point: it ties code, tests, docs, and memory into one inseparable bundle, so quality and documentation can't silently fall behind the code.

The four sources of truth

Concern	Lives in
Structure — how the system is laid out	docs/ARCHITECTURE.md
Why — the reasoning behind choices	docs/DECISIONS.md (ADRs)
What was done & how	docs/ai/memory/ (+ index)
What the product offers	docs/FEATURES.md

They're in the repo on purpose — so every agent, model, and pull-request reviewer sees the same truth. The companion subpages Memory & the single source of truth and Testing & coverage go deeper on two of them; The NestJS scaffold explains the application itself.

Why in the repo (not just in a tool's memory)?

Tool-local memory (for example Claude Code's ~/.claude) is invisible to other models and to PR review, and it doesn't travel with the code. So the canonical memory and docs live in the repo; Claude Code additionally mirrors a pointer into its local memory so it auto-recalls "go read the in-repo memory" — the best of both, without splitting the source of truth.