oriz.in / knowledge
type: rule
status: active
timestamp: 2026-06-26
tags: [agent-behavior, knowledge, okf, graph, discipline]

OKF graph discipline (inspired by okf-mcp)

Validate cross-links, prefer index-scan over directory-scan, propose-first authoring, structured graph queries

OKF graph discipline

Operate over knowledge/ like okf-mcp would, without the MCP runtime.

The 5 contracts

1. Index-first navigation

NEVER grep/find/scan the full knowledge/ tree. ALWAYS query knowledge/index.md first (1285 lines, 792 files indexed) OR scripts/okf-index-lookup.py <term> to find the precise concept file. Read targeted; don’t bulk-load.

Every relative [text](path.md) and [[wiki-link]] you add to a knowledge file must resolve to an EXISTING file. Run:

py scripts/okf-index-lookup.py --validate-links <path>

before commit. Broken-link tolerance: 0.

3. Propose-first authoring (mental model, not tooling)

When the user gives a decision in chat, draft the OKF concept file as a “proposal” — show me the path + frontmatter + 3-line body BEFORE writing. If the user wants edits, edit before write. This is the manual equivalent of okf_propose_concept ? okf_accept_proposal. For grill-locked decisions where the user already approved, skip the proposal step (auto-accept).

4. Graph-aware writes

Every new concept file MUST have:

5. Reserved files

Why we don’t install okf-mcp itself

Per Q8 (2026-06-26 grill): the rule captures the discipline. Installing okf-mcp adds an MCP server dep + a JSON-RPC stdio process + a graph builder we’d never query at runtime — most of our agent reads happen through the Read tool directly. The okf-mcp PROTOCOL of “validate, propose-first, graph-link” is the value; the runtime is overhead at our size.

If knowledge/ grows past ~5000 files OR multiple agents need parallel structured queries, revisit the install decision.

Cross-refs

Edit on GitHub · Back to index