OpenDomain: keeping business meaning in Git, where AI inferences stay candidates until a human accepts them
Git-native, evidence-backed domain semantic layer for AI agents and human maintainers.
At a glance
- What is it?
- OpenDomain is an Apache-2.0 tool that stores long-lived business concepts, rules and events as repository Markdown. Its core rule is that agent-inferred knowledge never becomes accepted automatically: it lands as a Candidate awaiting a human decision.
- Who is it for?
- Adopt OpenDomain if a team runs coding agents against a codebase whose business meaning needs to be explicit and governed: the Candidate boundary, where inferred knowledge waits for a human decision, and the schema-validated Markdown store are the reasons to choose it over a wiki.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
A durable semantic layer, separate from the code that changes
OpenDomain sets out to hold the things about a business that stay true for a long time: concepts, rules, lifecycles, events, the evidence behind them and their review state. The README calls it a Git-native, evidence-backed domain semantic layer for AI agents and human maintainers, and it keeps all of that in repository-readable Markdown with YAML front matter.
The intended user is a team using coding agents on a codebase where the business meaning is implicit, scattered across code and people's heads, and at risk of being quietly reinterpreted by whoever, or whatever, touches it next. It is aimed at the maintainer who wants an agent to ground its work in accepted domain knowledge before changing behaviour, and at the human who wants final say over what that knowledge is.
What makes it distinct is the boundary it draws around itself. The README is explicit that OpenDomain covers long-lived business semantics, what the business world is and which rules remain true, and deliberately does not cover change intent or delivery, which it leaves to planning tools like OpenSpec or Spec Kit, nor agent execution continuity, which it assigns to a separate tool called EchoPath. It is scoped to one job and says so.
The Candidate boundary is the whole idea
The single most important rule in OpenDomain is how it treats AI-inferred knowledge. The README states it plainly: AI-inferred knowledge never becomes accepted domain knowledge automatically. It starts as a Domain Candidate and requires an explicit human review decision, and the agent cannot bypass shell, network, filesystem, repository or approval policy.
This is a direct response to the failure mode of letting an agent write to a shared source of truth. An agent that infers a business rule and commits it as fact will, sooner or later, encode a plausible mistake that everything downstream then trusts. OpenDomain makes that structurally impossible by giving inferences a different status, Candidate, than accepted knowledge, and requiring a person to promote one to the other.
The README frames this as bounded agent autonomy with a clear split of responsibilities: the human owns goals, business boundaries, final meaning, risk trade-offs and final acceptance, while the agent owns reading the repository and environment, selecting the workflow, running tools while preserving evidence boundaries, and reporting validation and unresolved gaps. That division is the product. Everything else is machinery to enforce it.
Installing through Codex, or by hand
The README's recommended path is to let a Codex agent install OpenDomain by following a documented Agent Installation Contract, choosing an install channel, initialising, and proving readiness with `doctor` and `validate` without adding package metadata to the host project. For teams who prefer to do it themselves, the same channels are available manually.
The npm path is a global install followed by initialisation and two verification commands:
npm install --global @echopath-labs/opendomain
opendomain --version
opendomain init --tools codex
opendomain doctor
opendomain validateThe README says to use npm when Node.js 20 or Node.js 22 and newer is available, and to pin `@echopath-labs/opendomain@0.1.1` when an exact version is required. The `doctor` and `validate` steps matter: they are how the tool proves a workspace is set up correctly rather than assuming it, which suits a tool meant to be installed by an agent that then has to demonstrate the result.
`opendomain init --tools codex` is careful about what it touches. The README states it creates only OpenDomain-owned resources, an `opendomain/` directory tree, a managed block in `AGENTS.md`, and generated Codex skills under `.codex/skills/`, and that it does not create or modify the host project's `package.json`, lockfile, dependencies or npm scripts. That restraint is deliberate: a semantic layer should not entangle itself with the build system of the project it describes.
Working in natural language once it is installed
After installation the README shows the intended interaction as plain-language requests to Codex, with the managed repository instructions and generated skills routing each intent to the right OpenDomain workflow so the user does not pick CLI commands themselves. A read-only exploration is phrased as a request to explore the accepted model for something like order cancellation while keeping Candidate knowledge separate. A modelling request asks the agent to organise business rules and the concepts, relationships and states behind them, putting inferred knowledge into Candidates for review.
Review is where the human boundary is exercised: the README's example asks to review a specific candidate, show its evidence, conflicts and compatibility impact, then wait for the person's decision. Grounding an implementation task is a separate native entry point, and the README documents supplying OpenDomain's own request file:
opendomain assure --request <file>The README adds that agents using OpenSpec, Spec Kit or other tools can provide an OpenDomain request that references accepted domain IDs, and that OpenDomain defines its own contract rather than prescribing another tool's document format. So it interoperates without absorbing: a planning tool hands it accepted IDs, and OpenDomain grounds the work against them.
The honest limitations: early version and unsigned binaries
The maturity is what it is. The current stable release is `0.1.1`, and while the README labels the status stable and lists real capabilities, schema validation, reference integrity checks, deterministic Semantic Closure, optional multi-product workspace governance, this is an early version and should be read as one. The README's own upgrade note says `0.1.1` fixes missing grounding declarations and adds the native request entry over `0.1.0`, which is the normal churn of a young tool.
The distribution caveats are stated with unusual candour and deserve attention. For the standalone binaries, the README says the initial macOS binaries are ad-hoc signed but not notarized, Windows binaries are not Authenticode signed, and checksums detect file changes but do not establish publisher identity. In other words, verifying the `SHA256SUMS.txt` confirms the file was not altered in transit but does not prove who built it. A security-conscious team should prefer the npm channel, where provenance is at least tied to the registry, or accept that the binary path trades identity assurance for convenience.
The deeper limitation is conceptual: OpenDomain only helps if a team actually does the review. The Candidate mechanism guarantees a human decision point, but it cannot guarantee the human decides well. A team that rubber-stamps Candidates gets the ceremony of governance without its substance, and no tool can fix that.
Against putting domain knowledge in a wiki or ADRs
The usual home for long-lived business knowledge is a wiki or a set of Architecture Decision Records. Those are readable and familiar, and for many teams they are where the meaning already lives.
The difference OpenDomain argues for is machine-checkable structure and a controlled write path. A wiki page is free text: nothing validates that a rule references a concept that exists, nothing tracks which evidence supports a claim, and an agent editing it can write anything. OpenDomain stores concepts, rules, lifecycles and events as Markdown with YAML front matter that it schema-validates and checks for reference integrity, and it forces agent contributions through the Candidate gate. The README is explicit that ADRs and engineering plans remain external material, not managed business knowledge, so it is not trying to replace them; it is carving out the durable-semantics slice and making that slice enforceable. The trade is overhead. A wiki costs nothing to start and constrains nothing; OpenDomain adds a schema, a review workflow and a CLI in exchange for knowledge an agent can ground against and a human still controls. Choose the wiki when the knowledge is small and stable. Choose OpenDomain when agents are actively reading and proposing changes to business meaning and you need the write path governed.
Apache-2.0 and upgrade mechanics
OpenDomain is Apache-2.0 with a `NOTICE` file, which permits commercial use and derivatives with attribution and carries the patent grant, a sensible choice for a tool meant to be installed into other teams' repositories. The generated `opendomain/` content and the managed `AGENTS.md` block are compatible with normal Git versioning, and the README notes whether to commit them is the project's decision.
Upgrades are designed to preserve user content. The README's path from `0.1.0` is to update the CLI, then refresh each existing workspace with `opendomain update --json`, `opendomain doctor --json` and `opendomain validate --json`, and it states no domain model migration is required and existing inputs remain supported. The `--json` variants matter for the tool's own premise: an agent running the upgrade needs machine-readable output to confirm each step, which is consistent with a tool built to be operated by agents under human oversight.
The concrete thing to verify first is the boundary in practice. Run `opendomain init --tools codex` in a scratch copy and confirm it created only the `opendomain/` tree, the `AGENTS.md` block and the `.codex/skills/` skills while leaving your `package.json` and lockfile untouched, because that non-intrusiveness is the property that makes it safe to add to an existing repository, and it is easy to check before you trust it on a real one.
Editorial conclusion
Adopt OpenDomain if a team runs coding agents against a codebase whose business meaning needs to be explicit and governed: the Candidate boundary, where inferred knowledge waits for a human decision, and the schema-validated Markdown store are the reasons to choose it over a wiki. It is a poor fit if your domain knowledge is small and stable, where a wiki's zero overhead wins, or if you cannot commit to actually reviewing Candidates, since the gate only helps a team that uses it. Before trusting it on a real repository, run opendomain init --tools codex in a scratch copy to confirm it touches only the opendomain/ tree, AGENTS.md and .codex/skills/, and prefer the npm channel over the binaries, which the README says are unsigned and not notarized.
Frequently asked questions
What does OpenDomain store, and where?
It stores long-lived business concepts, rules, lifecycles, events, evidence and review state as repository Markdown with YAML front matter, validated for schema and reference integrity. The README calls it a Git-native, evidence-backed domain semantic layer.
Can an AI agent accept domain knowledge in OpenDomain on its own?
No. The README states AI-inferred knowledge never becomes accepted automatically; it starts as a Domain Candidate and requires an explicit human review decision, and the agent cannot bypass approval policy.
How do I install OpenDomain?
With Node.js 20 or 22 and newer, run npm install --global @echopath-labs/opendomain, then opendomain init --tools codex and verify with opendomain doctor and opendomain validate. Standalone binaries exist but the README notes they are unsigned.
Community notes