Skip to content

Conventions

What a tool enforces, and the habits the code shows. Where a convention is stated but not enforced, this says so.

1. The gate

mix check runs, in the test environment: compile --force --warnings-as-errors, format --check-formatted, credo --strict, troupe.boundaries, test. CI's lint and test <app> jobs run the same steps plus the generated-file checks (build.md §3); scripts/ci is the CI job on a machine. The clients have their own gates: mix check in clients/tui (with troupe.xref), and pnpm typecheck, test, tokens:check, icons:check in clients/gui. A package both the TUI and the umbrella lock must be the same version in both lock files; elixir scripts/locks-agree.exs checks it. Neither lock may hold a package with a security advisory: mix hex.audit, at the root and in clients/tui, fails the pull request in licences.yml and in scripts/ci, since Dependabot does not read Hex.

The formatter's blind spot. The root .formatter.exs lists {config,lib,test}/**/*.{ex,exs} relative to the root, and no app has its own, so mix format --check-formatted never opens a file under apps/. Credo covers part of it (spacing, trailing whitespace, line length 120). Run mix format in the app directory by hand.

Credo runs with --strict, so low-priority checks fail too: a TODO or FIXME comment fails the gate; every module needs a @moduledoc; no IO.inspect, dbg or IEx.pry; test files end in _test.exs; apply/3 with a literal module and function is flagged (the three calls the code has name theirs by a variable). One check is the repository's own: Troupe.Credo.PathOnlyLookup (apps/troupe_protocol/credo/) refuses System.find_executable/1 and :os.find_executable in lib/, which on Windows look in the current directory first; a program is found through Troupe.Executable, on PATH alone.

Line endings are LF everywhere, whatever core.autocrlf says (.gitattributes): Credo's line-ending check and dash both break on CRLF.

2. Boundaries

The rules are in ARCHITECTURE.md §3. When a client needs a server module, the protocol is missing a method: add it to PROTOCOL.md and the apps in the same pull request as the client change that needs it.

3. Rules the code states and tests check

Rule Checked by
Session.Log is the only publisher of durable events; agents publish ephemerals structure: Troupe.Events is internal to core
Ephemerals are never persisted and may be dropped backpressure_test.exs
A response is an acknowledgement, never the effect; replaying a command_id returns the first acknowledgement commands_test.exs; the Python conformance client
Schema changes are add-only within version 1 mix troupe.schema.diff
An upcaster adds and renames, never drops; one version at a time fold_test.exs against recorded fixtures
A recorded fixture hash is evidence, not a test to update troupe.fixtures.record refuses to overwrite
Every admin method is an API method and an MCP tool, with a summary and described arguments; destructive ones name confirm; none returns session content admin_parity_test.exs
The chart makes no Kubernetes Secret, and the operator only copies, by name, those a worker namespace mounts; one a profile names only when it is labelled for workers no kind: Secret in the chart; Troupe.Operator.WorkerSecretsTest
A UI can never apply backpressure to an agent a test stalls a socket and requires a turn within twice its idle time, or a quarter second more, whichever is larger

4. Comments, decisions and messages

  • Comments say why. Every module opens with a @moduledoc that argues for the design rather than restating the code. When behaviour changes, the moduledoc moves with it.
  • docs/decisions/ records the judgment calls that still hold and that a reader could have made differently, one file per decision (0790-one-file-per-decision.md): front matter with number, title (the one-sentence decision), date, status, paths and gist (what someone changing those paths must not undo), then a body of at most 40 lines that are not blank: the decision, what was not chosen, what breaks if it is undone. No list of tests, no history of the issue, no restatement of the code. paths are where it would be undone: at most eight globs of code, never a test. One that is superseded, or whose reasoning the code's comments now carry, is deleted or marked superseded, and its number is never reused: each log's README says <!-- next: N -->, the first number not yet reserved, which the coordinator moves past a chunk's block on the chunk's branch and a fixer never edits. docs/decisions/tui/ and docs/decisions/daemon/ hold those two projects' own, numbered on their own. mix troupe.decisions --for <path> lists the decisions that govern a path; --check, which CI runs, fails on a duplicate number, a number at or above its log's next, a missing field or a paths glob that matches nothing, and on a decision dated 2026-11-18 or later over 40 lines, over eight paths or naming a test.
  • Code cites no decision by number (Decision 882). A document may name code; code names no document. Where a comment would have said "Decision 800", it states the invariant where it applies, what holds and what breaks if the line changes: "the write names its epoch, and the plane refuses a stale one, so a sealer that lost the session stops before it writes". The decision names the code in its paths (and symbols), which is how --for finds it. Citations already in the code stay until their file is touched for another reason; then the one in the part you touch becomes its invariant in words. CI runs elixir scripts/decision-citations.exs --base HEAD^1 on every pull request and fails when a changed code file (.ex, .exs, .ts, .tsx and the other extensions it lists) cites a decision number more often than at the merge base; run it yourself with --base origin/<the branch you target>.
  • Commit messages and pull request titles state the behaviour that is now true, in plain prose ("A session's listing says what it has actually spent"), with a body saying what was wrong, what changed and why. No conventional-commit prefixes, no ticket numbers, no attribution trailers. Nothing enforces this. What is enforced is the one trailer a commit does carry: Signed-off-by:, from git commit -s, which the dco check requires (CONTRIBUTING.md).

5. Naming

Thing Pattern
Worker namespace and workload <namespacePrefix><profile>, default troupe-w-
Pod; its Service and Ingress troupe-w-<profile>-<ordinal>; <profile>-<ordinal>
Pod hostname <ordinal>-<profile>.<workersDomain> — one DNS label, so one wildcard covers every profile
Session id YYYYMMDDTHHMMSS-<4 random bytes, url-safe base64>
Service principal svc:<team>/<name>
Images troupe-operator, troupe-plane, troupe-worker, troupe-a2a, troupe-gui
Team and org volumes; a pod's own team-<team>, org; data
Tests <subject>_test.exs defining the subject module's name and Test (Troupe.Plane.AdminTest, Troupe.PolicyTest); test names are sentences stating a property; each file's @moduledoc says what it proves and how it skips

6. Recipes

An admin method. The function in Troupe.Plane.Admin (actor first, {:ok, result} or {:error, %Error{}}, authorisation and Audit.record/5 inside); a %Method{} in Troupe.Plane.Admin.API with a summary ending in a full stop, typed and described %Argument{}s, a risk, and confirm when destructive; its place on an area of the console's map in Troupe.Plane.Admin.Console; and in the console (clients/gui/apps/console), the client's call and a screen that makes it. The MCP tool appears by itself. Run admin_parity_test.exs, console_coverage_test.exs and the console's test/coverage.test.ts.

A protocol event. Add the type and its data to Troupe.Protocol.Schema.events/0 (or ephemeral_events/0), only ever adding fields; emit it through Session.Log.append/5; if the agent's replay acts on it, add it to Troupe.Log.Fold.witnessed_types/0 (the fold test reads the replay clauses and fails otherwise) and record a new fixture version rather than editing a hash; run mix troupe.schema.gen and commit protocol/schema/v1/; update the event table in PROTOCOL.md.

A protocol command. Troupe.Protocol.Schema.commands/0, the scope table and handler in Troupe.Gateway.Dispatch, schema regeneration, and a command_id if it changes anything. The GUI's side: a wrapper in packages/client/src/plane.ts (plane RPC) or a method on SessionView (a session command), an open type, an export from index.ts, a case in the test fakes.

A platform setting. A %Setting{} in Troupe.Plane.Settings with key, group, type, summary, consequence, effect and either app_key (the deployed value) or a fallback; editable: false for deployment values, secret: true for secrets. Read it with Settings.get/1 where it is used. The console, admin.settings.list, admin.setting.put and admin.setting.reset need no change. A deployed default also needs the variable in config/runtime.exs, the value in charts/troupe/values.yaml and a row in ../admin/configuration.md.

A GUI view. apps/desktop/src/views/<Name>.tsx, importing only React, @troupe/client, ../hooks, ../shell and sibling views; data through a hook, never a socket in a component; Pill, statusOf, Cost and friends from views/bits.tsx; a new colour starts as a token in every theme file (pnpm tokens refuses one that lacks it). Check it at 380 px, and that every status is a glyph and a word.