Evolith Core

Bilingual Navigation: Versión en Español

Your architecture rules, running on every PR.

_{Real output of the published CLI on an empty repository (2026-09-14, abridged; full 71-row capture).}

Architecture decisions tend to live in documents nobody reads again. Evolith turns them into rules that are checked automatically every time someone opens a pull request.

What it does

It reads your repository — folders, workflows, manifests, architecture decisions — and compares it against a library of rules about layering, dependencies, security and CI/CD. If a blocking rule is not met, the PR does not pass. It is a linter, but for architecture.

What makes it different

1. It counts what it could not check. A regular linter only reports what failed. Evolith also reports the rules it never got to evaluate; if one of them is blocking, the PR fails just the same. So "all green" never means "nothing was checked".

2. It follows the product lifecycle. Every product is in a phase: Discovery → Design → Construction → QA → Delivery. Evolith evaluates the gates of the current phase and does not recommend moving to the next one until they pass, keeping evidence of every step. Architecture decisions (ADRs) are written with the same tool and many rules derive from them.

Who it is for

• Teams that want their architecture decisions enforced automatically, not reviewed by hand.
• Platforms that need to block non-conformant artifacts before they reach production.
• AI agents that must validate their own output against the same rules as the human team.

Where to start

1. Try it in two minutes — one npx and you see your first result.
2. Four terms you need — rule, pack, topology and phase.
3. Use it in CI — so it runs on every PR.

Want more context? The phase gate, in the CLI and in the Tracker · What is inside · How it compares · What it is not · Documentation · Interactive atlas

---

Try it in two minutes

You need Node ≥ 18. No database, no server, no Docker; your code never leaves your machine.

npx -y @beyondnet/evolith-cli init --name my-project --yes   # writes evolith.yaml in the current directory
npx -y @beyondnet/evolith-cli validate --engine opa          # evaluates; exits 2 if anything blocking did not pass

The first run will fail, and that is fine: it is a baseline, not a grade. Many rules assume a layout your repository does not have yet. To start only from what you have already adopted:

npx -y @beyondnet/evolith-cli rulesets                        # lists the packs your installation loads
npx -y @beyondnet/evolith-cli validate --engine opa --select rulesets/acl/anti-corruption-layer.rules.json

init writes evolith.yaml with the product's name, type and phase and your stack; --engine opa picks the engine with the most coverage today (why, in Known limitations). What a first run looks like, row by row: capture. Full guide: Quickstart.

---

Four terms you need

• Rule — a check with an id, a priority (MUST / SHOULD / COULD) and a verdict: passed, failed or skipped (could not be evaluated). A MUST that ends skipped blocks exactly as a failed one.
• Pack — a *.rules.json file grouping rules by topic (ACL, security, CI…). evolith rulesets lists them; --select picks which ones to apply.
• Topology — the architecture style you declare: modular-monolith, distributed-modules, microservices, event-driven, serverless, edge-computing, data-mesh or agentic-ai. The same rules follow you when the monolith splits into services.
• Phase — where the product is in its lifecycle: Discovery → Design → Construction → QA → Delivery. Each phase has gates that block the move to the next one.

An ADR (Architecture Decision Record) is an architecture decision in writing; evolith adr create drafts one, and many rules are derived from them. Full glossary.

---

The phase gate, in the CLI and in the Tracker

The same corpus that fails a PR also decides whether a product may leave its phase. On the satellite from the first run, the Discovery gate asks for six artifacts and finds none:

_{Real output of the published CLI (2026-09-20, abridged; full capture). --core ../evolith is a checkout of this repository: the tarball does not carry the gate definitions yet (GT-714).}

The CLI evaluates and proposes; beyond the evidence it prints, it keeps nothing. Deciding, and keeping the decision, is what Evolith Tracker is for: the same gate around an initiative, with the criteria its type derives, the product owner's sign-off, and the phases that stay locked until the previous gate is approved.

_{Evolith Tracker's UAT environment on 2026-09-20, governing this repository as a product. Commercial product, not launched, private repository. The Core it calls is the one the CLI runs — and its repository-conformance call is what found GT-715 (Real status).}

---

In CI

- uses: beyondnetcode/evolith_arch32@v1
  with:
    fail-on-violation: true

Exit codes: 0 pass · 1 the tool failed · 2 the gate blocked · 3 invalid invocation. 1 and 3 mean the repository was not evaluated: they are not weaker forms of non-compliant, and the job summary says so in words.

For an AI agent, the same engine as an MCP server over stdio (Node ≥ 20):

{ "mcpServers": { "evolith": { "command": "npx", "args": ["-y", "@beyondnet/evolith-mcp"] } } }

---

What is inside

Product	Role
Evolith Core	The library of rules, ADRs and phase schemas. MIT and free: files you can read, edit and version
Evolith CLI	Evaluates your repository locally or in CI; manages ADRs and phase gates
MCP Services	The rules as live context for an agent
Core API	REST to query and evaluate remotely
Agent Runtime	Drives the Core from an agent, through Ports and Adapters. Experimental
Evolith Tracker	Commercial lifecycle-governance product: initiatives, phases, gate decisions and their approval trail, on top of the Core. In UAT (what it looks like); not yet launched; it will be the only paid one

How many rules, packs and ADRs your installation loads is printed by evolith rulesets; the tree's counts are measured by CI on every PR and published in the corpus inventory.

_{Open the interactive viewer — guided tour in eleven stops · drag to pan · scroll to zoom · numbers derived from the tree on every build}

---

How it compares

The tools people reach for first check different things, and the differences are in the rows, not in the adjectives. Verified against each tool's own documentation on 2026-09-19; corrections welcome as a PR.

	ArchUnit	dependency-cruiser	Conftest	Evolith
What it reads	JVM bytecode: classes, packages, layers	The JS/TS module import graph	Structured config files (YAML, JSON, HCL, Dockerfile…)	The repository around the code: layout, workflows, manifests, ADRs — not the AST
Rule language	Java fluent DSL, run as unit tests	JSON/JS config (forbidden / allowed)	Rego	Rego, compiled to Wasm, in JSON packs
Where rules live	In the code base, per repository	In the repository (.dependency-cruiser.js)	A policy directory; shareable with conftest pull (git, OCI)	A library outside the repositories, adopted per repository with --select
A rule that did not evaluate	Fails a rule whose should got an empty set (failOnEmptyShould, on by default)	severity: ignore skips it silently; no other outcome exists	No outcome: an undefined deny is a pass	skipped is a first-class verdict, counted next to passed and failed; a blocking skipped fails the run
Exit code	A failing unit test	The number of error violations	1 on failure (0/1/2 with --fail-on-warn)	0 pass · 1 the tool failed · 2 the gate blocked · 3 invalid invocation
Surfaces	Java tests	CLI (+ dependency graphs)	CLI	CLI · GitHub Action · MCP server · REST API
Rules derived from ADRs	—	—	—	Yes: evolith adr create, and many packs are derived from decisions
Language scope	JVM	JavaScript / TypeScript	Any structured file	Any repository for structural, CI/CD and ADR rules; Node/TypeScript for the dependency and linter rules
License	Apache-2.0	MIT	Apache-2.0	MIT

They are complements, not substitutes: ArchUnit and dependency-cruiser see inside the code, Conftest sees one file at a time, Evolith sees the repository as a governed unit and counts what it could not decide. Running Evolith next to one of them is the intended setup.

---

What it is not

• Not a replacement for ArchUnit, Conftest or dependency-cruiser; it complements them. Rules live outside the codebase, as data that governs many repositories and that an agent can read. Evolith is OPA underneath, and adds the rule library, the ADR-to-rule derivation and the coverage accounting.
• It does not read your code's AST. It inspects structure, workflows, manifests and governance artifacts; the subset that looks at dependencies and linters assumes a Node/TypeScript repository.
• It does not call any LLM. No command in the published CLI reaches one; "the LLM proposes, a deterministic verifier disposes" is a documented direction, not shipped behaviour. Network egress disclosure: Security Policy.

What this front page does not say — what each engine covers, counts that disagree, real adoption, unverified platforms — lives on a single dated page: Known limitations. It exists because a README that only tells the good part is exactly the defect Evolith detects.

---

Documentation

To…	Go to
Start from your role	Start by Role
Understand the rules and ADRs	Evolith Core hub
See the executable corpus	Rulesets · OPA policies · Schemas
Choose or migrate a topology	Topologies hub
Use the CLI, MCP or REST	Interfaces hub · Evolith CLI hub
See the project's state	Known limitations · Gap board · Maturity
Answer a specific question	Q&A · Glossary
Walk the whole corpus	Master Index · Product hub · Repository Taxonomy

---

Contributing

Start here: issues that are good for a first contribution — most touch a single file. Unsure before opening a PR? Discussions.

Three ways to contribute without writing TypeScript: correct a count that disagrees between docs and code · translate a hub into Spanish · add a rule to src/rulesets/.

Before the PR: Contribution Guide · Security Policy · AGENTS.md · CHANGELOG

---

License

Released under the MIT License.