# Brief — Cross-plugin second-brain convergence on OKF-compatible form

> Created 2026-06-26. **Reference-design brief — not an implementation order.** Captures the operator-locked
> direction for converging three plugins' user-owned second brains onto one shared, interoperable form,
> with **linkedin-studio's brain as the reference design** and **Google OKF as a thin interop layer only**.
> Cross-cutting: most rollout lands in sibling repos and requires its own per-repo go (see §8). State-of-play
> in `STATE.md`. Companion design docs (read alongside): `okr/docs/okf-second-brain-note-2026-06.md`,
> `ms-ai-architect/docs/okf-second-brain-brief-2026-06.md`.

## 1. Locked decision (operator, 2026-06-26)

Converge on **the user's own context** (not the plugins' domain reference files), driven by **interop** —
**not** standard-adoption for its own sake.

- **linkedin-studio's brain is the reference design** — the most mature of the three (provenance-weighted
  learning, episodic/semantic split, evidence-threshold promotion). The siblings rise toward its maturity;
  it is **not** levelled down to bare OKF.
- **OKF is the thin interop veneer** — add `type:` + per-level `index.md`; keep all rich fields as extension
  keys (OKF consumers MUST preserve unknown keys). No capability is sacrificed.
- **Staged:** ship a shared **spec/convention first**; build a shared **skill only if measured divergence
  justifies it** (okr's retrieval already works — see §4).

## 2. Premise corrections (verified — these overturn the old STATE/memory framing)

The pre-existing framing ("greenfield shared ingest skill; inbox→classify→convert→emit OKF; mdcode is the
key tool") rested on three premises that ground-truth checks **disproved**. Verified against the live
`GoogleCloudPlatform/knowledge-catalog` repo (research agent, 2026-06-26, file+URL log retained) and the
sibling repos.

1. **`mdcode` is NOT an OKF tool.** It is a **Google Cloud Dataplex** git-sync tool whose on-disk `kb`
   markdown carries a *different* frontmatter schema (`id`/`resource.name`/`createTime`/`links`) than OKF
   (`type`/`title`/`description`/`tags`/`timestamp`). They are not interchangeable. Do **not** plan `kcmd`
   to emit or sync OKF bundles.
2. **"OKF has no ingest" is true of the *format*, not the *repo*.** The repo ships an OKF *producer*
   (`okf/src/reference_agent`, BigQuery+web→OKF) — but it reads a BigQuery dataset + seed URLs, **not** a
   document folder, and is Gemini/GCP-bound. The genuinely reusable, GCP-free parts are the **SPEC**, the
   **emit/serialize/validate** core (`OKFDocument`), and the `index.md` synthesis.
3. **Classify/convert of arbitrary documents is exactly what the repo provides *nothing* for** — those
   stages are 100% build-yourself. And — decisive — **the sibling design docs never asked for them.** Both
   frame the work as *OKF as the storage format for a user-owned second-brain wiki* + a **retrieval skill**
   + a **maintenance mechanism**, with ingest being light ("onboarding writes OKF-conformant"), not
   auto-classification.

## 3. Landscape — the three consumers have already diverged

| Plugin | Second-brain status | Maturity |
|---|---|---|
| **okr** | **Built.** `scripts/okf-index.mjs` + `okf-check.mjs` (conformance checker) + `lib/frontmatter.mjs` + skill `okr-second-brain-search` **v1.6.0** ("OKF-compatible markdown wiki") + tests + fixtures (`okf-minimal/`, `okf-realistic/`) + `inject-okr-context.mjs`. | Structured + retrieval (built) |
| **ms-ai-architect** | **Designed, not built.** `docs/okf-second-brain-brief-2026-06.md` (operator-confirmed) + `ref-kb-direction-note` + `ref-kb-workflow-plan`. No retrieval skill yet. | Designed |
| **linkedin-studio** | **Built, richer non-OKF schema.** `brain/` hub + `ingest/{inbox,published}` + `journal/` (episodic) + two-layer `profile.md` (semantic), provenance-weighting, evidence-threshold promotion, temporal validity. Engine: `scripts/brain/`. | Provenance-weighted learning system (most mature) |

**Reading of the siblings' own docs:** they chose OKF because their second brains lived in ad-hoc `org/*.md`
**with no retrieval mechanism** — for them OKF (really: *structured markdown + a retrieval skill*) was an
upgrade from nothing. linkedin-studio is already past that point. So the convergence is "siblings rise to
the reference," not "everyone adopts a new format."

## 4. okr already supplies the reference checker

`okr/scripts/okf-check.mjs` implements **exactly the minimal contract** this brief recommends, and is the
de-facto reference implementation to align the shared spec with:

- **Only `type:` is required** on a concept file (`.md` except `index.md`); ≥1 file without `type` → fail.
- Recommended fields (`resource`/`title`/`description`/`timestamp`) → **warnings, not errors**.
- Root `index.md` carries an `okf_version` marker, echoed for human comparison — **no auto-fetch** (hooks
  are no-network).

This means okr has **both** a writer and a checker in production. The shared artifact should generalize
okr's checker semantics, not reinvent them. (Reading okr's code is fine; **writing** okr is a separate go.)

## 5. OKF v0.1 — verified core contract

Source: `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md` (v0.1, 12 June 2026,
"a starting point, not a finished standard").

- **Bundle** = a directory tree of markdown files, **one concept per file**. **Concept ID** = file path
  minus `.md`.
- **Frontmatter:** required `type` (free string); recommended `title`, `description`, `resource`
  (canonical source URI), `tags`, `timestamp`. **Consumers MUST preserve unknown keys and tolerate unknown
  `type` values.** (Note: the Google *reference producer* is stricter than the spec — it also requires
  `title`/`description`/`timestamp`. Build to the spec; supply the rest where cheap.)
- **Reserved filenames:** `index.md` (directory enumeration, **no frontmatter**, progressive disclosure)
  and `log.md` (change log). Optional `okf_version` lives in the bundle-root `index.md`.
- **Cross-links:** plain markdown links (bundle-relative `/...` or relative); relation type is conveyed by
  prose. **Consumers MUST tolerate broken links.**
- **Permissiveness is the whole point for us:** OKF is a *minimal superset-friendly* contract. Conforming
  costs `type` + `index.md`; our rich fields ride along untouched as extension keys.

## 6. The deliverable — "OKF-compatible second-brain form"

A spec (document, not code) that all three plugins' user-data conforms to:

1. **Minimal contract:** every concept file carries `type:`; each directory level has an `index.md`;
   bundle-root `index.md` carries `okf_version`. Recommended fields where cheap. (= okr's `okf-check`
   semantics, generalized.)
2. **Rich fields survive as extension keys.** linkedin-studio's brain keeps `provenance`, `first_seen`,
   `last_seen`, `evidence_count`, `status`, episodic/semantic distinction — all as extra frontmatter keys
   OKF must preserve. The model-collapse guard (`provenance=published` only) is unaffected.
3. **Mapping for our brain** (illustrative; verify writers in §10):
   - `brain/index.md` → bundle-root index + `okf_version`.
   - `brain/profile.md`, `operations.md`, `journal/*.md`, tributary summaries → concept files; each gains a
     `type` (e.g. `Profile`, `Operations`, `JournalEntry`, `TributarySummary`) + retains its existing rich
     frontmatter.
   - `ingest/inbox/` stays the **manual drop-zone** (already exists) — the "inbox folder" mechanism, with
     no heavy auto-classifier built now.

## 7. Staged plan

- **Stage 1 — Shared spec/convention (cheap, delivers interop).** Author "OKF-compatible second-brain form"
  as a cross-cutting document; align it with okr's `okf-check`. Each plugin's user-data conforms; one
  reader can traverse all three. **This alone meets the interop goal.**
- **Stage 2 — Measure divergence.** Do the per-plugin retrieval skills (okr's built one; architect's
  planned one; linkedin-studio's in-context reads) 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
  `second-brain-search` into one home (see §9), with a discovery convention for where each plugin's brain
  lives.

## 8. Home decisions

- **The spec** is cross-cutting → **catalog/marketplace level** (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 **consumer (a) — the user's own context —
  directly**. Rejected alternatives: duplicate-per-plugin (drift risk); user-level `~/.claude/skills/`
  (unversioned, outside the catalog).

## 9. Per-repo scope boundaries (each its own explicit go)

| Repo | This initiative's work | Status |
|---|---|---|
| **linkedin-studio** (here) | (1) Be the reference design (mostly exists in `docs/second-brain/architecture.md`). (2) Make our own brain emit OKF-compatible form (`type` + per-level `index.md` + root `okf_version`) without dropping rich fields. | **In scope — (2) ✅ LANDED 2026-06-26** |

> **Stage-1 outcome (2026-06-26).** Brain writers now emit OKF-compatible form: `serializeProfile`
> leads with `type: Profile` frontmatter (constant → round-trip-safe), `operations.md` seed leads with
> `type: Operations`, `brain/index.md` carries an `okf_version: 0.1` marker, and `brain/journal/index.md`
> is scaffolded (per-level index). **Premise refinement (verified):** the brain is *deliberately*
> YAML-free with a byte-exact round-trip invariant on `ingest/published/*.md` (SC2) that a frontmatter
> block would break — so the OKF concept-bundle is scoped to **`brain/` only**; the round-trip-critical
> **`ingest/` tributary is excluded** and pointed to from the hub index. We **emit** frontmatter, adding
> no YAML parser. 5 new tests (`tests/okf-conform.test.ts`); full brain suite **132/132**; cross-tool
> proof — `okr/scripts/okf-check.mjs` validates `brain/` (exit 0). **Finish (same day):** the cheap
> recommended fields `title`/`description` added to the concept frontmatter (`timestamp`/`resource` stay
> out — a timestamp would break the pure serializer, `resource` is N/A for an internal concept); and the
> transient `brain/pending-diff.md` now carries `type: PendingDiff` so the bundle passes `okf-check` even
> mid-propose (re-verified exit 0 with a pending-diff present). Brain suite **134/134**.
| **okr** | Optional form-conformance alignment (already has writer + checker). | **Separate go** |
| **ms-ai-architect** | Build its retrieval skill against the shared spec. | **Separate go** |
| **catalog** | Host the shared spec. | **Separate go** (catalog only via `release-plugin.mjs`) |
| **new standalone plugin** | Stage-3 shared skill, if justified. | **Separate go** |

Per scope-guard + "never write in other repos without explicit instruction": this session touches
**linkedin-studio only**.

## 10. Key assumptions + tests (plan-quality mandate)

| Assumption | Test (before relying on it) |
|---|---|
| OKF preserves unknown keys → our rich brain fields survive conformance | **✅ Verified:** `okf-check.mjs` exits 0 on `brain/`; `profile.md` round-trips (`parseProfile` skips the frontmatter, `parse ∘ serialize` identity holds). |
| Our brain is already near-OKF (conformance is a small writer change) | **⚠️ Refined → verified:** brain is *deliberately* YAML-free and `ingest/published` is round-trip-critical, so a literal frontmatter target conflicts there → bundle scoped to `brain/`, `ingest/` excluded (tributary). 4 surgical writer touchpoints (3 scaffold seeds + `serializeProfile`); we EMIT frontmatter, add no parser. |
| okr's `okf-check` semantics generalize as the shared conformance contract | Diff okr's contract (only-`type`-required, recommended=warnings, `okf_version` echo) against OKF SPEC §9 conformance → confirm it is a faithful, slightly-laxer subset. |
| A shared skill is *not yet* justified | Stage-2 measurement, deferred — do not build Stage 3 before it. |

## 11. Open choices (resolve in `/trekbrief` or measurement, not now)

- **Retrieval mechanism:** native Grep/Glob/Read (skill instruction "search the wiki first, open only
  relevant") vs. a dedicated fileskb MCP server. Both sibling docs lean **native** (Claude Code's
  Grep/Glob/Read already cover OKF's list/search/read). Genuine doubt → "build both, measure" candidate.
- **Degree of OKF formalism:** full v0.1 conformance vs. "OKF-compatible form" (frontmatter + `index.md`
  only). Lean to the lightest that yields smart retrieval.
- **Inbox auto-classify/convert:** **defer.** OKF gives nothing for it; the manual inbox seam already
  exists. Build only on demonstrated need.
- **Discovery convention:** how a shared skill finds each plugin's brain root.
- **OKF version-bump tracking:** how to catch v0.1 → later without manual polling (hooks are no-network).

## 12. Success criterion (operator, inherited from both sibling tracks)

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.

## 13. References

- OKF SPEC v0.1: `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`
- Sibling design docs: `okr/docs/okf-second-brain-note-2026-06.md`,
  `ms-ai-architect/docs/okf-second-brain-brief-2026-06.md`,
  `ms-ai-architect/docs/ref-kb-direction-note-2026-06.md`
- okr reference implementation: `okr/scripts/okf-check.mjs`, `okr/scripts/okf-index.mjs`,
  `okr/skills/okr-second-brain-search/SKILL.md`
- Our reference design: `docs/second-brain/architecture.md`; engine `scripts/brain/`
- Verified-OKF research log (files+URLs fetched on `main`): retained in session transcript, 2026-06-26
- Memory: `google-okf-open-knowledge-format`, `profile-evolution-second-brain`,
  `plugin-vs-maskinrommet-division`, `plugin-is-domain-general`