Align PKM skills with OKF v0.1 spec #14

New Issue

2026-07-06T21:23:29-04:00

steve commented

2026-07-06 21:23:29 -04:00

Problem Statement

The PKM skills in common/pkm/ (research-vault, pkm-curation, conversation-summary, crit) were built against an ad-hoc set of vault conventions that predate any formal knowledge representation spec. The Open Knowledge Format (OKF)
v0.1 now provides a standard for representing knowledge as self-describing markdown bundles. The skills need to be updated to produce OKF-conformant output while
remaining compatible with Obsidian and the existing vault at /home/sjb/Documents/sjb-brain.

Additionally, the vault itself has grown organically with inconsistent frontmatter, mixed link styles, and no bundle structure. A migration is needed to bring existing notes into conformance.

Solution

Adopt the OKF v0.1 spec as the structural backbone for all PKM skills and the vault. Key changes:

Replace [[wikilinks]] with standard markdown [...](...) links across all skills and vault notes
Adopt the OKF bundle model: a subdirectory with index.md (progressive-disclosure listing) and log.md (change history) is an OKF bundle
Merge OKF frontmatter fields (type, title, description, resource, tags, timestamp) with existing vault fields (id, aliases, area, project) into a single required schema
Define a fixed vocabulary of type values for the skills to use
Make the vault root a conformant bundle, and designate subdirectories as bundles or non-bundles
Migrate existing vault notes incrementally

User Stories

As a vault owner, I want the research-vault skill to create OKF-conformant research packets (bundles with index.md, log.md, and concept frontmatter), so that my research output is portable and agents can reliably consume it.
As a vault owner, I want the pkm-curation skill to add type to every note's frontmatter and use markdown links instead of wikilinks, so that curated notes are OKF-conformant.
As a vault owner, I want the conversation-summary skill to save conversation reports/transcripts into an OKF-conformant bundle (AI Conversation Summaries/ with index.md and log.md), so that summaries are discoverable and conformant.
As a vault owner, I want the vault-conventions.md reference file to document the merged frontmatter schema, bundle structure, and link conventions, so that all skills and agents share a single source of truth.
As a vault owner, I want the vault root to have an index.md and log.md listing the major sub-bundles, so that the entire vault is a valid OKF bundle.
As a vault owner, I want Knowledge/, Notes/, Resources/, Profiles/, AI Conversation Summaries/, each Research/<packet>/, and each Projects/<project>/ to be OKF-conformant bundles with index.md and log.md, so that agents can navigate them
progressively.
As a vault owner, I want existing notes in bundle directories to have their frontmatter updated (add type, convert wikilinks to markdown links), so that the migration is complete without breaking existing content.
As a vault owner, I want Inbox/, Dailies/, Templates/, and Clippings/ to remain non-bundle directories, so that temporary or structured-content areas are not forced into the bundle pattern.
As an agent, I want to be able to parse any note in the vault and reliably determine its type, title, description, and relationships via markdown links, so that I can traverse and summarize knowledge without guessing.
As a consumer of the skills repo, I want crit to remain vault-agnostic (no file I/O), so that the CRIT brainstorming framework is not coupled to vault structure.

Implementation Decisions

Frontmatter Schema (merged)

All notes created or curated by PKM skills MUST include this frontmatter:

---
type: <OKF type name>              # OKF required
title: <display name>              # OKF recommended
description: <one-line summary>    # OKF recommended
resource: <canonical URI>          # OKF recommended (when applicable)
tags: [<tag>, ...]                 # OKF recommended + vault required
timestamp: <ISO 8601 datetime>     # OKF recommended
id: <unique identifier>            # vault required
aliases: [<alias>, ...]            # vault required
area: <area/domain>                # vault required
project: <project name or ''>      # vault required
---

Type Vocabulary

Fixed set of type values across all PKM skills:

type	Purpose	Used by
`Inbox`	Raw capture, unprocessed	pkm-curation
`Source`	Based on external material	pkm-curation
`Concept`	One durable evergreen idea	pkm-curation, research-vault
`Project`	Active work, planning	pkm-curation
`Daily`	Day-specific activity	pkm-curation
`Reference`	Lookup material, specs	pkm-curation
`Conversation Report`	Narrative summary of conversation	conversation-summary
`Conversation Transcript`	Raw conversation transcript	conversation-summary, research-vault
`Research Synthesis`	Compiled answer for a research topic	research-vault
`Research Claim Index`	Collection of evidence-backed claims	research-vault
`Research Source List`	Index of sources consulted	research-vault
`Research Glossary`	Term definitions for a topic	research-vault
`Research Questions`	Open and resolved questions	research-vault
`Research Log`	Chronological research session log	research-vault
`MOC`	Map of content / curated index	pkm-curation
`Template`	Template note for note creation	pkm-curation
`Person`	A person you want notes about	pkm-curation
`Tool`	A tool, app, or service	pkm-curation

Link Convention

Standard markdown links [text](relative/path.md) replace Obsidian [[wikilinks]] throughout all skill instructions, reference files, and vault notes. Obsidian renders both syntaxes, so this is backward-compatible.

Bundle = subdirectory with index.md + log.md

index.md: OKF progressive-disclosure listing (no frontmatter, sections with bullet links + descriptions). See OKF §6.
log.md: OKF chronological update log (datestamped entries, newest first). See OKF §7.
Reserved filenames apply: index.md and log.md MUST NOT be used for concept documents.

Bundle map

Path	bundle?
`sjb-brain/` (root)	✅
`Knowledge/`	✅
`Notes/` + subdirs	✅ (each subdir is a sub-bundle)
`Resources/` + subdirs	✅ (each subdir is a sub-bundle)
`Profiles/`	✅
`AI Conversation Summaries/`	✅
`Research/<packet>/`	✅
`Projects/<project>/`	✅ (each project a bundle, migrate flat notes to dirs)
`Inbox/`	❌
`Dailies/`	❌
`Templates/`	❌
`Clippings/`	❌
`Tasks/`, `tools/`, `wts-services/`	⏳ deferred

Implementation order

Update common/pkm/pkm-curation/references/vault-conventions.md — single source of truth for the new conventions
Seed root bundle (sjb-brain/index.md, sjb-brain/log.md)
Retrofit existing bundles (create index.md/log.md, update frontmatter, convert links) — simplest first
Rewrite research-vault skill (packet template, bundle structure, frontmatter, links)
Rewrite pkm-curation skill (frontmatter normalization, link syntax, bundle awareness)
Rewrite conversation-summary skill (frontmatter, bundle structure, links)
Review crit skill for any references needing update
Reorganize Tasks/tools/wts-services (deferred)

Testing Decisions

These are agent skills — instructions for LLMs, not compiled code. Testing is therefore about conformance of the skill's output (notes written into the vault) against the OKF spec.

What makes a good test: An end-to-end invocation of each skill against a test vault, followed by automated conformance checks on the generated files.

Seams (from highest to lowest):

End-to-end conformance — Run each skill against a small test vault, then run an OKF bundle conformance check (§9 of OKF) on the output. This is the highest seam: if the files pass conformance, the skill did its job.
Frontmatter audit — For each note a skill creates, verify that all required fields (type, id, aliases, tags, area) are present and non-empty, and that recommended fields (title, description, timestamp) are present when applicable.
Link audit — Verify that all links use [...](...) syntax, not [[wikilinks]], and that links within a bundle use bundle-relative paths (prefixed with / for OKF absolute, or ./ for relative).
Bundle structure audit — For each directory designated as a bundle, verify that index.md and log.md exist and follow OKF format.

What will be tested:

research-vault — packet creation end-to-end
pkm-curation — note curation and atomic note extraction
conversation-summary — report/transcript pair creation
vault-conventions.md — correctness of the documented schema (manual review)

What will NOT be tested:

crit — no vault I/O
The vault migration itself (one-time process, validated by inspection)

Prior art: No existing test infrastructure for skills in this repo. Testing will be manual or script-based (shell checks + OKF conformance via custom script).

Out of Scope

Migration of Tasks/, tools/, wts-services/ directories — deferred until their content is reorganized
Automated vault migration tooling — the grilling session produced a phased manual plan, not a migration script
Changes to AGENTS.md in the vault root — that file serves a different purpose (agent instructions), not a concept doc
Changes to .obsidian/ configuration or plugins
CI/CD or automated test runners for skill conformance
Schema registry or central type authority (OKF explicitly does not require one)

Further Notes

The OKF spec is version 0.1 (draft). We should track upstream changes and adjust as the spec matures.
On case-sensitive filesystems (Linux), index.md and Index.md are distinct files — the vault has both forms in different places (e.g., research packets used Index.md). The migration must handle this carefully to avoid data loss.
The research-vault packet template needs the most structural rework: the existing Index.md (MOC-style with frontmatter) becomes OKF index.md (progressive disclosure, no frontmatter); Log.md becomes OKF log.md (datestamped entries); all other packet files get
concept frontmatter with proper type values.
Link migration (wikilinks → markdown links) across ~120 existing vault notes is the bulk of the retrofitting work. Skills should produce correct links going forward; the vault retrofit can be batched.

## Problem Statement The PKM skills in `common/pkm/` (`research-vault`, `pkm-curation`, `conversation-summary`, `crit`) were built against an ad-hoc set of vault conventions that predate any formal knowledge representation spec. The [Open Knowledge Format (OKF) v0.1](https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/refs/heads/main/okf/SPEC.md) now provides a standard for representing knowledge as self-describing markdown bundles. The skills need to be updated to produce OKF-conformant output while remaining compatible with Obsidian and the existing vault at `/home/sjb/Documents/sjb-brain`. Additionally, the vault itself has grown organically with inconsistent frontmatter, mixed link styles, and no bundle structure. A migration is needed to bring existing notes into conformance. ## Solution Adopt the OKF v0.1 spec as the structural backbone for all PKM skills and the vault. Key changes: 1. Replace `[[wikilinks]]` with standard markdown `[...](...)` links across all skills and vault notes 2. Adopt the OKF bundle model: a subdirectory with `index.md` (progressive-disclosure listing) and `log.md` (change history) is an OKF bundle 3. Merge OKF frontmatter fields (`type`, `title`, `description`, `resource`, `tags`, `timestamp`) with existing vault fields (`id`, `aliases`, `area`, `project`) into a single required schema 4. Define a fixed vocabulary of `type` values for the skills to use 5. Make the vault root a conformant bundle, and designate subdirectories as bundles or non-bundles 6. Migrate existing vault notes incrementally ## User Stories 1. As a vault owner, I want the `research-vault` skill to create OKF-conformant research packets (bundles with `index.md`, `log.md`, and concept frontmatter), so that my research output is portable and agents can reliably consume it. 2. As a vault owner, I want the `pkm-curation` skill to add `type` to every note's frontmatter and use markdown links instead of wikilinks, so that curated notes are OKF-conformant. 3. As a vault owner, I want the `conversation-summary` skill to save conversation reports/transcripts into an OKF-conformant bundle (`AI Conversation Summaries/` with `index.md` and `log.md`), so that summaries are discoverable and conformant. 4. As a vault owner, I want the `vault-conventions.md` reference file to document the merged frontmatter schema, bundle structure, and link conventions, so that all skills and agents share a single source of truth. 5. As a vault owner, I want the vault root to have an `index.md` and `log.md` listing the major sub-bundles, so that the entire vault is a valid OKF bundle. 6. As a vault owner, I want `Knowledge/`, `Notes/`, `Resources/`, `Profiles/`, `AI Conversation Summaries/`, each `Research/<packet>/`, and each `Projects/<project>/` to be OKF-conformant bundles with `index.md` and `log.md`, so that agents can navigate them progressively. 7. As a vault owner, I want existing notes in bundle directories to have their frontmatter updated (add `type`, convert wikilinks to markdown links), so that the migration is complete without breaking existing content. 8. As a vault owner, I want `Inbox/`, `Dailies/`, `Templates/`, and `Clippings/` to remain non-bundle directories, so that temporary or structured-content areas are not forced into the bundle pattern. 9. As an agent, I want to be able to parse any note in the vault and reliably determine its `type`, title, description, and relationships via markdown links, so that I can traverse and summarize knowledge without guessing. 10. As a consumer of the skills repo, I want `crit` to remain vault-agnostic (no file I/O), so that the CRIT brainstorming framework is not coupled to vault structure. ## Implementation Decisions ### Frontmatter Schema (merged) All notes created or curated by PKM skills MUST include this frontmatter: ```yaml --- type: <OKF type name> # OKF required title: <display name> # OKF recommended description: <one-line summary> # OKF recommended resource: <canonical URI> # OKF recommended (when applicable) tags: [<tag>, ...] # OKF recommended + vault required timestamp: <ISO 8601 datetime> # OKF recommended id: <unique identifier> # vault required aliases: [<alias>, ...] # vault required area: <area/domain> # vault required project: <project name or ''> # vault required --- ``` ### Type Vocabulary Fixed set of type values across all PKM skills: | type | Purpose | Used by | |------|---------|---------| | `Inbox` | Raw capture, unprocessed | pkm-curation | | `Source` | Based on external material | pkm-curation | | `Concept` | One durable evergreen idea | pkm-curation, research-vault | | `Project` | Active work, planning | pkm-curation | | `Daily` | Day-specific activity | pkm-curation | | `Reference` | Lookup material, specs | pkm-curation | | `Conversation Report` | Narrative summary of conversation | conversation-summary | | `Conversation Transcript` | Raw conversation transcript | conversation-summary, research-vault | | `Research Synthesis` | Compiled answer for a research topic | research-vault | | `Research Claim Index` | Collection of evidence-backed claims | research-vault | | `Research Source List` | Index of sources consulted | research-vault | | `Research Glossary` | Term definitions for a topic | research-vault | | `Research Questions` | Open and resolved questions | research-vault | | `Research Log` | Chronological research session log | research-vault | | `MOC` | Map of content / curated index | pkm-curation | | `Template` | Template note for note creation | pkm-curation | | `Person` | A person you want notes about | pkm-curation | | `Tool` | A tool, app, or service | pkm-curation | ### Link Convention Standard markdown links `[text](relative/path.md)` replace Obsidian `[[wikilinks]]` throughout all skill instructions, reference files, and vault notes. Obsidian renders both syntaxes, so this is backward-compatible. ### Bundle = subdirectory with index.md + log.md - `index.md`: OKF progressive-disclosure listing (no frontmatter, sections with bullet links + descriptions). See OKF §6. - `log.md`: OKF chronological update log (datestamped entries, newest first). See OKF §7. - Reserved filenames apply: `index.md` and `log.md` MUST NOT be used for concept documents. ### Bundle map | Path | bundle? | |------|:-------:| | `sjb-brain/` (root) | ✅ | | `Knowledge/` | ✅ | | `Notes/` + subdirs | ✅ (each subdir is a sub-bundle) | | `Resources/` + subdirs | ✅ (each subdir is a sub-bundle) | | `Profiles/` | ✅ | | `AI Conversation Summaries/` | ✅ | | `Research/<packet>/` | ✅ | | `Projects/<project>/` | ✅ (each project a bundle, migrate flat notes to dirs) | | `Inbox/` | ❌ | | `Dailies/` | ❌ | | `Templates/` | ❌ | | `Clippings/` | ❌ | | `Tasks/`, `tools/`, `wts-services/` | ⏳ deferred | ### Implementation order 1. Update `common/pkm/pkm-curation/references/vault-conventions.md` — single source of truth for the new conventions 2. Seed root bundle (`sjb-brain/index.md`, `sjb-brain/log.md`) 3. Retrofit existing bundles (create index.md/log.md, update frontmatter, convert links) — simplest first 4. Rewrite `research-vault` skill (packet template, bundle structure, frontmatter, links) 5. Rewrite `pkm-curation` skill (frontmatter normalization, link syntax, bundle awareness) 6. Rewrite `conversation-summary` skill (frontmatter, bundle structure, links) 7. Review `crit` skill for any references needing update 8. Reorganize Tasks/tools/wts-services (deferred) ## Testing Decisions These are agent skills — instructions for LLMs, not compiled code. Testing is therefore about conformance of the skill's *output* (notes written into the vault) against the OKF spec. **What makes a good test:** An end-to-end invocation of each skill against a test vault, followed by automated conformance checks on the generated files. **Seams (from highest to lowest):** 1. **End-to-end conformance** — Run each skill against a small test vault, then run an OKF bundle conformance check (§9 of OKF) on the output. This is the highest seam: if the files pass conformance, the skill did its job. 2. **Frontmatter audit** — For each note a skill creates, verify that all required fields (`type`, `id`, `aliases`, `tags`, `area`) are present and non-empty, and that recommended fields (`title`, `description`, `timestamp`) are present when applicable. 3. **Link audit** — Verify that all links use `[...](...)` syntax, not `[[wikilinks]]`, and that links within a bundle use bundle-relative paths (prefixed with `/` for OKF absolute, or `./` for relative). 4. **Bundle structure audit** — For each directory designated as a bundle, verify that `index.md` and `log.md` exist and follow OKF format. **What will be tested:** - `research-vault` — packet creation end-to-end - `pkm-curation` — note curation and atomic note extraction - `conversation-summary` — report/transcript pair creation - `vault-conventions.md` — correctness of the documented schema (manual review) **What will NOT be tested:** - `crit` — no vault I/O - The vault migration itself (one-time process, validated by inspection) **Prior art:** No existing test infrastructure for skills in this repo. Testing will be manual or script-based (shell checks + OKF conformance via custom script). ## Out of Scope - Migration of `Tasks/`, `tools/`, `wts-services/` directories — deferred until their content is reorganized - Automated vault migration tooling — the grilling session produced a phased manual plan, not a migration script - Changes to `AGENTS.md` in the vault root — that file serves a different purpose (agent instructions), not a concept doc - Changes to `.obsidian/` configuration or plugins - CI/CD or automated test runners for skill conformance - Schema registry or central type authority (OKF explicitly does not require one) ## Further Notes - The OKF spec is version 0.1 (draft). We should track upstream changes and adjust as the spec matures. - On case-sensitive filesystems (Linux), `index.md` and `Index.md` are distinct files — the vault has both forms in different places (e.g., research packets used `Index.md`). The migration must handle this carefully to avoid data loss. - The `research-vault` packet template needs the most structural rework: the existing `Index.md` (MOC-style with frontmatter) becomes OKF `index.md` (progressive disclosure, no frontmatter); `Log.md` becomes OKF `log.md` (datestamped entries); all other packet files get concept frontmatter with proper `type` values. - Link migration (wikilinks → markdown links) across ~120 existing vault notes is the bulk of the retrofitting work. Skills should produce correct links going forward; the vault retrofit can be batched.

steve added the ready-for-agent label 2026-07-06 21:23:34 -04:00

steve added in-progress and removed ready-for-agent labels 2026-07-06 21:24:52 -04:00

steve added a new dependency 2026-07-09 11:56:28 -04:00

jones/adherence-ui#19 - When creating a new Patient the patient does not appear on the list, we need to refresh the page to see the new Patient.

steve removed a dependency 2026-07-09 12:04:08 -04:00

jones/adherence-ui#19 - When creating a new Patient the patient does not appear on the list, we need to refresh the page to see the new Patient.

steve added a new dependency 2026-07-09 12:09:39 -04:00

#4 Clarify PKM skill boundaries or make knowledge-gardener a router

steve removed a dependency 2026-07-09 12:13:39 -04:00

#4 Clarify PKM skill boundaries or make knowledge-gardener a router

steve added a new dependency 2026-07-09 12:14:49 -04:00

#4 Clarify PKM skill boundaries or make knowledge-gardener a router