Shared conventions

September 7, 2026 ยท View on GitHub

Cross-cutting conventions every module obeys. A module spec should reference these rather than restating them.

DocumentCovers
code-style.mdWhere each constant and limit lives, comment style, and the lint rules you will trip.
model-selection.mdNever hardcoding a model id: the "auto" default, the resolver, role pins, and the entitlement predicate.
platform-compat.mdThe POSIX-call shim table: which platform_compat helper replaces each fcntl / os.kill / resource call, and why.
error-handling.mdException boundaries, retries, and user-facing failure text.
testing-conventions.mdTest patterns, which conftest owns which isolation, the side-effect floor, the six flake classes and the one correct fix for each, and how to keep the suite fast.
injected-messages.mdThe envelopes automation injects into a session (cron, subagent, auto-nudge) and how to treat them.