GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

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

Open
#93 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.