← knowledge.oriz.in

OKF graph discipline (inspired by okf-mcp)

rule agent-behaviorknowledgeokfgraphdiscipline

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 npx tsx scripts/okf-index-lookup.ts <term> to find the precise concept file. Read targeted; don't bulk-load.

2. Validate cross-links on write

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

npx tsx scripts/okf-index-lookup.ts --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