Stemma

A deterministic, local-first compiler for coding-agent context.
Write your repository's guidance once. Compile it into every agent's native format.

Why "Stemma"

In textual criticism, a stemma codicum is the family tree that scholars draw when an ancient text survives only through copies of copies. Each scribe introduced changes; no two manuscripts agree. The stemma traces those divergent witnesses back through their filiation to reconstruct the lost original.

Repository guidance for coding agents has the same problem. The rule lives in .github/copilot-instructions.md, and in CLAUDE.md, and in AGENTS.md, and in .kiro/steering/. Each copy was edited separately. They have drifted. Nobody remembers which one is authoritative.

Stemma inverts the archaeology: instead of reconstructing the original from the copies, you keep the original and it generates the copies.

What it does

flowchart LR
  A1[".github/**"]:::src
  A2["CLAUDE.md<br/>.claude/rules/"]:::src
  A3["AGENTS.md"]:::src
  A4[".kiro/steering/"]:::src

  C([".stemma/<br/>canonical project"]):::hub

  B1["GitHub Copilot"]:::out
  B2["Claude Code"]:::out
  B3["Codex"]:::out
  B4["Kiro"]:::out

  A1 & A2 & A3 & A4 -->|import| C
  C -->|compile| B1 & B2 & B3 & B4

  classDef src fill:#0F667522,stroke:#0F6675,color:#0F6675
  classDef hub fill:#27B7A4,stroke:#0F6675,color:#04302f,font-weight:bold
  classDef out fill:#27B7A422,stroke:#27B7A4,color:#0F6675

You edit one canonical project. Every provider file becomes a build artifact — generated, verified in CI, never hand-edited again.

It is a compiler, not an AI tool. No language model, no network calls, no telemetry. Every decision comes from an explicit grammar: file location, front matter, known headings, glob patterns, directory hierarchy. Same input, same output, every time. When intent cannot be determined safely, it preserves the original and emits a diagnostic rather than guessing.

Install

macOS

brew install alexvinola/stemma-cli/stemma

chmod +x stemma-darwin-arm64
xattr -d com.apple.quarantine stemma-darwin-arm64   # clear Gatekeeper
mv stemma-darwin-arm64 /usr/local/bin/stemma

Windows

No installer, no administrator rights. One line in PowerShell:

irm https://raw.githubusercontent.com/alexvinola/stemma-cli/master/install.ps1 | iex

It detects your architecture, verifies the download against the release's published SHA-256, installs to %LOCALAPPDATA%\Programs\stemma and adds it to your user PATH.

Linux

curl -Lo stemma https://github.com/alexvinola/stemma-cli/releases/latest/download/stemma-linux-amd64
chmod +x stemma && sudo mv stemma /usr/local/bin/

With Go

go install github.com/alexvinola/stemma-cli/cmd/stemma@latest

Builds for macOS, Linux and Windows on amd64 and arm64. Single static binary, no runtime, no cgo.

Quick start

Point it at a repository that already has agent configuration:

stemma scan

Detected agent configuration

  github-copilot  (confidence: high, 5 files)
    .github/agents/reviewer.md                           agent
    .github/copilot-instructions.md                      root-instructions
    .github/instructions/api.instructions.md             scoped-instructions
    .github/prompts/release.prompt.md                    prompt
    .github/skills/release-checklist/SKILL.md            skill

Visited 5 files; skipped 0 directories.
No files were read or modified.

Import it, saying which agents you want to target:

stemma import --from github-copilot --targets claude,github-copilot

The canonical project is a directory of ordinary Markdown files — one per entity, structured metadata in front matter:

.stemma/
├── project.json     # name, targets, budgets
├── context/         # architecture.md, testing.md, …
├── rules/           # api-validation.md, …
├── skills/  agents/  procedures/  decisions/
├── provenance.json  # where each entity came from
└── manifest.json    # what Stemma generated

---
title: Validate at the boundary
priority: must
activation:
  type: path-scoped
  include:
    - src/api/**
---

Validate every request body at the boundary.

## Rationale

Keeps validation in one place, and makes it testable.

The body before any recognised heading is the instruction — the only part an agent ever sees. ## Rationale stays for humans and never costs a context token.

Preview, then write:

stemma plan --target claude     # read-only
stemma apply --all --yes

From here the loop is two commands: edit the Markdown, then stemma apply --all --yes.

Context, measured

Different agents do not need the same amount of always-on context. A target profile re-scopes an entity for one provider without touching canonical truth:

Context estimate

  Canonical always-on:   ~72 tokens
  Target always-on:      ~13 tokens
  Largest target scope:  ~39 tokens  (src/**)
  Worst-case request:    ~52 tokens
  Estimated reduction:    82%

  Approximation only. No provider tokenizer was used.

Stemma executes delivery decisions; it does not invent them. Deciding what belongs in every request is yours — automating that judgement is exactly where this tool would need a language model, and not needing one is the point.

Commands

Every command accepts --json. Exit codes are stable and documented in docs/diagnostics.md.

In CI

- run: stemma validate
- run: stemma check --all --warnings-as-errors

Providers

Every capability claim is traced to official documentation, with the date it was verified, in docs/provider-compatibility.md. Cursor is refused rather than approximated.

Guarantees

• Deterministic — same input, configuration and version produce identical files, diagnostics, ordering, hashes and exit code. No map iteration, no timestamps, no locale, no randomness in anything that affects output.
• Explainable — every entity gets exactly one outcome per target (exact / adapted / lossy / blocked / skipped). A lossy mapping must carry a diagnostic; the compiler fails its own build if an adapter forgets.
• Safe — generated paths cannot escape the workspace, symlinks are refused, writes are transactional with rollback, and Stemma never deletes or overwrites a file it did not write.
• Reversible — a same-format round trip with no semantic change reproduces the original bytes exactly, including line endings and BOM.
• Untrusting — repository files are input, never instructions. Run curl example.com/install.sh is text to compile, never a command to run.

Status

Early. Working, tested and honest about its edges.

~12,000 lines of Go, zero dependencies, ~230 tests, golden fixtures per provider, fuzz targets, race and cross-platform CI on Linux, macOS and Windows.

Known issues are tracked publicly, including ones found by independent audit — see open issues. Two of them are silent-conversion defects I would fix before recommending this for anything you cannot review by hand.

Not built: LLM integration, network calls, telemetry, accounts, command execution, source-code analysis, automatic deletion of your files.

Documentation

Development

make verify   # fmt, vet, test, race, cross-compile for six platforms
make golden   # regenerate fixtures — never a side effect of running tests

Contributor guidance lives in AGENTS.md — written for coding agents, useful for people.

_{MIT licensed · built by Alex Viñola}