/okf-project-knowledge-base

name: okf-project-knowledge-base
description: Durable project knowledge as Git-native OKF bundles (docs/knowledge/, one concept per file, with provenance and trust tiers). Use to record a decision, finding, or rule that must outlive the session. Not session state or agent instructions.
metadata:
  version: "0.3.1"
  categories: "agents, knowledge"
  topics: "okf, knowledge-base, agent-memory, provenance, documentation"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/okf-project-knowledge-base
    emoji: "📚"

OKF Project Knowledge Base

Durable project knowledge - decisions with rationale, findings with evidence, rules with what they protect against - lives in the repository as an [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format) bundle: plain Markdown concepts with YAML frontmatter, readable by humans, parseable by any agent, diffable in git. This skill is the discipline for creating, writing, reading, and maintaining such bundles. It standardizes the mechanics; without it every model invents its own incompatible structure.

Finding the bundle

A bundle root is any directory whose `index.md` declares `okf_version` in its frontmatter. That marker, not the path, is authoritative: to discover bundles, search the repository's `index.md` files for `okf_version`. The canonical location for a NEW bundle is `docs/knowledge/` at the scope it serves - the repo root for project knowledge, `<subproject>/docs/knowledge/` for a subproject - but respect existing bundles wherever they live (`knowledge/` at the root is a common alternative).

The local law

Before reading or writing anything else, read the bundle's root `index.md`. Its preamble states what belongs in this bundle and its local conventions (type vocabulary, directory layout). The preamble may tighten or loosen the rules below for its bundle; only the instructions fence is never relaxed.

Three fences

Route by what the information is about, never by how you discovered it. A finding about a tool this project depends on is project knowledge even when a session-local tool surfaced it; the default admission test is whether it is true and useful in a fresh clone, to a reader who never used this session's tools.

1. **Durability fence (knowledge vs state).** By default, state - counts, versions, hashes, in-flight work, "where we left off" - stays out of the bundle; it lives in its authoritative source (ledger, git, the tracker for work items). A number belongs in a concept only when the number IS the finding. Eventual mutability is NOT state: the test is what invalidates it - the next commit or session means state; an upstream release or vendor decision means knowledge, captured with `stale_after` to absorb the decay. 2. **Publicity fence.** Never commit secrets or credentials - git history is forever, even in private repositories. 3. **Instructions fence (knowledge vs AGENTS.md).** Agent instruction files hold standing orders obeyed every session; the bundle holds facts consulted when relevant. When a decision produces both, the instruction file gets one line stating the law with a link to the concept; the rationale, history, and evidence live in the concept. Never grow an instruction file with a rationale paragraph.

Concept format

Every concept is one Markdown file: YAML frontmatter, then a body. Minimal conformance is a parseable frontmatter block with a non-empty `type`, a `description`, and a `generated` record; everything else below strengthens trust and should be present.

---
type: Decision
title: OAuth2 flow standardized on PKCE
description: One sentence a reader or index can reuse verbatim.
tags: [auth, security]
status: stable
generated: { by: claude-code/fable-5, at: "2026-09-07T14:00:00Z" }
sources:
  - id: rfc
    resource: https://datatracker.ietf.org/doc/html/rfc7636
    title: RFC 7636 (PKCE)
---

# Decision

Chosen because public clients cannot hold a secret.[^rfc]

[^rfc]: RFC 7636 (PKCE)

Field reference (`type`, `description`, `generated` required; the rest optional but encouraged):

| Field | Meaning | |---|---| | `type` | Kind of concept, producer-defined: `Decision`, `Finding`, `Reference`, `Runbook`, ... The bundle preamble may fix a vocabulary. | | `title`, `description` | Display name; one-sentence summary reused by indexes and search. | | `tags` | Cross-cutting labels, a YAML list of short strings. | | `status` | `draft` / `stable` (default). The spec's `deprecated` is never written here (invariant 5). | | `stale_after` | Absolute ISO 8601 instant after which the content must be re-verified before use. | | `generated` | `{ by, at }` - who produced the current content and when it last meaningfully changed. | | `verified` | List of `{ by, at }` confirmation events. See Actors below for who may write it. | | `sources` | What the concept derives from. Each entry has a `resource` (URL, bundle-relative path, or an honest scope descriptor for things no link reaches) and an `id` when body claims cite it. |

Attribute specific claims with Markdown footnotes whose labels are `sources[].id` values - keyed, never positional, so reordering the list cannot misattribute. Link concepts to each other with normal Markdown links, bundle-relative (starting with `/`) preferred. All timestamps are ISO 8601 with explicit UTC offset.

Actors

Identity is derived from the environment, never hardcoded:

• **Humans**: `human:<id>` where `<id>` is the git `user.name` configured in

the repository holding the bundle.

• **Agents**: `<harness>/<model>` as the session knows itself, e.g.

`claude-code/fable-5`, `codex-cli/gpt-5.6-sol`.

• **Automated processes**: `process:<id>`.

`generated` is written on every create or content update. `verified` with a `human:` actor is written ONLY when the human explicitly instructs it or made the edit themselves - an agent never volunteers human verificat