A coherence layer for Elixir/Phoenix projects.
A project is coherent to the degree that, at any point in its development, it can furnish any actor — human or model — with the minimal context sufficient to act in line with the user's intent, and can mechanically detect when the project has drifted from that intent.
Cohere makes that a measurable property of the project rather than a behavior of the agent, via three document kinds and the tooling that keeps them honest:
The map (
mix cohere.map) — a compact, git-tracked description of the system's actual shape, derived from the compiled application: contexts and their public API, Ecto schemas and associations, Phoenix routes, Oban workers and cron wiring. Never hand-edited, regenerated on demand, therefore it cannot lie.Intent cards (
mix cohere.gen.intent) — one small authored file per context holding only what cannot be derived: purpose, invariants, decisions with rejected alternatives, non-goals. Each card is bound to the context's public surface by hash. Living constraints.Design docs (
mix cohere.design) — one authored file per design: problem, existing ground, shape, promised surface, decisions. Drafts are work in flight; accepted designs are immutable history.
The developer surface is the feature loop, three verbs:
mix cohere.design <slug> starts a design with its ground delivered
onto the page; mix cohere.check is the one iterative command (and CI
gate — hard findings exit 1, design findings only advise); and
mix cohere.complete <slug> verifies the design's promised surface
exists in the compiled app, then flips it to accepted.
Work packets (mix cohere.packet) assemble the map slice and cards for
the contexts a task touches, so context is delivered to an agent rather
than rediscovered by it.
The coherence ladder
| Level | Property | Mechanism |
|---|---|---|
| 0 | Context by discovery | raw repo; agents grep and hope |
| 1 | Static guidance | AGENTS.md / usage-rules |
| 2 | Derived truth | the map |
| 3 | Authored intent, checked | intent cards + design docs + the check gate |
| 4 | Governed verbs, verified behavior | boundary enforcement, Tidewave runtime |
| 5 | Delivered context | work packets |
Each level is useful alone; adopt incrementally. mix cohere reports
where a project currently stands.
Design constraints
Cohere has zero runtime dependencies and makes no LLM calls: everything it produces is deterministic and CI-runnable. It probes for what's present (Ecto, Phoenix, Oban, boundary, Ash, Tidewave) and derives more when more is there — capability detection, not a required stack.