Executable architectural intent. The slice of project knowledge that has been promoted from documentation into machine-evaluable, enforceable constraints that bind AI agent behavior at generation time — not just read, but obeyed.
Concepts 9 min read · May 2026

# Executable Architectural Intent

Most project knowledge wants to be findable. A smaller, more important subset has to be binding. Executable architectural intent is the name for that subset — the slice of architectural knowledge that has been promoted out of documentation and into the layer where it can actually constrain what an AI agent does.

By Theo Valmis · Published May 2026

Teams writing for AI coding agents accumulate project knowledge fast: ADRs, PRDs, design notes, AGENTS.md files, NotebookLM corpora, Cursor rules, repo-native wikis. Almost all of it is useful, and almost all of it is reference material. It tells the agent what the system is.

A different question sits behind that body of work: which parts of this knowledge are not optional? Which decisions, if the agent ignored them, would make the result wrong even if it ran, passed tests, and looked locally plausible?

That subset has to live somewhere else. It is no longer documentation. It is executable architectural intent.

## The operational definition

Executable architectural intent is the slice of project knowledge that has been promoted from documentation into machine-evaluable, enforceable constraints that bind AI agent behavior at generation time.

Three properties distinguish it from ordinary project knowledge:

- It is binding, not informational. The agent does not have discretion to weigh it against task pressure. A run that violates it is a failed run, regardless of whether the rest of the output looks right.
- It is machine-evaluable. A hook or a CI gate can produce a deterministic verdict against the resulting artifact. The constraint is not a sentence in a doc; it is something a check can answer with pass or fail.
- It is traceable. Every verdict can be linked back to the source decision — the ADR, PRD, or policy it derives from — so enforcement is auditable rather than opaque.

Reference knowledge tells the agent what the system is. Executable architectural intent tells the agent what it is not allowed to change about that system while doing the task.

## Promotion: from documentation to constraint

Executable architectural intent does not appear by default. It exists because a team explicitly promoted a piece of knowledge from the wiki layer into the governance layer. The shape of that promotion:

Stage 01
Decision

An architectural choice is made — usually in an ADR, PRD, design doc, or policy note.

Stage 02
Reference

The decision lives in the project wiki or LLM-readable corpus. Agents can read it. Compliance is left to discretion.

Stage 03
Executable intent

The decision is encoded as a scoped, retrievable, enforceable constraint that enters the agent loop and produces deterministic verdicts.

Most architectural knowledge stops at stage two and should. Promotion to stage three is a deliberate act, applied selectively to the rules that genuinely have to bind agent behavior.

## The five-criteria bar

The signal that a piece of project knowledge is ready to be promoted is that it meets all five of the following criteria.

1. Explicit.Stated as a checkable rule, not implied across paragraphs of rationale.
2. Scoped.Tied to the part of the system it actually governs, so it is retrieved when relevant and silent when not.
3. Retrievable at the right moment.Surfaced into the agent’s context before it commits to a candidate change, not after.
4. Enforceable before code lands.Evaluable by a hook or CI gate that returns a deterministic verdict against the resulting artifact.
5. Auditable back to the source decision.Every verdict can be traced to the ADR, PRD, or policy it derives from, so enforcement is reviewable rather than opaque.

If any one of these is missing, the rule is still doing useful work in the wiki, but it is not yet executable intent. It is documentation that has aspirations.

## Why this category exists

Without an explicit name for this layer, teams end up putting binding rules into surfaces that were never designed to enforce them: long CLAUDE.md files, system prompts, prose in ADRs, PR review checklists. Each of those is a useful surface for its own purpose. None of them produces a deterministic verdict at the moment of generation.

The result is a familiar failure mode: the rule was documented, the agent read it, the agent generated code that contradicted it, and the violation was caught (or missed) only in review. The cause was not missing knowledge. It was the absence of an enforcement surface for the knowledge that was already there.

See: Your LLM Wiki Is a Library, Not a Law for the trend-capture version of this argument.

## How it differs from adjacent concepts

Layer | What it does | What it does not do
--- | --- | ---
LLM wiki / NotebookLM | Organizes project knowledge for agent retrieval | Cannot return a deterministic verdict at generation time
Prompt files (CLAUDE.md, AGENTS.md) | Reminds the agent what generally matters in the repo | Cannot prevent a session from ignoring or paraphrasing the rule
ADRs & PRDs | Records architectural and product decisions for humans | Cannot, on their own, enforce themselves on a generated artifact
Executable architectural intent | Binds agent behavior at generation and at merge | Does not replace any of the layers above — it sits on top of them

Executable architectural intent is the layer that turns selected pieces of project knowledge into rules the agent cannot route around. It is not a replacement for the wiki or for ADRs. It is the promotion path that some of their contents need to take.

## How Mneme implements it

Mneme is the infrastructure layer for executable architectural intent. Architectural decisions are encoded in a version-controlled corpus, retrieved through a deterministic scoping layer before agents generate, and validated at the hook and CI levels after generation. Each verdict carries provenance back to the source decision, so enforcement is reviewable rather than opaque.

The wiki keeps doing its job. ADRs keep doing theirs. Mneme handles the promoted slice: the constraints whose violation would make the run wrong.

## Frequently asked questions

What is executable architectural intent?
Executable architectural intent is the slice of project knowledge that has been promoted from documentation into machine-evaluable, enforceable constraints that bind AI agent behavior at generation time. It is the difference between an ADR an agent can read and a constraint the agent cannot violate.
How is executable architectural intent different from an LLM wiki?
An LLM wiki is a knowledge surface — it organizes project documentation so AI agents can read it. Executable architectural intent is a control surface — the subset of that knowledge encoded so it can be retrieved before generation, checked deterministically before merge, and traced back to its source decision. The wiki helps agents understand. Executable intent decides which parts of that understanding are binding.
What criteria turn project knowledge into executable architectural intent?
Five criteria: the knowledge must be explicit (stated as a checkable rule), scoped (tied to the part of the system it governs), retrievable at the right moment (surfaced before the agent generates), enforceable before code lands (a deterministic hook or CI verdict), and auditable back to the source decision (traceable to the ADR or PRD it derives from).
Does every architectural decision need to become executable?
No. Most project knowledge belongs in the wiki and should stay there. Reference material, design history, and rationale need to be findable, not enforceable. Only the subset of architectural intent that has to bind agent behavior — and that you would reject a PR for violating — should be promoted into the governance layer. Promotion is a deliberate decision, not an automatic one.
How does Mneme implement executable architectural intent?
Mneme treats architectural decisions as machine-evaluable constraints stored in a version-controlled corpus, retrieves them through a deterministic scoping layer before agents generate, and validates them at the hook and CI levels after generation. Each verdict carries provenance back to the source decision so enforcement is auditable, not opaque.

## Related reading

- Architectural Governance
- Governance Before Generation
- Verification Contracts
- Deterministic Enforcement
- Enforcement Provenance
- Your LLM Wiki Is a Library, Not a Law