GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: Layer field (concept, analysis, synthesis) as a mandatory OKF convention
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## 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:
```yaml
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)
Contributor guide
Assessment
This issue has not been assessed yet.