Kjell Tore Guttormsen
449225454f
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
69 lines
4.7 KiB
Markdown
69 lines
4.7 KiB
Markdown
# 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):
|
|
|
|
1. **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.)
|
|
2. **This log is the cross-repo state.** Convention version, decisions, per-plugin conformance status,
|
|
open coordination items. All three sessions read it.
|
|
3. **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.
|
|
4. **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.
|
|
5. **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.)_
|