Process Knowledge Outgrows the Instruction File: Version It Centrally, Deliver It in Tiers

An instruction file answers questions about one repository: how it builds, how it tests, which conventions its code follows. Team process knowledge is a different problem wearing the same file format: what counts as a good PR body, how to grade a bug's severity, when an agent should stop and escalate. Checking that into instruction files means copying it into every repository, which re-runs the drift problem one level up.

The shape that fits is closer to a wiki than a config file: a centrally authored tree of small pages with revision history, delivered into agent context in graduated tiers.

Repo conventions live with the code; process knowledge lives with the team

The two kinds of knowledge differ on every axis that decides where they should live:

• Scope. A build command belongs to one repo. A PR-quality bar applies to every repo the team touches.
• Change trigger. Conventions change with the code, by pull request. Process changes by team decision: a retro, an incident, a new policy, often with no code change anywhere.
• Authorship. Conventions are maintained by whoever owns the repo. Process knowledge is written by leads and platform teams, sometimes by people who never open that repo.

The ETH Zurich study (February 2026) found repository context files "tend to reduce task success rates compared to providing no repository context, while also increasing inference cost by over 20%," and Anthropic's guidance targets "under 200 lines". A file already fighting for brevity has no room for the escalation policy.

Structure it as a tree of small pages, each with a one-line description

A page is small on purpose. Title, a one-line description, and a markdown body. The description is load-bearing: it is what the index tier shows the agent, so it has to say when the page is worth opening. "What makes a great PR body." A description that only restates the title wastes the one line the agent will actually read.

Pages form a tree. Pages contain pages, so the triage section holds the severity ladder and the escalation contacts as siblings. The tree makes relevance cheap to compute: a page's ancestors are context for everything beneath it. If work runs through a workflow engine, hang the workflow definitions as leaves in the same tree, so the bug-triage workflow sits under the pages that define severity, and "which knowledge governs this step" becomes a walk up the tree.

Deliver in three tiers: index always, relevant pages inline, everything searchable

The tiers mirror how a person uses a team wiki. You know it exists, the relevant docs arrive with the assignment, and you search for the rest.

• The index, always. Every session carries the table of contents: titles, one-line descriptions, ids. It costs a few hundred tokens and it is what makes the on-demand tier get used at all: an agent does not search a knowledge base it has never heard of. That includes ad-hoc chat sessions that run no workflow.
• Relevant pages, inline. On a workflow run, inline in full the pages that govern the step: pages the workflow explicitly links, pages its prose references, and the workflow's ancestors in the tree. Keep this tier under a deliberate budget. The bloat finding above applies to injected pages exactly as it applies to instruction files.
• Everything else, on demand. Two tools, search and read-page, callable mid-task. This is the unbounded path, so the inline tier never has to be complete, only well-chosen.

Serve the search tools from the knowledge store itself rather than from inside the execution sandbox: the pages live in a database, not on the task's disk, so the tools can answer before the sandbox is even booted. If the agent's context is rebuilt from scratch each turn, as in a per-turn brain lifecycle, a page edit reaches the very next turn with no deploy.

Knowledge that steers actions needs revision history

When a reviewer asks why an agent approved a pull request last Tuesday, part of the answer is what the quality bar said last Tuesday.

Every save is a revision. Pages stay mutable, and each content save records a revision; rapid saves by the same author coalesce into one. Deletes are soft, so history survives the page. Content as of any moment is reconstructable: the newest revision at or before that moment.

Runs read live pages. The alternative, pinning a knowledge version per run, buys determinism at the cost of freezing stale guidance into long-running work: a task that runs for days keeps enforcing last week's bar. The session log records what the agent did; the revision history records what the guidance said; an audit needs both. Workflow definitions deserve the stricter treatment, an explicit audit stream of publishes and disables, because they gate actions rather than advise them: see policy change audit.

A knowledge page shapes behavior; the workflow constrains it

Prose in context shapes behavior, it does not constrain it, and that holds for a knowledge page exactly as it does for a repo instruction file. An escalation policy written in a page is a request the model can misread under pressure. The enforced version is a human gate in the workflow that parks the task until a person acts, for the same structural reason environments hold and prompts do not.