ktg-plugin-marketplace/docs/okf-second-brain/spec.md

# OKF-compatible second-brain form

A cross-plugin convention for how each plugin stores the **user's own context** — their
personal/organizational "second brain" / LLM-wiki — as a portable, interoperable markdown
bundle, compatible with Google's Open Knowledge Format (OKF) v0.1.

> **Version 0.3 · 2026-07-31 · Cross-cutting catalog artifact, owned by no single plugin.**
> _(0.3 corrects this convention's placement rule to match upstream: the bundle-root `okf_version`
> marker belongs in the root `index.md`'s **frontmatter block**, which is the one place upstream
> permits frontmatter in an `index.md` (§6). The value is now **unquoted before** the shape check,
> because upstream's own canonical example is quoted. `okf_layout` stays in body text (§12).
> 0.2 had tightened the §3 floor: `okf_version` enforced on shape. Distinct from — and
> deliberately no longer numerically confusable with — upstream Google OKF v0.1, which this
> convention targets and does not version.)_
> Reference design: linkedin-studio's `brain/`. Interop layer: Google OKF v0.1 (thin veneer).
> Change log + per-plugin rollout status + coordination protocol: `log.md` (same directory).

## 1. Purpose & scope

This convention exists for **interop**, not standard-adoption for its own sake. Three plugins in
this marketplace independently grew a user-owned "second brain" — a wiki of the user's personal and
organizational context the plugin retrieves from during chat and commands. This document defines the
**one shared on-disk form** so a single reader can traverse all three, and so a future shared
retrieval skill (if ever justified — §10) has one contract to build against.

- **In scope:** the user's own context/data — the per-user second brain. **Where** that brain sits on
  disk is *not* part of this contract (§8): the reference impl (okr) runs per **installation root**
  over a project installation root (`.claude/okr/`, cwd-relative) and a home installation root
  (`~/.claude/okr/org/`), and other consumers install none at all. A single `~/.claude/<plugin>/…`
  example would misstate both. _("Root" is overloaded across this ecosystem — installation root
  (here, §8), **bundle root** (an interior link-resolution origin, `method-spec.md:68-69`), **source
  root** (ingest extraction, `ingest-spec.md:106-108`), and the §3 **root marker**. Every bare use in
  this document means installation root.)_
- **Explicitly out of scope:** each plugin's **domain reference files** (skill `references/*`). Those
  stay native Claude Code skill-references (Anthropic-recommended progressive disclosure). The decisive
  test, which all three plugins reached independently: not "is it an LLM-wiki" (both are) but
  **"is there already a native, recommended mechanism?"** — for skill-refs YES (skills + references +
  grep), for the second brain NO (it lived in ad-hoc `org/*.md` with no retrieval mechanism). OKF fills
  a real gap **only** for the second brain.

## 2. The three consumers

| Plugin | Second-brain maturity | Role here |
|---|---|---|
| **linkedin-studio** | Provenance-weighted learning system (episodic/semantic split, evidence-threshold promotion, temporal validity). Most mature. | **Reference design.** Siblings rise toward it; it is not levelled down to bare OKF. |
| **okr** | Built: writer + checker (`okf-check.mjs`, `okf-index.mjs`) + retrieval skill `okr-second-brain-search`. | **Reference checker** (§7). |
| **ms-ai-architect** | Designed, not built. Targets the fuller OKF package + a retrieval skill. | Builds against this spec. |

Live rollout status (🔵/🟡/🟢 + commit-refs) lives in `log.md`, not here.

## 3. Minimal contract (normative)

A conforming **bundle** is a directory tree of markdown files, one concept per file. Concept ID =
file path minus `.md`.

- **MUST** — every concept file (every `.md` except `index.md`) carries a `type:` frontmatter key
  (free string, e.g. `Profile`, `Operations`, `JournalEntry`).
- **MUST** — every directory level has an `index.md` (an **authored** enumeration of that directory's
  children — **never a filesystem read**; carries progressive-disclosure prose). An `index.md` carries
  **no frontmatter, with one exception**: the bundle-root one MAY carry `okf_version` in a frontmatter
  block (§6, §12). This mirrors upstream verbatim (`okf/SPEC.md` §8:509-510).
- **MUST** — the bundle-root `index.md` carries an `okf_version` marker (the upstream OKF version the
  bundle targets, currently `0.1`). The value is the **upstream version alone**; a plugin's own layout
  revision belongs in the optional `okf_layout` marker (§12), never here. **Enforced on shape** — the
  gate rejects a value that is not version-shaped (`/^\d+(\.\d+)*$/`), which is what catches a layout
  snapshot sitting in this field. The value is **unquoted before** that check (0.3): quotes are YAML
  syntax, not value, and upstream's own canonical example writes `okf_version: "0.2"`
  (`okf/SPEC.md:773`) — a gate that rejected it would assert something upstream contradicts.
  Unquoting does not weaken the rule: a quoted layout snapshot still fails. The check deliberately
  asserts **nothing about which upstream versions exist**: that value set is Google's (§12), so a
  bundle targeting a newer upstream version passes. **Presence is not enforced** — an absent marker is
  reported, not failed; that is a separate step, not this one. **Placement is not enforced either**
  (0.3) — see §6.
- **MUST (consumers)** — preserve unknown frontmatter keys, tolerate unknown `type` values, tolerate
  broken cross-links.

This is a **superset** of upstream OKF, not a restatement of it — and it is a superset of **two**
contracts, which this document through 0.3 collapsed into one. There are three rungs, not two:

1. **Upstream requires `index.md` nowhere.** Its structure diagram marks the file `# Optional`
   (`okf/SPEC.md:117`), §8 opens «An `index.md` file MAY appear in any directory, including the
   bundle root» (`:504`), and §11 forbids a consumer to reject a bundle for «Missing `index.md`
   files» (`:759`). Read at `3fcbb9f`.
2. **A sibling contract binds the requirement to the bundle root alone** — commons'
   `method-spec.md:81-85`: a missing root `index.md` is an error, «this binds the **root alone**»,
   and a nested directory without its own `index.md` is not an error.
3. **The MUST above binds every level.** Highest rung; ours.

§8 permits a plugin to go further than the floor, and this is the catalog exercising that. A reader
must not take the MUST as upstream's requirement restated — **nor attribute rung 2 to Google, which
does not state it** (through 0.3 this paragraph did, citing `method-spec.md` for a sentence that
said "upstream"; corrected 2026-08-03 against `3fcbb9f`). okr's `okf-check.mjs` (§7) is the
reference implementation of *these* semantics.

## 4. Recommended fields (warnings, not errors)

`title`, `description`, `resource` (canonical source URI), `tags`, and a last-content-change
marker whose name depends on the bundle's `okf_version` (below). Supply where cheap.

- **The last-change marker is version-dependent.** A bundle declaring `okf_version` **< 0.2**
  (or none at all) uses **`timestamp`**; **>= 0.2** uses **`generated`**. Upstream retired the
  first in favour of `generated: { by, at }` — "`timestamp` is superseded by `generated.at`",
  one of v0.2's two breaking changes (`okf/SPEC.md` §13.1:802-803, read at `3fcbb9f`) — while
  still permitting a consumer to "fall back to a legacy `timestamp` when `generated` is absent"
  (`:804`). The gate therefore asks each bundle for the marker its own version names, and never
  nags a correct bundle of either version. An absent or non-version-shaped `okf_version` gets
  the legacy floor: absence is echoed, not failed (§3), so it still needs a defined list.
- **v0.2's *other* breaking change does not reach this floor — but it reaches a template.** Upstream
  also superseded the body `# Citations` list with frontmatter `sources`: consumers «SHOULD read
  `sources` and MAY still parse a legacy `# Citations` body list for v0.1 documents»
  (`okf/SPEC.md` §13.1:806-808, read at `3fcbb9f`). `sources` is recommended here, never required,
  so the §3 floor is untouched whichever form a bundle carries. **Measured 2026-08-03: no
  marketplace emitter writes `# Citations`.** The live exposure is a *plan*, not code —
  ms-ai-architect's design brief still names an upstream v0.1 example as the template to copy,
  carrying both `timestamp` and a `# Citations` section (`ms-ai-architect`
  `docs/okf-second-brain-brief-2026-06.md:56`). A bundle built from that template would be
  v0.1-shaped on **both** retired fields, which is conformant but ages the day it is written.
- **Canonical name is `resource`** (the OKF spec's name) — **not** `source`.
- A field that would break a plugin's invariant may be omitted. Example: linkedin-studio omits
  `timestamp` (its serializer is pure/deterministic — a timestamp would break round-trip) and
  `resource` (an internal concept has no canonical URI), keeping `type`/`title`/`description`.

## 5. Extension keys — rich fields ride along

OKF's permissiveness is the whole point for us: conforming costs `type` + `index.md`, nothing more. A
plugin's richer schema survives untouched as **extension frontmatter keys** that consumers MUST
preserve. linkedin-studio's brain keeps `provenance`, `first_seen`, `last_seen`, `evidence_count`,
`status`, and its episodic/semantic split — all as extension keys. Its model-collapse guard
(`provenance=published` only) is unaffected. **Plugins rise toward the richest design; they are not
levelled down to bare OKF.**

## 6. Reserved files & cross-links

- `index.md` — an **authored** enumeration of the directory's children (**never a filesystem read** —
  §3), progressive-disclosure prose, and **no frontmatter — with one exception**: the **bundle-root**
  `index.md` carries `okf_version` in a **frontmatter block**.

  **Canonical placement (0.3):** the frontmatter block. This follows upstream, which is unambiguous
  on both halves — «Index files contain no frontmatter, with one exception: a bundle-root `index.md`
  MAY carry an `okf_version` key» (`okf/SPEC.md` §8:509-510), declared «in a bundle-root `index.md`
  frontmatter block (the only place frontmatter is permitted in an `index.md`)» (§12:773-775). Read
  at upstream commit `3fcbb9f`. Through 0.2 this convention said the opposite — marker in body text,
  index files with no frontmatter at all — so the divergence was **ours against upstream**, and 0.3
  removes it rather than documenting it.

  **The pre-0.3 body-text form is still read and still passes.** Placement is **declared, not
  enforced**: the gate reports which form it found and does not fail on either. Two marketplace
  emitters wrote body text when 0.3 was cut (measured 2026-07-31), and the §7 parity gate compares
  this value against a sibling implementation's live checker — enforcing placement before the
  emitters migrate would redden that gate without a single bundle having become less conformant.
  Enforcement is a later step and needs its own ruling, exactly as presence does.
- `log.md` — change log (optional per bundle; reserved name).
- Cross-links — plain markdown (bundle-relative `/...` or relative); relation type conveyed by prose.
  Consumers MUST tolerate broken links.

## 7. Reference checker

okr's `scripts/okf-check.mjs` is the de-facto reference implementation of the minimal contract (§3):
only `type` required (missing → fail + names the files), recommended fields → warnings, root
`index.md` `okf_version` echoed for human comparison (no network — hooks are offline). ~91 lines, zero
npm dependencies, only couples to a ~55-line `frontmatter.mjs`. The shared spec **generalizes okr's
semantics; it does not reinvent them.** Reading okr's code is fine; **writing okr is a separate go.**

A **shared checker now lives here:** `catalog/scripts/okf-check.mjs` (+ vendored
`okf-frontmatter.mjs`), originally lifted from okr's reference impl at `c06e4d7` (2026-06-29),
output in English, zero deps, self-contained. It is the **canonical cross-plugin acceptance gate**
for this convention's §3 minimal contract. Run it per bundle root:

```
node catalog/scripts/okf-check.mjs <bundle-root>
```

**The two checkers provably diverge on the same input — and that divergence is now a running, tested
signal rather than a latent risk.** The catalog copy was lifted from okr once (`c06e4d7`); okr began
hardening its checker the next day (`3b45be7`, 2026-06-30: an `innboks/`+dot-dir walk ignore
`okf-check.mjs:37-38`, and a scoped `checkBundle(root, { strictIngest, files })` signature `:73`) and
added BOM/CRLF normalization weeks later (`482effb`, 2026-07-17; `lib/frontmatter.mjs:23`), while this
copy stayed frozen at the lift. A **running parity gate** now measures exactly this: `scripts/check-okf-parity.mjs`
compares the implementations **per file** (concept-set membership + type verdict, over default
read-mode) across a committed spec-adversarial corpus (`test/okf-parity-corpus/`) that carries
**red-proof** fixtures — inputs the gate MUST go red on, proving it is not green-on-everything. Honest
scope: only two implementations expose a runnable per-file checker today (catalog + okr), so the gate
runs **2-way** now and is architected n-way — llm-ingestion-okf's Python checker (fase 2) and its future
Node port slot in behind an availability guard when they legitimately exist. The gate does **not** claim
the two checkers are identical (they are not); it makes their divergence a monitored red/green fact and
pins a shared latent gap (both still descend into `node_modules`). Treat the catalog checker as its
**own** implementation of the §3 floor whose drift against okr is now watched, not a verified twin. A scaffolded linkedin-studio `brain/`
validates clean under this gate ("OK: valid OKF bundle", exit 0). Each plugin may keep its own dev-loop
check (linkedin-studio's TypeScript impl under `scripts/brain/` stays for its own suite); the catalog
`.mjs` is the shared gate for this convention's §3 floor. The only Stage-3 remainder is *reconciling*
the two language implementations into one — deferred until measured need, and **not** required for the
gate to function.

## 8. Deliberately NOT mandated

- **Auto-classify / convert** of arbitrary documents into the bundle — OKF provides nothing for it; a
  manual inbox/drop-zone seam suffices; build only on demonstrated need.
- **Retrieval mechanism** — native Grep/Glob/Read (skill instruction "search the wiki first, open only
  what's relevant") vs. a dedicated fileskb MCP server. All three plugins lean **native** (Claude
  Code's Grep/Glob/Read already cover OKF's list/search/read). Per-plugin choice; a "build both,
  measure" candidate.
- **Degree of OKF formalism** — full v0.1 conformance vs. this "OKF-compatible form." Plugins sit at
  different points (ms-ai-architect targets the fuller package; linkedin-studio emits the minimal form
  + extension keys; okr has writer + checker). **The minimal contract (§3) is the floor all meet;**
  going further is per-plugin and never required by this spec.
- **Placement — where a bundle lives on disk.** Unmandated, and *measured* rather than assumed
  (`log.md`, 2026-07-25): of the four consumers polled, exactly **one** installs a bundle anywhere
  (okr's two roots — §1), and **three install none** — the bundle directory is a
  caller-supplied argument per run, with no default, no discovery, and no `$HOME`/`~` expansion
  anywhere in their sources. **"No installation root" is a conforming consumer shape,** not a gap: a
  consumer may be handed a bundle it never placed. Note also that *installing* and *writing* are
  separate axes — a consumer can write into a bundle it did not place — so no rule here may assume
  the writer is the installer. This is why discovery keys on the §3 root marker rather than on a path
  (`log.md`, distilled note 3): a marker-based reader serves both shapes; a mandated path form serves
  neither.
  - **OPEN — which root wins when there is more than one.** The two shapes above are *installed* and
    *not installed*; okr is a third, **two marked installation roots at once**, and the marker
    predicate answers "is this a bundle?" without answering "which of these do I read?". Nor is there
    one answer: okr resolves it **per axis**. **Retrieval** globs **both** roots — union is the
    *search space*, with project content winning **on conflict only** (`SKILL.md:35,46,95`); the
    precedence there is a tie-break, not a lookup that stops at the first root. The org **profile**
    is the one axis that truly short-circuits (project overrides home, `inject-okr-context.mjs:54-56`).
    So union and precedence are not two axes but two *layers* on one: the roots carry *different
    content* rather than two versions of the same, which is why the search cannot stop early even
    though a conflict still needs a winner. This costs nothing while placement stays descriptive. It becomes the
    first question a second implementer asks the moment marker-based discovery is proposed as
    normative (§10, Stage 3), so it is named here rather than left implied by the two-shape framing.
    **Unresolved; do not plan against an assumed answer.**

## 9. Verified premise corrections (dead-ends — do not plan against these)

Ground-truth-checked against the live `GoogleCloudPlatform/knowledge-catalog` repo (research agent,
2026-06-26, file+URL log retained). These overturn earlier framing in the per-plugin design notes:

1. **`mdcode` / `kcmd` is NOT an OKF tool.** It is a Google Cloud **Dataplex** git-sync tool whose
   on-disk markdown carries a *different* frontmatter schema (`id`/`resource.name`/`createTime`/`links`)
   than OKF (`type`/`title`/`description`/`tags`/`timestamp`). Do **not** plan to emit or sync OKF
   bundles via mdcode. (Corrects the "metadata as code" pattern listed in ms-ai-architect's ecosystem
   digest.)
2. **No reusable OKF *ingest* code exists.** The repo's `reference_agent` is a BigQuery+web → OKF
   producer, Gemini/GCP-bound; it reads a BQ dataset + seed URLs, not a document folder. The GCP-free
   reusable parts are the **SPEC**, the **emit/serialize/validate** core, and the **`index.md`
   synthesis** — *patterns*, not a drop-in library. Classify/convert of arbitrary docs is 100%
   build-yourself.
3. **"OKF has no ingest" is true of the *format*, not the *repo*.** And the per-plugin design notes
   never actually asked for auto-classification — all three frame the work as *OKF as the storage form
   for a user-owned wiki* + a *retrieval skill* + a *maintenance mechanism*, with ingest being light
   ("onboarding writes OKF-conformant").

## 10. Staged plan

- **Stage 1 — Shared form (this document).** Cheap, delivers interop alone. Each plugin's user-data
  conforms; one reader traverses all three. **This alone meets the interop goal.**
- **Stage 2 — Measure divergence.** Do the per-plugin retrieval paths diverge enough to hurt? Only a
  *measured* "yes" justifies Stage 3 (operator anti-pattern: ambitious initiatives where a config tweak
  suffices).
- **Stage 3 — Conditional shared skill.** If justified: extract/generalize okr's working retrieval
  skill into one home (§11), with a discovery convention for where each plugin's brain lives. **Do not
  build before Stage 2 says so.**

## 11. Homes

- **This spec** — catalog/marketplace level (here), owned by no single plugin.
- **A future shared skill** (Stage 3 only) — a standalone marketplace plugin (own repo, release-tagged,
  catalog-pinned), installable alongside the others, serving the user's own context directly. Rejected
  alternatives: duplicate-per-plugin (drift risk); user-level `~/.claude/skills/` (unversioned, outside
  the catalog).

## 12. Versioning

Markers are kept deliberately separate. A single field must not carry two unrelated concerns — the
upstream OKF version *and* a plugin's own layout revision — so those are two distinct markers:

- **`okf_version`** — a key in each bundle-root `index.md`'s frontmatter block (§6); the upstream Google OKF version
  the bundle targets (currently `0.1`). **Required (§3).** Its value set is owned by Google, so the field
  has exactly one meaning and stays single-valued — the bundle-root marker (§6) relies on that. When
  Google bumps OKF, each plugin re-checks conformance.
- **`okf_layout`** — an *optional* marker; a plugin's own layout-revision snapshot
  (e.g. `kb-layout-2026-06`). Its value set is owned by the emitting plugin — not by OKF, not by this
  convention. It is **not** a version marker, never triggers a cross-plugin re-check, and a consumer that
  doesn't recognize it ignores it. This is where a plugin stamps its own layout revision, keeping
  `okf_version` reserved for the upstream version alone.

  **Placement (0.3): body text, not the frontmatter block.** When `okf_version` moved into
  frontmatter (§6), this marker deliberately did **not** follow it. Upstream's exception is
  enumerated to a single key — «a bundle-root `index.md` MAY carry **an `okf_version` key**»
  (`okf/SPEC.md` §8:509-510) — so the frontmatter block in an `index.md` exists by upstream's leave
  and for upstream's key. `okf_layout` is **this convention's** extension, and it stays outside the
  block upstream governs. The two markers therefore sit in the same file in different places, which
  is asymmetric on purpose: it is the reading that holds whichever way upstream's parenthesis is
  later construed (whether it bounds *where* a frontmatter block may appear or *which* keys it may
  carry — an open question this convention does not own). The gate does not read this marker at all.
- **This convention's version** (top of this file) — bumped when the shared *form* (the §3 floor)
  changes. `log.md` records bumps of the two versions (`okf_version` and this one); each triggers a
  per-plugin re-check. Hooks are offline (no auto-poll); version drift is caught by human review + the
  `okf_version` echo in `okf-check`.

## 13. Success criterion

Measured against **user value** (does the plugin retrieve the right personal/org context in chat and
commands?) + **maintenance reliability** — **not** against formal OKF conformance for its own sake.
(Operator, inherited identically by all three tracks.)

## 14. References

- **OKF SPEC:** `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`. **`main`
  has served v0.2 since 2026-07-24** (`780fe9d`, "okf: migrate format and tooling to Open Knowledge
  Format v0.2"; the SPEC was last touched at `3fcbb9f` the same day, and upstream had not moved
  when this was re-checked on 2026-08-03). Every upstream anchor in this document was read at
  `3fcbb9f`. Upstream publishes **no tags**, so the v0.1 text — the version this convention targets
  on the `okf_version` axis (§12) — is reachable only through history.
  _(Through 0.3 this entry read "OKF SPEC v0.1" while pointing at `main`; label and link had
  disagreed since the upstream bump. A reader following it got v0.2 under a v0.1 label.)_
- **Per-plugin design notes:** linkedin-studio `docs/okf-convergence-brief.md`; okr
  `docs/okf-second-brain-note-2026-06.md`; ms-ai-architect `docs/okf-second-brain-brief-2026-06.md`.
- **Shared checker (the cross-plugin gate):** `catalog/scripts/okf-check.mjs` (+ `okf-frontmatter.mjs`,
  `okf-check.test.mjs`) — lifted from okr's reference impl `okr/scripts/okf-check.mjs`
  (+ `okf-index.mjs`, `lib/frontmatter.mjs`).
- **Reference design:** linkedin-studio `docs/second-brain/architecture.md`; engine `scripts/brain/`.
- **Coordination + rollout status:** `log.md` (this directory).