DEV Community: Marco 'Gatto' Boffo

Don't store trust, derive it: a trust model for agent-written docs

Marco 'Gatto' Boffo — Sat, 15 Aug 2026 09:43:15 +0000

Your coding agent writes persistent knowledge now. CLAUDE.md files, memory directories, runbooks, "what I learned about this codebase" notes. If you use Claude Code, Cursor, or Codex daily, a growing share of the markdown in your repos was written by something that is not you.

The dangerous part is not that agents write wrong things. Humans do too. The dangerous part is that six weeks later, nothing in the file answers three basic questions:

Who wrote this: a person or a model?
Did anyone ever check it?
Is it still supposed to be true?

When the answers are missing, an agent that reads its own unverified guess treats it as ground truth and builds on top of it. The next session inherits the error with more confidence than the first one had. That is knowledge rot with a feedback loop.

The tempting fix that doesn't work

First instinct: add a field.

trusted: true
confidence: 0.87

A stored trust score has three problems:

It's an opinion, and it doesn't say whose.
It's not portable: your 0.87 is not my 0.87.
It rots silently: edit the content, the score stays.

It's a cache without an invalidation strategy. Same bug, different costume.

Record facts, derive the judgment

The Open Knowledge Format (OKF: an open, vendor-neutral spec announced by Google Cloud in June 2026, plain markdown + YAML frontmatter, no runtime, no SDK) takes the other route. I covered the format itself in a previous post: knowledge as a directory of markdown concepts, versioned next to the code it describes. Since then the spec moved to v0.2, and v0.2 is about exactly this problem. Frontmatter stores only observable events. Every consumer derives the judgment at read time.

---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
status: stable
generated: { by: doc_agent/1.0, at: 2026-06-14T10:00:00Z }
verified: { by: human:dana, at: 2026-06-20T09:00:00Z }
stale_after: 2026-09-23
sources:
  - id: auth-readme
    resource: https://github.com/acme/auth#readme
    author: team:auth
    last_modified: 2026-06-01
---

Everything here is a fact you could check:

Field	The fact it records
`generated: {by, at}`	Who produced the current content, and when it last meaningfully changed.
`verified: [{by, at}]`	Who confirmed it against its sources, and when. A list: a human sign-off plus a nightly process are independent events.
`status`, `stale_after`	Lifecycle: `draft / stable / deprecated`, and an absolute date after which the content is stale.
`sources[]`	What it derives from, with per-source credibility signals (`author`, `last_modified`, `usage_count`).

The load-bearing detail is the actor convention: human:dana for people, process:finance-nightly for automation, doc_agent/1.0 for agents and tools. The prefix is the machine-parseable part. Who wrote a concept and who checked it are deliberately separate fields, because the writer need not be the checker: an agent generating and a human confirming is the normal case, not the exception.

The derivation

The whole trust model is four rules a consumer applies at read time:

No verified key ⇒ unverified.
Verified by non-human: actors only ⇒ machine-confirmed.
Any human: verifier ⇒ human-reviewed.
today >= stale_after ⇒ stale, whatever the tier.

That's it. No score, no registry, nothing to keep in sync. And because generated.at and the latest verified[].at are both plain timestamps, a consumer can also see the case that stored scores hide: content that changed after its last verification. The check is still a fact; it just visibly no longer covers the current text.

Deriving instead of storing is not a new idea. Git does not store "this branch is merged": it derives it from the commit graph, so it can never be stale. A stored trust tier is a stored opinion, and it goes stale the moment anything around it moves. A derived tier is recomputed against today's date and the current frontmatter on every read.

One failure mode is worth automating away: humans:dana (a typo) is a non-human: actor, so a real human review silently downgrades to machine-confirmed. It's the one typo that changes a trust tier without breaking anything visibly, which is exactly the kind of bug that deserves a linter, not a code review.

What this looks like in practice

We maintain okf-skills, the Claude Code-native OKF toolchain: skills to produce, maintain, validate, and visualize bundles, plus a GitHub Action to gate them in CI with no agent at all. The graph renderer computes the trust tier and staleness badges at render time and stores neither. The validator enforces the frontmatter families and warns on actor near-misses like the humans: typo above.

The repo also documents itself in OKF, so you can browse a real bundle with derived trust signals as a live interactive graph: architecture, decisions, and the update log, each node showing who generated it and what tier that earns.

One thing we deliberately don't claim: that bundles make agents cheaper. We benchmarked a bundle's effect on agent answers early on (+8 points of claim coverage on "why" questions, no token savings) and then deleted the benchmark from the repo, because it measured an adoption pitch, not the standard. The trust model is the part we'd defend on its own: it makes agent-written knowledge auditable, and that property doesn't depend on a benchmark.

Try it

# as a Claude Code plugin
/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

# as agent skills (Claude Code, Cursor, Codex, 20+ agents)
npx skills add scaccogatto/okf-skills

# validate any bundle, zero config
uv run skills/validate/scripts/okf_validate.py .okf --strict

Then ask your agent to "document the auth service in OKF", and check the frontmatter it writes.

If your agents write knowledge your team reads, don't ask them to be right. Ask them to leave evidence: who wrote it, who checked it, until when it holds. Trust is not a field. It's a query.

OKF for Claude Code: structured, portable memory your agent (and team) can read

Marco 'Gatto' Boffo — Sun, 28 Jun 2026 12:44:50 +0000

The problem: agents forget your project every session

If you pair with a coding agent, you have lived this: a new session starts and the context is gone. The agent re-discovers your auth flow, re-guesses why a decision was made, re-reads the same files to rebuild a mental model you already explained yesterday. Project knowledge — the why behind your systems, the runbooks, the "don't touch this, here's the reason" — lives scattered across wikis, code comments, and people's heads. None of it travels with the code, and none of it survives a fresh context window.

CLAUDE.md helps, but it's for standing instructions, and it gets loaded wholesale into every prompt. Auto-memory captures what an agent picked up, but it's implicit, per-agent, and not reviewed. A wiki is for humans and needs exporting. There's a gap: curated team knowledge that's structured, versioned with the code, and readable by any agent or person.

What OKF is

Open Knowledge Format is an open, vendor-neutral format (announced by the Google Cloud Data Cloud team in June 2026, Apache-2.0) that represents knowledge as a directory of markdown files with YAML frontmatter. That's the whole idea. No schema registry, no runtime, no SDK. If you can cat a file you can read it; if you can git clone a repo you can ship it.

A bundle looks like this:

.okf/
├── index.md                  # progressive disclosure (root carries okf_version)
├── log.md                    # ISO-dated change history, newest first
├── services/auth-api.md      # one concept = one file; path is its ID
├── datasets/orders-db.md
├── decisions/use-okf.md
├── runbooks/payment-failures.md
└── metrics/checkout-conversion.md

Each concept needs exactly one thing to be conformant: YAML frontmatter with a non-empty type. Everything else is optional.

---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---

# Endpoints
| Method | Path     | Description               |
|--------|----------|---------------------------|
| `POST` | `/token` | Exchange creds for a JWT. |

Concepts link to each other with plain markdown links, which makes the bundle a graph of typed, cross-referenced knowledge — diffable, reviewable in PRs, and portable across tools because it's just text.

What okf-skills adds

OKF is the format. okf-skills is the Claude Code-native toolchain that teaches your agent to actually use it, driven by the verbatim v0.1 spec. It ships as a Claude Code plugin and as agent skills (installable on Cursor, Codex, and 20+ agents via skills.sh). Three pieces:

Skill	What it does
`/okf:okf`	Produce, maintain, and consume bundles, applying the spec and templates. Auto-triggers when a repo already has an OKF bundle.
`/okf:validate`	Deterministic §9 conformance check — a real Python checker, not an eyeball pass.
`/okf:visualize`	Render a bundle to a self-contained interactive HTML graph.

The validator and visualizer are standalone scripts too (uv run, PyYAML via PEP 723), so they work the same whether installed as a plugin or as skills. The visualizer output is a single viz.html — concepts as nodes, links as edges, a wiki-style detail panel with rendered markdown and "Links to / Cited by" backlinks. No backend; nothing leaves the page. There's a live demo of a real bundle, and the repo documents itself in OKF, with CI validating that bundle on every push.

Honest scope

A few things worth being straight about:

OKF is curation, not magic. It's a place to put knowledge deliberately, not a system that captures it automatically. Someone (you, or the agent on request) still writes the concepts. The payoff is durability and portability, not zero effort.
It's complementary, not a replacement. Use CLAUDE.md for how to behave, auto-memory for what the agent picked up, and an OKF bundle for what the team knows. They stack.
No hooks by design. The plugin won't silently rewrite your repo. Automatic upkeep is opt-in (see below).

Install and try it

As a Claude Code plugin:

/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

As agent skills (Claude Code, Cursor, Codex, 20+ agents):

npx skills add scaccogatto/okf-skills

Then capture, validate, and visualize:

/okf:okf produce .okf          # or just ask: "document the auth service in OKF"
/okf:validate .okf --strict
/okf:visualize .okf            # opens a shareable viz.html

Every concept gets a deep link — viz.html#services/auth-api loads the graph with that concept already selected.

To turn on automatic upkeep (consult .okf/ before tasks, write knowledge back after changes), paste templates/CLAUDE-okf.md into your project's CLAUDE.md. It's soft mode and entirely opt-in. The scripts need uv (or python3 + pyyaml).

Why bother

The pitch is small and concrete: give your project's knowledge one durable, diffable, portable home, versioned next to the code it describes — instead of re-explaining it to a fresh agent every morning. It's plain markdown, so worst case you've written some good docs your team can read. Best case your agent stops forgetting.

Repo, demo, and spec: github.com/scaccogatto/okf-skills. Issues and PRs welcome.