Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): make all starter-pack templates OKF-conformant (#2011)

tim-inkeep72d9c5702f85
diff --git a/.changeset/okf-conformant-starter-templates.md b/.changeset/okf-conformant-starter-templates.md
new file mode 100644
index 000000000..01cbe2dc4
--- /dev/null
+++ b/.changeset/okf-conformant-starter-templates.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Every `ok seed` starter pack now stamps a semantic `type` into the frontmatter of the documents its templates create, so a project scaffolded from any pack is conformant with Google's Open Knowledge Format (OKF v0.1) from the first document. The `knowledge-base`, `software-lifecycle`, `plain-notes`, and `writing-pipeline` packs gain context-appropriate types (for example `source`, `proposal`, `note`, `idea`); the `worldbuilding` and `entity-vault` packs already carried them. A conformance test now guards every pack's templates against the OKF non-empty-`type` rule.
diff --git a/packages/server/src/seed/okf-conformance.test.ts b/packages/server/src/seed/okf-conformance.test.ts
index b3587af68..c9ef02fd8 100644
--- a/packages/server/src/seed/okf-conformance.test.ts
+++ b/packages/server/src/seed/okf-conformance.test.ts
@@ -8,6 +8,7 @@ import {
stripFrontmatter,
unwrapFrontmatterFences,
} from '@inkeep/open-knowledge-core';
+import { parse as parseYaml } from 'yaml';
import { applySubstitution } from '../content/substitution.ts';
import { applySeed } from './apply.ts';
import { planSeed } from './plan.ts';
@@ -202,3 +203,41 @@ describe('okf pack — OKF §9 conformance by construction', () => {
}
});
});
+
+describe('all starter packs — OKF §9 rule 2 (every template instantiates a typed doc)', () => {
+ test('every template in every pack carries a non-empty type in its instantiated (block-2) frontmatter', () => {
+ const packs = Object.values(STARTER_PACKS);
+ expect(packs.length).toBeGreaterThanOrEqual(7);
+
+ for (const pack of packs) {
+ const templates = Object.entries(pack.templates);
+ expect(templates.length, `${pack.id}: pack defines no templates`).toBeGreaterThan(0);
+
+ for (const [name, body] of templates) {
+ const relPath = `${pack.id}/.ok/templates/${name}.md`;
+ const yaml = consumerFrontmatterYaml(relPath, body);
+ expect(
+ yaml,
+ `${pack.id}/${name}: rule 1 — no parseable instantiated frontmatter`,
+ ).not.toBeNull();
+
+ let map: unknown;
+ try {
+ map = parseYaml(yaml ?? '');
+ } catch (err) {
+ throw new Error(`${pack.id}/${name}: rule 1 — frontmatter is not valid YAML: ${err}`);
+ }
+ expect(
+ map !== null && typeof map === 'object',
+ `${pack.id}/${name}: rule 1 — frontmatter did not parse to a map`,
+ ).toBe(true);
+
+ const type = (map as Record<string, unknown>).type;
+ expect(
+ typeof type === 'string' && type.trim().length > 0,
+ `${pack.id}/${name}: rule 2 — \`type\` must be a non-empty string, got ${JSON.stringify(type)}`,
+ ).toBe(true);
+ }
+ }
+ });
+});
diff --git a/packages/server/src/seed/starter.ts b/packages/server/src/seed/starter.ts
index dfcabf502..a72a66e24 100644
--- a/packages/server/src/seed/starter.ts
+++ b/packages/server/src/seed/starter.ts
@@ -61,6 +61,7 @@ title: External Source
description: Capture a URL or article text verbatim as raw reference material. For binary files (PDFs, images, audio), use the \`ingest\` tool instead — this \`clip\` template is for text sources only.
---
---
+type: source
source_url:
date_fetched: {{date}}
preservation: text-extracted
@@ -78,6 +79,7 @@ title: Research Log
description: Provisional analysis synthesizing external sources. Every factual claim cites a doc in external-sources/. Promoted to articles/ via consolidate once findings are stable.
---
---
+type: research-note
status: provisional
sources: []
created: {{date}}
@@ -98,6 +100,7 @@ title: Canonical Article
description: Canonical knowledge committed after a team decision. Carries status:canonical plus a supersedes chain tying back to the research/ docs it replaces. Source-of-truth for the domain.
---
---
+type: article
status: canonical
supersedes: []
authored: {{date}}
@@ -174,6 +177,7 @@ title: Proposal Title
description: One-line summary of the proposal.
---
---
+type: proposal
status: draft
authors: [{{user}}]
created: {{date}}
@@ -195,6 +199,7 @@ title: Decision Title
description: One-line decision summary.
---
---
+type: decision
status: proposed
date: {{date}}
deciders: [{{user}}]
@@ -213,6 +218,7 @@ title: Spec Title
description: One-line description of what's being built.
---
---
+type: spec
status: draft
owner: {{user}}
target_release:
@@ -236,6 +242,7 @@ title: 'Plan: <Spec Title>'
description: Implementation plan derived from the parent spec. Pairs with spec.md and tasks.md (github/spec-kit triple shape).
---
---
+type: spec-plan
parent_spec:
created: {{date}}
author: {{user}}
@@ -257,6 +264,7 @@ title: 'Tasks: <Spec Title>'
description: Task checklist for the parent spec. Pairs with spec.md and plan.md (github/spec-kit triple shape).
---
---
+type: spec-tasks
parent_spec:
created: {{date}}
author: {{user}}
@@ -278,6 +286,7 @@ title: '<Topic>: <Action>'
description: One-line summary of what the reader will accomplish.
---
---
+type: guide
category: how-to
last_verified: {{date}}
tags: [guide]
@@ -296,6 +305,7 @@ title: 'Onboarding: <Audience>'
description: First-N-days setup path for <audience> (e.g. new engineer, new contributor, new oncall).
---
---
+type: guide
category: onboarding
audience:
last_verified: {{date}}
@@ -319,6 +329,7 @@ title: '<Service>: <Symptom>'
description: Oncall procedure for diagnosing and remediating <symptom> in <service>.
---
---
+type: guide
category: runbook
service:
severity:
@@ -341,6 +352,7 @@ title: 'Incident: <short name>'
description: Blameless postmortem for <incident>.
---
---
+type: postmortem
severity:
duration:
services: []
@@ -387,6 +399,7 @@ title: Note title
description: One-line summary.
---
---
+type: note
created: {{date}}
author: {{user}}
tags: []
@@ -397,6 +410,7 @@ title: Daily entry
description: Daily journal entry.
---
---
+type: daily-note
title: {{date}}
date: {{date}}
author: {{user}}
@@ -707,6 +721,7 @@ title: Idea title
description: One-line hook.
---
---
+type: idea
captured_at: {{date}}
hook:
tags: [idea]
@@ -719,6 +734,7 @@ title: Draft title
description: What's this piece about?
---
---
+type: draft
status: drafting
target_form:
target_words:
@@ -734,6 +750,7 @@ title: Published title
description: One-line summary.
---
---
+type: publication
status: published
published_at:
canonical_url: