Intent Over Instructions: Why AI-Native Teams Need a Governed Shared Context Layer

Open an engineering repo that has recently adopted AI, and count the places that try to tell an agent how the team works. There’s a CLAUDE.md at the root, an AGENTS.md next to it, and a .cursor/rules directory. And on one senior engineer’s laptop sits a personal prompt file that’s better than all of them and has never left that laptop.

Each says a slightly different version of the same thing: here’s our architecture, here’s what not to touch, here’s how we test. They disagree with each other, nobody owns them, most are months stale, and the one that’s actually good is private.

That team believes it has context. What it actually has is a pile of instructions, aimed at tools, quietly decaying: a new hire learns the wrong architecture, a reviewer checks a change against stale rules, and an agent touches production code using context that wasn’t purposefully reviewed or approved. What the team lacks is one governed place to say what’s true, once, that people and agents can both trust: a “shared context layer”.

The label matters, because when a context layer fails, it usually fails organizationally, not technically. I’ve spent two decades leading engineering teams, the last few with agents doing real work inside them, and I’m sharing the context strategy I run as an open specification: Leji, pronounced LEH-jee, from the word “legible”. Leji stands on three principles: “intent over instructions,” “a circle, not a tier,” and “mechanism over goodwill.”

Instructions Fragment the Team’s Truth

The senior engineer with the private prompt file spent six months refining how she briefs an agent on the payments service: the invariants that never made the docs, the three integrations that look alike and behave differently, the migration other team members keep tripping over. She uses a different agent. Her stuff works, and her pull requests come back cleaner and faster than anyone else’s.

Not ideal, but that’s how plenty of us worked pre-AI. Her context is trapped in a format built for her agent host, so a teammate on a different one can’t use it, and when she’s out for a week it leaves with her. When the architecture changes, her file, the CLAUDE.md, and the Cursor rules drift independently, and no review catches it, because none of them go through the team’s review workflow.

That’s what imperative instructions do: each is written for one tool at one moment, so the same truth gets copied into five formats, and five formats rot at five different rates.

Leji rejects this premise. No entrypoint file holds canonical context, whichever host reads it: an entrypoint points to the boot profile, the one place people and agents both start from, and can carry host-specific mechanics, a model choice or a runner setting, but never team knowledge.

What separates those files is role, not origin. AGENTS.md is the portable one: it’s stewarded by the Linux Foundation’s Agentic AI Foundation and read natively by most hosts, so Leji writes a pointer-only AGENTS.md when your repo has none. Single-vendor files like CLAUDE.md or .cursorrules it never creates, and it converts them to redirects only if you ask. Portable or single-vendor changes only the tooling default, never where the truth lives. Boot context stays model- and agent-agnostic either way.

With a boot profile in place, the payments migration routes to three reviewed and approved documents, spelled out in a few lines a new hire and an agent read the same way:

## Loading
Before any task: boot-profile.md, governance/agent-rules.md

For a payments change, also read:
- domain/payments.md                  # what the terms mean
- system/payments-migration.md        # invariants a migration must hold
- decisions/2026-02-schema-split.md   # why the last schema change went this way

Nothing about the agent or the model changed, only the context, and who stands behind it.

Intent Outlives the Tool

If instructions are the wrong unit, intent is the right one: not “format every API response this way for this agent,” but the durable facts underneath, what the core nouns in your domain mean, what invariants every change has to respect, why a decision went the way it did, what an agent may do on its own and where it has to stop and ask.

Instructions tell an agent what to do. Intent tells a team what stays true even when the tools change, and tools turn over every few months now.

That’s why a context layer is organized around five intent-shaped categories, not tool-shaped ones. domain is your business language, in your own words. system is architecture and its invariants. practice is the conventions that have proven out. governance is the guardrails: what an agent may do unprompted, what needs a human gate. decisions are dated records of why things are as they are.

Nothing on that list names a vendor or a tool. That’s downstream: a person or an agent picks up a task, reads the slice of intent it touches, and derives the actions.

A Circle, Not a Tier

Most AI context today runs one direction, down a tier: people write instructions, the agent host loads them, the agent acts. Human-to-human knowledge stays in heads and Slack threads, and every agent host keeps its own slowly diverging copy.

Leji treats context as a circle instead, with three first-class flows: human-to-human (onboarding, review, settling a debate), human-to-AI, and human-to-AI-to-human (agent-drafted work a person reviews). The same system/payments-migration.md onboards a new hire, briefs the agent making the change, and anchors the reviewer checking it. A page only an agent ever reads rots unnoticed, but one that people and AI both read as source of truth gets fixed in one place.

The circle runs on equal access, not equal authority: a product manager who never touches git enters through the same door as a new hire and an agent, everyone with access reads the whole context layer, and anyone can propose a change, including an agent that finds the context wrong mid-task. People then approve what becomes canonical. Access itself is the version control system’s to grant. Context that needs a smaller audience lives in its own permissioned context layer.

Approval is accountability for meaning, not version-control mechanics: the person who owns a decision approves it whether or not she ever opens a terminal. In practice agents draft most changes. Deciding intent and approving it is the part that doesn’t delegate.

Mechanism over Goodwill

Shared context decays by default: reality moves, documents don’t, and nothing forces a wiki to stay current. On the payments team of one of my clients, an agent picked up a schema change and loaded a migration note superseded two quarters earlier, with nothing anywhere saying so. The code passed review because the reviewer trusted the same stale note, and it broke a downstream consumer in production. Nothing was missing. The wrong thing was present, current-looking, and owned by no one.

A context layer has three forcing functions a wiki lacks. Agents read from it on every task, so wrong context produces wrong output that is felt immediately, catching semantic drift no validator sees. Changes follow the same review as code, so there’s no separate documentation process to forget. And tooling fails the build on mechanical drift (a stale index, a malformed profile, a dead path) and reports what has aged past its freshness horizon, so neither tooling nor a conforming agent gets to treat stale context as current.

A context layer names a primary owner, not a custodian: accountable not for writing everything but for keeping the whole context current and tended in every area. A continuity owner can back her up when the person who knows leaves. Content earns its place only if it changes how future work gets done, and stale content gets pruned in ordinary reviewed changes, not in an annual cleanup that never quite happens. A context layer that only ever grows rots while passing review.

Honest Means Anyone Can Check It

A standard you can’t check is a slogan. So Leji ships a conformance ladder with four honest levels, plus reference tooling in Node, Python, and Go that checks a context layer against the level it claims. The checks are mechanical: edit system/payments-migration.md and the generated index no longer matches the tree, so from indexed upward leji validate fails in continuous integration (CI) before stale context ever reaches an agent.

• core: a context layer exists and both people and agents can work from it. Reaching it takes an afternoon.
• indexed: it’s legible to tooling, with a generated index and a machine-readable changelog. One tooling run gets you there.
• governed: the forcing functions are mechanical, not goodwill. Changes ride review, CI validates the surface, freshness is checked. This is where the context layer stops depending on anyone’s discipline.
• federated: one team’s truth, readable across many repositories.

Most teams should reach governed and stop. federated exists for organizations that genuinely need it. A team claims its level in its own manifest, and any conformant tool can verify the claim for free: no paid certification program, no registry gatekeeper, no usage fee. The spec, the schemas, and the reference tooling are open, and nothing stops you from building your own tooling on the spec instead.

The scope is deliberately small: Leji 1.0 standardizes the parts that usually show up in review, where context lives, who owns it, how it changes, and what an agent reads first, and leaves the execution machinery (task envelopes, agent handoff, orchestration) out for now. Leji is not a programming language, a runtime, or a service. It’s Markdown conventions, a few small JSON schemas, and governance semantics.

It Scales Down to One and Up to Many

Run it as a team of one and it becomes a personal operating system: present-you governs what future-you and your agents treat as true. I run my own work this way, with a second agent as reviewer, because rubber-stamping your own agent’s output is the solo version of the wiki problem.

Across an organization, when the risk team needs the payments team’s context, merging both into one repository fails the way a wiki fails, only faster: it separates payments’ content from payments’ accountability. Federation keeps them together: risk mounts the payments context layer at a pinned version, and nothing is copied. Mounting enables reading, not authority, and grants no access of its own: it routes people and agents who already have access, and payments still approves payments’ changes.

Three Checks You Can Run This Week

A CTO or an engineering leader can test this without adopting anything: pull up a repo with the team lead and ask three questions.

1. Where does canonical context live? If the answer is “depends which tool you ask,” name one boot profile as the entrypoint, or onboarding keeps teaching the wrong architecture.
2. Who approves a change to it? If the answer is “nobody, really,” name a primary owner accountable for currency, or stale rules keep passing review as current.
3. Do vendor files redirect or compete? If each has its own version, make CLAUDE.md and .cursor/rules redirect, or agents act on whichever copy they happen to hit.

None of this requires Leji. It requires deciding the answers are worth having.

Where Your Team Decides What’s True

Go back to that repo. None of those files is the problem. They’re symptoms of a decision the team never made: one place to say what’s true, rules for how it changes, a person accountable for it.

That, more than any tool choice, is what makes a team AI-native: not how many agents it runs, but whether people and agents work from the same governed truth.

Leji 1.0 went generally available today, frozen at the 1.3.0 tooling release: the specification, schemas, and reference tooling in three languages, all open at leji.org. Give it a try: it reads in a sitting, core takes an afternoon, and I’d love to hear what your team makes of it. But a spec only ever follows the decision, and this one no tool makes for you.