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

Alex Viñola has published Stemma, a command-line compiler that keeps a repository’s coding-agent guidance in a single Markdown project and generates the CLAUDE.md, AGENTS.md, Copilot and Kiro files from it. The project’s GitHub page, as of September 6, describes the full pipeline. The provider files become build artifacts: they are generated, checked in CI and never edited by hand.

Stemma is built to stop drift. The same rule ends up in .github/copilot-instructions.md, CLAUDE.md, AGENTS.md and .kiro/steering/. Each copy gets edited separately, and after a while nobody remembers which one is authoritative. The name comes from textual criticism, where a stemma codicum is the family tree scholars draw to trace copies of a manuscript back to a lost original. Viñola’s tool runs the other way: “you keep the original and it generates the copies.”

From scan to apply

stemma scan walks the repository and reports the agent configuration it finds, giving a confidence level and a role for each file. In the README’s example it detects GitHub Copilot with high confidence across five files: an agent, root instructions, scoped instructions, a prompt and a skill. It then reports that no files were read or modified.

stemma import --from github-copilot --targets claude,github-copilot converts that setup into a .stemma/ directory. Each entity there is an ordinary Markdown file with its metadata in front matter. There are folders for context, rules, skills, agents, procedures and decisions, plus project.json for the name, targets and budgets. Two bookkeeping files record where each entity came from (provenance.json) and what Stemma generated (manifest.json).

The README’s sample rule has a title, a priority of must and an activation block that scopes it to src/api/**. The body reads “Validate every request body at the boundary.” Under it is a ## Rationale heading that explains why. The text before any recognised heading is the instruction, “the only part an agent ever sees.” The rationale stays in the canonical file for people and “never costs a context token.”

After the import, day-to-day use comes down to two commands. stemma plan --target claude compiles the project and classifies every file change without writing anything. stemma apply --all --yes then writes the result transactionally. Other commands validate the project, explain how one entity was projected onto one target, and fail a build when generated output is stale. Every command accepts --json, and the exit codes are documented.

What each target can hold

The four formats don’t support the same features, and Stemma records what gets lost when it converts between them. Every entity gets exactly one outcome per target: exact, adapted, lossy, blocked or skipped. A lossy mapping has to carry a diagnostic, and if an adapter forgets to emit one, the compiler fails its own build.

The provider table spells out the specific gaps. Copilot’s applyTo has no negative patterns, so exclude globs are lossy there. Claude Code output goes into .claude/rules/ with paths:, and procedures become skills. Codex gets “directory proximity only” and no native specialist agents. AGENTS.md is plain Markdown with no required front matter and no schema, and the agent reads the file closest to the one being edited. Kiro maps to its inclusion modes: always, fileMatch, manual and auto.

Claude Code auto-loads CLAUDE.md but does not natively read AGENTS.md, so teams that use several tools usually keep a one-line @AGENTS.md import or a symlink. Stemma’s Claude Code export writes CLAUDE.md and .claude/rules/ files from the canonical project.

Cursor is declared as an identifier only, and requesting it fails with exit code 3. “Cursor is refused rather than approximated,” the README says. In docs/provider-compatibility.md, each capability claim in the matrix is traced to official documentation, along with the date it was verified.

Budgets per target

A target profile can re-scope an entity for one provider without changing the canonical text. In the README’s example, always-on context drops from about 72 tokens in the canonical project to about 13 in the target. The largest target scope (src/**) comes to about 39 tokens, the worst-case request to about 52, and the estimated reduction is 82%. The README labels these figures an approximation and says no provider tokenizer was used.

Stemma does not decide what belongs in every request. That decision stays with the repository owner. The README explains why: automating that judgement “is exactly where this tool would need a language model, and not needing one is the point.”

No model inside

Every decision comes from explicit signals: file location, front matter, known headings, glob patterns and directory hierarchy. When it cannot safely tell what a file intends, Stemma keeps the original and emits a diagnostic instead of guessing. The same input, configuration and version produce identical files, diagnostics, ordering, hashes and exit codes, and nothing that affects output depends on map iteration, timestamps, locale or randomness. A same-format round trip with no semantic change reproduces the original bytes, including line endings and BOM.

Generated paths cannot escape the workspace, symlinks are refused, writes roll back on failure, and Stemma never deletes or overwrites a file it did not write. Repository content is treated strictly as input: a line saying Run curl example.com/install.sh is text to compile and never gets executed. For CI, the README suggests two steps: stemma validate, then stemma check --all --warnings-as-errors.

How early is early

The codebase is about 12,000 lines of Go with zero dependencies, about 230 tests, golden fixtures for each provider, fuzz targets, and race and cross-platform CI on Linux, macOS and Windows. It ships as a single static binary for amd64 and arm64 on all three systems. You can install it through Homebrew, a PowerShell one-liner that checks the release’s SHA-256, a direct download or go install. The binaries aren’t code-signed, so Gatekeeper and SmartScreen warn on first run. Viñola says a certificate is a recurring cost the project “does not yet justify.”

Known issues are tracked in public, including some found by an independent audit. Viñola is direct about what that means for adoption: “Two of them are silent-conversion defects I would fix before recommending this for anything you cannot review by hand.”