linkedin-studio/docs/okf-convergence-brief.md

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