Proposal: Layer field (concept, analysis, synthesis) as a mandatory OKF convention

[magnus919]

Summary

Adopt a layer frontmatter field as a required convention for OKF concept documents, with recommended values of concept, analysis, or synthesis. This enables multi-agent routing by depth rather than type — a PM agent reads synthesis files, a domain expert reads analysis files, a validator reads concept/dossier files — without the agent loading and parsing every file to determine its role.

Motivation

OKF currently treats all concepts as peers. A type: Metric document and a type: Playbook document share the same structural level. An agent looking for strategic guidance has to wade through table schemas to find the playbook it needs. There is no way to distinguish "this file synthesizes other files" from "this file is a primary reference concept."

Proposal

Add to the recommended frontmatter fields:

layer: concept | analysis | synthesis   # Optional, recommended

Semantics:

Value	What it contains	Typical consumer
concept	A primary knowledge unit — table schema, metric definition, API reference (the current default for all OKF concepts)	Any agent that needs reference knowledge
analysis	A synthesis of multiple concepts into findings or evaluation — competitive analysis, feasibility assessment, dimensional analysis	Domain specialists, analyst agents
synthesis	A summary of multiple analyses into strategic implications or recommendations	PM agents, executives, quick scanners

Producers SHOULD adopt this as a mandatory internal convention. Consumers that do not understand the layer field treat everything as concept (the default). Consumers that do understand it route differently by layer.

Relationship to Spec

This is a backward-compatible addition to the recommended frontmatter fields. OKF v0.1 already permits arbitrary additional keys — consumers MUST tolerate unknown fields. A bundle without layer annotations remains valid OKF, but surrenders the multi-agent routing efficiency that the annotation enables.

Prior Art

The artifact-pyramids agent skill (github.com/groktopus/artifact-pyramids) has used mandatory layer separation in production across specialist agent pipelines. The three-layer model (L1 summary/synthesis, L2 analysis, L3 dossiers/concepts) allows an orchestrator to guarantee that each agent profile only loads files at the depth relevant to its role — not a search optimization, but an architectural guarantee.

Filed by Jasper (AI agent on behalf of Magnus Hedemark)