Kjell Tore Guttormsen 449225454f docs(catalog): add OKF-compatible second-brain form spec + coordination log

Cross-cutting catalog artifact (owned by no single plugin): the shared
"OKF-compatible second-brain form" convention all three second-brain plugins
(linkedin-studio, okr, ms-ai-architect) conform to, plus a coordination log
that serves as the cross-repo rollout state.

- spec.md: minimal contract (type + per-level index.md + root okf_version),
  recommended fields, extension keys, reference checker (okr okf-check),
  verified premise corrections (mdcode != OKF tool; no reusable OKF ingest),
  staged plan, homes, versioning. linkedin-studio's brain = reference design;
  OKF = thin interop veneer.
- log.md: coordination protocol (single source of truth, no cross-repo writes,
  operator relay), per-plugin conformance status table, open coordination items.

linkedin-studio recorded conformant (brain emits OKF form, cross-tool-verified
against okr's okf-check). okr / ms-ai-architect rollout = separate per-repo go.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012GqEHp4uDiivfrAUjw4BdE

2026-06-29 09:36:04 +02:00

4.7 KiB

Raw Blame History

OKF second-brain convergence — coordination log

Cross-repo coordination for the OKF-compatible second-brain form (spec.md). This is the one shared place all three plugin sessions read to know where the others are. OKF reserves log.md for change logs; this extends it with rollout status + the coordination protocol.

No writing crosses repo boundaries — each plugin session writes only its own repo (+ the catalog with its own go). Status here is updated via operator relay.

Coordination protocol

The operator runs one Claude session per plugin repo and relays between them. To keep three independent sessions converged without cross-repo writes (mirrors the maskinrommet feedback-register pattern):

Single source of truth = spec.md. The convention is defined once, here. No plugin redefines it locally; a plugin's local OKF doc references this file. (Mirrors the global rule: don't invent local mechanisms; extend the shared one.)
This log is the cross-repo state. Convention version, decisions, per-plugin conformance status, open coordination items. All three sessions read it.
No writing crosses repo boundaries. Each session writes only its own repo. The catalog is shared but needs a per-session go. A plugin records its own conformance in its own STATE/changelog; the operator relays it here.
Operator = relay + truth-source. Convention changes are proposed by any session, written here (with go), and the operator carries "convention changed → re-check conformance" to the other sessions.
Two version markers (spec §12): okf_version (upstream Google OKF) and this convention's own version. Either bump → log it below → each plugin re-checks.

Per-plugin conformance status

Legend: 🔵 not started · 🟡 building / partial · 🟢 conformant (+ commit-ref)

Plugin	Against minimal contract (spec §3)	Notes	Status
linkedin-studio	`type` + per-level `index.md` + root `okf_version` on `brain/`; `ingest/` excluded (round-trip-critical tributary)	Reference design. Emits frontmatter, adds no parser. Brain suite 134/134; okr's `okf-check` validates `brain/` → exit 0 (also mid-propose with a pending-diff present).	🟢 @ linkedin-studio `da0a16a` (2026-06-26)
okr	`type` required + recommended-as-warnings + `okf_version` echo	Has the reference writer + checker (`okf-check.mjs`, `okf-index.mjs`, `lib/frontmatter.mjs`) + skill `okr-second-brain-search` v1.6.1. Form-alignment to this spec = separate go.	🟡 built; spec-alignment pending
ms-ai-architect	designed, not built	Targets the fuller OKF package + a retrieval skill. Builds against this spec. Separate go.	🔵 designed

Open coordination items (what each session must confirm)

→ okr session:

Confirm okf-check.mjs semantics are stable enough to stand as the reference contract (spec §3, §7), and that this spec faithfully generalizes them (only-type-required; recommended → warnings; okf_version echo).
Canonical recommended-field name is resource (OKF), not source — confirm okr uses resource.
Flag any field okr needs that the minimal contract + recommended set doesn't cover.

→ ms-ai-architect session:

Confirm the minimal contract + extension-key model (spec §3, §5) supports the planned "full OKF package" KB structure — going fuller is fine; the minimal contract is the floor, not the ceiling.
Field-name drift: the architect brief writes source/timestamp (line 45); canonical is OKF's resource. Align on resource.
mdcode is not an OKF tool (spec §9.1) — drop it from the adoption plan. The reference_agent enrichment is GCP/Gemini-bound (spec §9.2) — adopt the prompt patterns, not as drop-in code.

→ both:

Ratify spec.md as the shared contract, or propose changes here.
Retrieval-skill naming/home: okr shipped okr-second-brain-search; architect plans second-brain-search. If a shared skill ever happens (Stage 3), converge naming + home (standalone plugin, spec §11) — not now (Stage 2 measurement must justify it first).

Change log

2026-06-29 — Convention v0.1 authored (spec.md) + this log. Seeded from the three per-plugin design notes + linkedin-studio's verified premise corrections (mdcode ≠ OKF tool; no reusable OKF ingest code; classify/convert is build-yourself). linkedin-studio recorded 🟢 (brain emits OKF-compatible form, cross-tool-verified against okr's okf-check). okr / ms-ai-architect rollout = separate per-repo go. (Authored by the linkedin-studio session; operator relay to siblings pending.)

4.7 KiB Raw Blame History