Agent minimum-context protocol — find before deriving

rule Wed Jun 24 2026 00:00:00 GMT+0000 (Coordinated Universal Time) ruleagentknowledgenavigationcontextprotocolcookbook

Agent minimum-context protocol

TL;DR for any agent reading this

1. Decision-shaped question? ? open knowledge/_navigation.md, find the matching row, follow the link.
2. About to write a new rule/decision? ? first git grep -i '<keyword>' knowledge/ to find what already exists. If a related rule exists, edit it or supersede it; do not duplicate.
3. Writing a new knowledge file? ? keep it = 80 lines. One concept. Terse. Future agents pay tokens to read it.
4. Cross-reference everything ? use [[file-slug]] wikilinks to point at related knowledge files.
5. Update in same turn ? if a chat-decision is captured, the knowledge file lands in the same commit.

Why this matters

Every agent session pays tokens to load context. The knowledge bundle (knowledge/) is the shortcut: it pre-digests architectural decisions, taste rules, and runbooks so a fresh agent doesn't re-derive them from scratch. But the bundle only earns its keep if agents:

• Read it before reasoning. Otherwise the agent reinvents an inferior version of a decision already made.
• Don't bloat it. A 500-line "history of the decision" file costs more tokens to load than the 50-line "what we do + why" version. Every line is a tax on every future agent.
• Keep it discoverable. _navigation.md is the index. If a new concept doesn't have a nav entry, the next agent won't find it.

The 5-step protocol in detail

Step 1: Load the navigation index first

Before answering any question that smells like an architectural / naming / stack / policy choice, read knowledge/_navigation.md. It maps user intent ("looking for X") ? the right file. Reading nav costs ~2k tokens; reading the wrong files costs 10–50k tokens.

Trigger phrases that mean "go to nav first":

• "should I use X or Y", "what's our rule for Z", "where does W live", "how do we Q"
• Any mention of: secrets, env, mirror, backup, fork, naming, recruiter, ToS, license, distribution, Doppler, sops, B2, R2, GitHub Actions, knowledge, OKF

Step 2: Grep before writing

About to write knowledge/rules/foo.md or knowledge/decisions/bar/baz.md?

# From the umbrella root:
git grep -li '<keyword>' knowledge/
ls knowledge/rules/ knowledge/decisions/*/  | grep -i '<keyword>'

If a file already covers = 60% of what you're about to write — edit it, don't create a new one. If two files cover overlapping concepts, mark the older as superseded_by: <new-slug> and the newer as supersedes: <old-slug> (see _okf.md for the convention).

Step 3: Terse + self-contained

Every knowledge file is:

• = 80 lines for rules / decisions (runbooks can be longer because step-by-step).
• Self-contained for retrieval. A future agent reading just THIS file should be able to act. Don't say "see also [[X]]" without also stating the decision inline.
• One concept per file. "Two related decisions" = two files with related: cross-refs.
• Header is the contract. Title + description must be retrieval-friendly — assume an agent matches on title/description first, body second.

Step 4: Wikilink everything related

[[file-slug]] or <!-- TODO: broken link, was [file](../relative/path.md) --> — both work. Pick at least 2 related files to link from any new knowledge file. The bundle's graph density is what makes it navigable; isolated files rot.

Step 5: Same-turn commit

Per [[rules/self-update-rule]], when a chat-decision lands, the knowledge file lands in the same commit. NEVER "I'll add it later" — later means never. NEVER add knowledge/log.md entries that just restate the diff. The git log is the durable record of "what was decided when."

What to NEVER write to knowledge

(From the stricter self-update-rule revision):

• Count bumps. "72 submodules ? 73 submodules" — recoverable from git submodule status.
• Migration timestamps + step-logs. Git history records these.
• Re-statements of the diff. A commit message already says "added X as submodule." A knowledge file repeating that wastes tokens forever.
• Status updates / TODO lists. Those belong in commit messages or tasks, not durable knowledge.

Cookbook — recurring tasks and where to look first

Anti-patterns

• "Let me research this from scratch" when knowledge/ already has the answer. ALWAYS check nav first.
• "I'll write a quick rule" without checking if one exists. ALWAYS grep first.
• Writing 200-line knowledge files. Tokens compound. Split into 3 × 60-line files if there are 3 distinct concepts.
• Knowledge files without related: cross-refs. Isolated files become unfindable.
• Mentioning a decision in chat without committing the knowledge file in the same turn. Drift starts here.

Self-check before committing

# Before any commit that touches knowledge/, run:
git diff --cached --stat knowledge/

# If you wrote a new file: confirm it has nav entry, related: refs, = 80 lines.
# If you edited an existing file: confirm the title/description still matches.