open/ms-ai-architect
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ms-ai-architect/docs/okf-second-brain-brief-2026-06.md
Kjell Tore Guttormsen 72a7e2b84e docs(ms-ai-architect): ratifiser OKF second-brain spec v0.1 + adapter lokal plan [skip-docs] 
- Lokal brief refererer naa delt catalog/docs/okf-second-brain/spec.md (eneste kilde),
  restater ikke konvensjonen.
- Premiss-korreksjoner (spec §9): mdcode != OKF-verktoey (droppet); ingen gjenbrukbar
  OKF-ingest-kode (reference_agent GCP/Gemini-bundet -> prompt-moenstre, ikke kode);
  kanonisk anbefalt felt = resource (ikke source).
- Full OKF-pakke-ambisjon bestaar; minimal kontrakt (spec §3) = gulv, rike felt =
  extension keys (spec §5). Scope: kun brukerens second brain, IKKE de 389 skill-refs.
  Bygging = separat go.

OKF second-brain spec v0.1 ratified + plan adapted (2026-06-29)
2026-06-29 09:46:10 +02:00

8.9 KiB
Raw Blame History

Brief — Google OKF for brukerens «second brain» (LLM-wiki), IKKE for skill-refs

Notert 2026-06-26. Fremtidig initiativ — IKKE implementer før operatør sier fra. Bygger på research av GoogleCloudPlatform/knowledge-catalog (spec + samples + toolbox). State-of-play i STATE.md.

Delt spec er nå kilden (2026-06-29, ratifisert)

Konvensjonen er ikke lenger definert lokalt — den bor i catalog/docs/okf-second-brain/spec.md (v0.1, eid av ingen enkelt plugin; linkedin-studios brain/ er referansedesign, okrs okf-check.mjs referanse-checker; rollout/koordinering i samme mappes log.md). Denne brief-en er nå plugin-spesifikk plan, ikke konvensjonsdefinisjon — den refererer spec-en. Bekreftet for ms-ai-architect: minimal kontrakt (spec §3: type per konseptfil + index.md per nivå + okf_version i rot-index.md) er gulvet, ikke taket — vår «fulle OKF-pakke» rir over som extension keys (spec §5), ikke nivellert ned til bar OKF.

Premiss-korreksjoner (spec §9, ground-truth mot live repo — overstyrer økosystem-digesten under):

  1. mdcode/kcmd er IKKE et OKF-verktøy — det er et Dataplex git-sync-verktøy med annet frontmatter-schema. Droppet fra adopsjonsplanen.
  2. Ingen gjenbrukbar OKF-ingest-kode finnes — reference_agent er BigQuery+Gemini/GCP-bundet. Adopter prompt-mønstrene, ikke koden. Classify/convert = bygg-selv.
  3. Kanonisk anbefalt feltnavn er resource (ikke source).

Scope-grense + ambisjon (ufravikelig, operatør-bekreftet 2026-06-26)

  • OKF gjelder KUN brukerens egen kontekst/data — hans person- og organisasjonsspesifikke «second brain» / LLM-wiki (i dag onboarding-output i ~/.claude/ms-ai-architect/org/*.md).
  • For dette sporet kjøres FULL Google OKF-pakke (ikke bare lån av mønstre): frontmatter-kontrakt + index.md-progressiv-disclosure + retrieval + vedlikeholds-/enrichment-mekanisme, modellert på samples/ + toolbox/. Og adopsjonen holdes oppdatert etter hvert som OKF-standarden utvikler seg (v0.1 → senere versjoner; fang okf_version-bump). Operatør-direktiv 2026-06-26.
  • OKF gjelder IKKE de 389 skill-reference-filene. De forblir Claude Code skill-references (native mekanisme, Anthropic-anbefalt flat/progressiv-disclosure-struktur). Begrunnelse: se docs/ref-kb-direction-note-2026-06.md + rekonsidererings-konklusjon i memory okf-scope-second-brain-only.

Hvorfor OKF passer second brain (men ikke skill-refs)

Avgjørende skille er ikke «er det en LLM-wiki» (begge er det) — men «finnes det allerede en native, anbefalt mekanisme?»:

  • Skill-refs: JA — Claude Code skills + references + progressiv disclosure, allerede Anthropic-best-practice (flat, ett nivå dypt, store filer lastet on-demand, SKILL.md-hub + domene-mapper + grep). OKF ville erstattet et fungerende native system med et ekvivalent fremmed (OKFs retrieval-verdi over skills ≈ null; Grep/Glob/Read dekker allerede OKFs list/search/read).
  • Second brain: NEI — bor i dag i ad-hoc org/*.md uten retrieval-mekanisme under chat. OKF fyller et reelt tomrom: struktur + retrieval + vedlikeholds-tooling, vendor-nøytralt, portabelt, bruker-eid.

Lastemodell-skifte (operatør-presisering 2026-06-26 — reverserer tidligere antakelse)

  • Før (antatt): all kontekst injiseres når hver /architect:*-kommando kjøres.
  • Nå (mål): kontekst hentes smart/selektivt per kommando og per interaksjon — fordi de fleste ganger chatter brukeren med pluginen lastet, uten å kjøre kommandoer. Konteksten må være tilgjengelig i fri chat, hentet on-demand, ikke forhåndsinjisert.
  • Implikasjon: «second brain» trenger en retrieval-skill (list → search → read) som er aktiv uavhengig av kommandoer, + en vedlikeholds-mekanisme som holder wikien oppdatert etter hvert som brukeren tilfører kontekst OG etter hvert som OKF-standarden utvikler seg.

OKF v0.1 — kjernekontrakt (verifisert mot spec)

  • Bundle = katalogtre av markdown-filer, ett konsept per fil. Påkrevd frontmatter-felt: type. Anbefalt: title, description, resource (kilde-URI), tags, timestamp. Konsumenter MÅ bevare ukjente felt.
  • Reserverte filnavn: index.md (katalog-enumerasjon, ingen frontmatter, progressiv disclosure), log.md (endringslogg).
  • Kryss-lenking: bundle-relativ (/...) eller relativ markdown; relasjonstype utledes av prosa. Konsumenter må tolerere brutte lenker.
  • v0.1 (12. juni 2026), «starting point, not finished standard» → hold OKF-adopsjonen oppdatert ettersom standarden bumpes (okf_version i rot-index.md).
  • Kilde: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

Økosystem-digest (les disse FØRST ved implementasjon)

Repo: GoogleCloudPlatform/knowledge-catalog. Mye er GCP/Dataplex/Gemini-bundet (ikke direkte gjenbrukbart); de rene mønstrene vi adopterer er markert.

Konsum / smart retrieval (kjernen — ADOPTER MØNSTERET):

  • samples/enrichment/sample/config/skills/kb-search/SKILL.md — kanonisk skill-basert henteguide. Eksponerer trioen list_contents / read_file / search_content (= progressiv disclosure: finn → åpne kun relevant). Mest verdifulle fil å lese først.
  • samples/enrichment/sample/config/mcp.json + samples/enrichment/src/tools/fileskb/{README.md,main.py} — minimal stdio-MCP-server som eksponerer list/search/read over en markdown-katalog. NB: i Claude Code dekker Grep/Glob/Read dette allerede — egen MCP-server er trolig unødvendig; SKILL-instruksen («søk wikien først, åpne kun relevant») er det bærende.
  • samples/discovery/* — Dataplex-bundet søke-agent (Google ADK + CatalogServiceClient). IKKE gjenbrukbart; kun mønster-referanse.

Struktur / frontmatter-eksempler:

  • okf/bundles/ga4/index.md + okf/bundles/ga4/references/metrics/avg_pageviews.md — ekte index.md-hierarki + leaf-konsept med frontmatter (type/resource/title/description/tags/timestamp) + # Citations-seksjon. Kopier som mal.

Produksjon / vedlikehold (ADOPTER MØNSTERET, ikke koden):

  • okf/src/reference_agent/prompts/web_ingestion_instruction.md — kilde-drevet oppdatering: list_concepts → fetch → enrich/mint/skip med strenge frontmatter-/heading-bevaringsregler. Moden mal for «hold wikien oppdatert fra kilder».
  • okf/src/reference_agent/prompts/reference_instruction.md — deterministisk konsept-syntese (frontmatter + fast body-rekkefølge).
  • okf/src/reference_agent/cli.py — enrich / visualize-kommandoer (Gemini/BQ-bundet impl).
  • toolbox/mdcode/... — DØDT SPOR (spec §9.1): mdcode/kcmd er IKKE et OKF-verktøy, men et Dataplex git-sync-verktøy med et annet frontmatter-schema (id/resource.name/createTime/links). Ikke planlegg OKF-emit/sync via det.

Hva som må bygges (fremtidige faser — ikke nå)

  1. Frontmatter-/struktur-konvensjon for second brain: bygg mot delt spec §3 (type påkrevd + index.md per nivå + okf_version i rot). Anbefalte felt (spec §4): resource (kanonisk kilde-URI — IKKE source), title, description, tags, timestamp. Migrer dagens org/*.md (de mangler bare type: — nær OKF allerede).
  2. Retrieval-skill («second-brain-search» e.l.): list → search → read over ~/.claude/ms-ai-architect/org/, aktiv i fri chat (ikke bare kommandoer). Avgjør: ren SKILL+Grep/Glob/Read vs. dedikert MCP-server (build-both-and-measure-kandidat — se under).
  3. Vedlikeholds-mekanisme: hvordan wikien oppdateres når brukeren tilfører kontekst (onboarding-agent skriver OKF-konform), + en oppdaterings-rutine når OKF-standarden bumpes.

Åpne valg (operatør / måling)

  • Retrieval-mekanisme: SKILL + native Grep/Glob/Read vs. dedikert fileskb-MCP-server. Ekte tvil → kandidat for «implementer begge, mål hvilken gir best kontekst-treff for brukeren» (operatørs faktabasert-prinsipp).
  • Hvor mye av OKF formaliseres: full v0.1-konformitet vs. «OKF-kompatibel form» (frontmatter + index.md uten resten). Lén mot det letteste som gir smart retrieval.
  • Oppdaterings-kadens mot standarden: hvordan fange OKF-versjonsbump (v0.1 → …) uten manuell polling.

Suksesskriterium (per operatør 2026-06-26)

Det viktigste er ikke teknologien, men at second brain blir så bra som mulig for brukeren og at oppdateringsmekanismene fungerer veldig bra. Mål mot brukerverdi (henter pluginen riktig personlig/org-kontekst i chat?) + vedlikeholds-pålitelighet — ikke mot formell OKF-konformitet i seg selv.

Referanser