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.1 · 2026-06-29 · Cross-cutting catalog artifact, owned by no single plugin. 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 (e.g. ~/.claude/<plugin>/...).
• 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 (directory enumeration, no frontmatter, carries progressive-disclosure prose).
• MUST — the bundle-root index.md carries an okf_version marker (the upstream OKF version the bundle targets, currently 0.1).
• MUST (consumers) — preserve unknown frontmatter keys, tolerate unknown type values, tolerate broken cross-links.

This is exactly okr's okf-check.mjs semantics, generalized (§7).

4. Recommended fields (warnings, not errors)

title, description, resource (canonical source URI), tags, timestamp. Supply where cheap.

• 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 — directory enumeration, no frontmatter, progressive-disclosure prose. The bundle-root one carries okf_version.
• 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>

Verdict parity with okr's current checker is not established — do not rely on it. 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 — so the two can already diverge on the same input. The one parity check ever run was at lift-time, against okr's own fixtures, at bundle-verdict granularity — green then, but stale now and never per-file. A CI-run parity gate over a spec-derived adversarial corpus (check-okf-parity.mjs, tracked, not yet built) is what would establish parity; until then, treat the catalog checker as its own implementation of the §3 floor, not a verified twin of okr's. 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.

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

Two independent version markers:

• okf_version in each bundle-root index.md — the upstream Google OKF version the bundle targets (currently 0.1). When Google bumps OKF, each plugin re-checks conformance.
• This convention's version (top of this file) — bumped when the shared form changes. log.md records both. 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 v0.1: github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md (12 June 2026, "a starting point, not a finished standard").
• 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).