Stemma compiles agent rules into CLAUDE.md and AGENTS.md

Stemma compiles a single canonical set of repository instructions into the native formats of four coding agents: GitHub Copilot, Claude Code, Codex and Kiro. The command-line tool is written by Alex Viñola, published on GitHub under an MIT licence, and ships without a language model, network calls or telemetry.

At a glance

• Every provider file becomes a build artifact: the canonical project is a .stemma/ directory of Markdown entities with front matter, and stemma check --all fails a CI run when generated output is stale.
• The project ships as a single static binary with no cgo, about 12,000 lines of Go, zero dependencies and roughly 230 tests, with race and cross-platform CI on Linux, macOS and Windows.
• Cursor is the one declared identifier Stemma refuses rather than approximates, and requesting it exits with code 3, while lossy mappings such as Copilot exclude patterns must carry a diagnostic.

Repository guidance has multiplied faster than any convention for keeping it consistent: the same rule now lives in .github/copilot-instructions.md, CLAUDE.md, AGENTS.md and .kiro/steering/, each edited separately. Stemma's answer reads as a deliberate rejection of the obvious one, a compiler with an explicit grammar rather than a model that guesses intent, which likely trades coverage for output that can be diffed and reviewed line by line.

The canonical project is a .stemma/ directory of Markdown files, one entity per file

Each entity is an ordinary Markdown file with structured metadata in front matter. The directory holds project.json with name, targets and budgets, alongside context/, rules/, skills/, agents/, procedures/ and decisions/, plus provenance.json recording where each imported entity came from and manifest.json recording what Stemma generated.

Front matter carries fields such as priority: must and an activation block, for example a path-scoped rule limited to src/api/**. The body before any recognised heading is the instruction an agent sees; a ## Rationale section stays for human readers and costs no context token. After the initial stemma import, the loop is editing Markdown and running stemma apply --all --yes.

Four providers import and export both ways, and Cursor is refused with exit code 3

The compatibility matrix lists GitHub Copilot, Claude Code, Codex through AGENTS.md and Kiro as importable and exportable, with the limits named: Copilot's applyTo has no negative patterns, so excludes are lossy; Codex has directory proximity only and no native specialist agents; Kiro's inclusion field takes always, fileMatch, manual or auto.

For Claude Code, rules land in .claude/rules/ with paths:, and procedures become skills. Each entity gets exactly one outcome per target out of exact, adapted, lossy, blocked or skipped, and a lossy mapping must carry a diagnostic; the compiler fails its own build if an adapter omits one.

Writes are transactional with rollback, generated paths cannot escape the workspace, symlinks are refused, and Stemma never deletes or overwrites a file it did not write. A same-format round trip with no semantic change reproduces the original bytes, including line endings and BOM.

Stemma estimates an 82% cut in always-on context, without using a provider tokenizer

A target profile can re-scope an entity for one provider without changing canonical truth. In the documented example, canonical always-on context is about 72 tokens against 13 tokens for the target, the largest target scope is roughly 39 tokens under src/**, and the worst-case request comes to about 52 tokens. The figures are approximations, computed without a provider tokenizer.

The command set covers scan, import, validate, plan, apply, check, explain and version, each accepting --json, with exit codes documented in docs/diagnostics.md. A CI job runs stemma validate followed by stemma check --all --warnings-as-errors, which fails when generated output is stale. Deciding what belongs in every request stays with the maintainer; Stemma executes delivery decisions rather than inventing them.

Unsigned binaries and two defects The binaries are not code-signed, so Gatekeeper blocks the download on macOS and SmartScreen warns on Windows at first run; Viñola cites the recurring cost of a certificate, and Homebrew avoids the prompt. He calls the project early and points to two silent-conversion defects, among issues tracked publicly including ones found by independent audit, that he would fix before recommending Stemma for work nobody can review by hand. No timeline is given for either.