How it worksStudioCommandsFAQGitHub

Keep the meaning
of your software
as AI writes the code.

Avouch turns your design documents into one checked model of business rules. Coding agents read the rule before they change code, and CI fails when the documents and the model drift apart.

npx -y avouch init

Open source under Apache 2.0. Read only, except init, which asks before each change.

avouch query action BORROWOpen this model in Studio
id: BORROW
permission:
  form: keys
  alternatives:
    - keys: loan:create
      cite: [L10] `loan:create`
…
conditions:
  - id: book_available
    exprText: book_id.state = "AVAILABLE"
    cites:
      - [L6] BORROW creates a Loan for an AVAILABLE Book
…
decision:
  rows:
    - row: 1
      when:
        fails: book_available
      result: REJECTED
      cites:
        - [L6] BORROW of a Book that is not AVAILABLE is REJECTED.
… excerpt of the full answer

Code changes faster than anyone can track what it should do

Without a model

  • Each rule is split across product documents, decisions, APIs, schemas, tests and old code.
  • An agent reads what a handler does today. It cannot see which behavior the business expects.
  • When a source is missing or unclear, the agent fills the gap and nobody sees it.

With Avouch

  • Each rule is in one model in your repository, with a verbatim quote from its document.
  • The agent asks avouch query and gets the rule, its conditions and its cited source.
  • A rule that no document states is recorded as a gap, and a person decides it.

Every rule
cites its source.
A rule without one
is a gap, not a guess.

What you get

Agents change code from the rule

avouch query returns the permission, conditions, decision rows and effects of an action, each with its quote. In Claude Code, and in Codex after you approve it, a hook blocks grep and cat on the model.

Documents and model stay in step

avouch check runs 12 rules, such as "each quote is verbatim". gate docs fails a pull request that changes a document section without a review.

Gaps stay visible

When the documents do not say what happens, the model records the condition as unspecified. It does not invent an answer.

Runtime cases checked against the rules

reconcile and gate verify compare recorded runtime cases with each decision row.

Partly available: it checks recorded cases, not the code itself.

Not built yet: a semantic diff that shows which business behavior a change touches, and detection of conflicting sources.

How it works

One model in your repository. Agents read it, and CI keeps it equal to the documents.

Design documentsdocs/*.md, one section per heading
/avouch:scan
OntologyObjects, states, actions and rules, each with a cite
avouch query
Coding agentReads the rule before a change
check, gate docs
CIFails when the model and the documents drift
grep and cat on the model are blocked

Two more files support the model: avouch.config.json names the documents and the adapter, and avouch.ledger.jsonl keeps a review record per document section.

Set up your agents

Installs the plugin for Claude Code and Codex and adds the Avouch instructions to AGENTS.md and CLAUDE.md.

npx -y avouch init

Draft the first model

In Claude Code (/avouch:scan) or Codex ($avouch:scan). Drafts the config, the ontology and the review ledger. You review it until check passes.

/avouch:scan

Gate every pull request

Both commands exit 0 or fail the build. A full GitHub Actions example is in the README.

npx -y avouch check
npx -y avouch gate docs

Read the model in Avouch Studio

Avouch Studio shows an Avouch model in the browser, so a product owner or a reviewer can see what it says without reading YAML. Open a file, paste the text or give a URL. Studio keeps no data.

  • Objects and links as a graph, grouped by context.
  • What an action does: select it to mark the objects it creates, edits and reads, and the state transitions it triggers.
  • Where each rule comes from: each definition shows its source citations.
Avouch Studiolibrary.ontology.yaml
LoancreatesBookAVAILABLE → ON_LOANMemberBranchPerson
BORROW [L6] BORROW creates a Loan for an AVAILABLE Book

Commands

One CLI. Every command is read only, except init. Run avouch <command> --help for the usage.

CommandAnswersWhen
initSets up a repository for coding agents: the plugin and the AGENTS.md block.Once per repository
queryWhat writes or reads Order.status? What does PAY_ORDER require and change? What cites this section?avouch query <list|action|object|result|writes|reads|cites|link> <arg> [-f <ontology.yaml>]Before you change business logic
checkDoes the ontology agree with its sources? Each failure names its rule and line.After an edit, and in CI
gate docsWas each changed document section reviewed and recorded in the ledger?Every pull request, in CI
factsWhat does the adapter read from these documents? If no adapter is set, it names the smallest configuration.When you write documents to the convention
reconcile, gate verifyDo recorded runtime cases match the evaluator, and do they cover each decision row?When you record runtime cases

Questions

Is the format stable?

No. Experimental draft (0.x pre-release of format v1), not a standard. A change in 0.x can reject a file that passed before. The rules are in SPEC.md.

Do I need Claude Code?

No. Claude Code or Codex is needed only for the scan skill, which drafts the first model, and for the hook that blocks text reads of the model. The skill is /avouch:scan in Claude Code and $avouch:scan in Codex. In Codex, the hook runs only after you approve it when Codex asks. init --plugin installs the plugin for Claude Code and for Codex, whichever is on PATH. query, check and the gates run anywhere Node 22 runs, for example npx -y avouch query list. Codex and other agents read the instructions in AGENTS.md. Claude Code reads CLAUDE.md, and reads AGENTS.md when there is no CLAUDE.md or through a line @AGENTS.md in CLAUDE.md.

Does Avouch change my code?

No. Every command reads only, except init. init asks before each change, never creates a file, and --dry-run shows what it would do.

What do my documents need to look like?

Markdown that follows the Avouch convention needs only a short config. Other documents need an adapter module, which an agent can write from the adapter guide.

What happens when the documents do not say?

The model records the condition as unspecified, with the section it came from. It stays an open item until a person decides it.

Does it check my implementation?

Partly. reconcile and gate verify compare recorded runtime cases with the decision rows. Avouch does not read your source code.

What is the ledger?

avouch.ledger.jsonl has one entry per document section: a hash and the rules that cite it. gate docs uses it to find changed sections that nobody reviewed.

How do I set it up by hand?

Install the plugin. It adds /avouch:scan, /avouch:cli and the hook. In Claude Code:

claude plugin marketplace add githonllc/avouch
claude plugin install avouch@avouch

In Codex, where the skills are $avouch:scan and $avouch:cli and the hook runs after you approve it:

codex plugin marketplace add githonllc/avouch
codex plugin add avouch@avouch

Then add the Avouch block to AGENTS.md, which Codex reads. Claude Code reads CLAUDE.md, and AGENTS.md when there is no CLAUDE.md or through a line @AGENTS.md in CLAUDE.md. npx -y avouch init --print prints the block.

Set up your repository in one command

Then run /avouch:scan in Claude Code or $avouch:scan in Codex. The first model is a draft that you review.

npx -y avouch init