{"row":{"id":"ADR-021","title":"YAML envelope convention: apiVersion + kind + metadata + spec, multi-doc, 9 doc kinds","file":"adr-021-yaml-envelope-convention.md","status":"superseded","date":"2026-04-16","cites":6,"supersedes":[],"superseded_by":["ADR-082"],"layers":["L0","L0.5"],"tags":["schema","yaml","envelope","k8s"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-021: YAML envelope convention","id":"adr-021-yaml-envelope-convention"},{"k":"quote","inline":[{"k":"strong","text":"⚠️ SUPERSEDED 2026-05-25"},{"k":"text","text":" · The K8s envelope decided here\n("},{"k":"code","text":"apiVersion: nika.sh/v1"},{"k":"text","text":" + "},{"k":"code","text":"kind"},{"k":"text","text":" + "},{"k":"code","text":"metadata"},{"k":"text","text":" + "},{"k":"code","text":"spec"},{"k":"text","text":") is "},{"k":"strong","text":"superseded\nby the public `nika-spec`"},{"k":"text","text":", which adopts a "},{"k":"strong","text":"single version marker"},{"k":"text","text":" ·\n"},{"k":"code","text":"nika: v1"},{"k":"text","text":" + "},{"k":"code","text":"workflow: <id>"},{"k":"text","text":" + "},{"k":"code","text":"tasks:"},{"k":"text","text":". The spec explicitly rejects the\n"},{"k":"code","text":"apiVersion:"},{"k":"text","text":"/"},{"k":"code","text":"schema:"},{"k":"text","text":" two-field form as Kubernetes-ceremony a workflow\nfile does not need (cf "},{"k":"code","text":"nika-spec spec/01-envelope.md"},{"k":"text","text":" · \"Why one field,\nnot apiVersion + schema\"). The engine's internal canonical URI stays\n"},{"k":"code","text":"https://nika.sh/spec/v1"},{"k":"text","text":" for RDF/conformance tooling, but the author\nnever types it. Decision below preserved as audit trail per\n"},{"k":"code","text":"cross-source-validation.md"},{"k":"text","text":" §2.7. The "},{"k":"code","text":"kind"},{"k":"text","text":" discriminator + multi-doc\nrationale (9 doc kinds) is the part that survives — only the version-field\nshape changed ("},{"k":"code","text":"apiVersion: nika.sh/v1"},{"k":"text","text":" → "},{"k":"code","text":"nika: v1"},{"k":"text","text":")."}]},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Phase D Round 2c-2e shipped a parser for top-level workflow scalars ("},{"k":"code","text":"name"},{"k":"text","text":",\n"},{"k":"code","text":"description"},{"k":"text","text":", "},{"k":"code","text":"goal"},{"k":"text","text":", "},{"k":"code","text":"provider"},{"k":"text","text":", "},{"k":"code","text":"model"},{"k":"text","text":", "},{"k":"code","text":"schema"},{"k":"text","text":") and "},{"k":"code","text":"tasks:"},{"k":"text","text":" sequence.\nBackground research (4 web-research agents, 2026-04-16) converged unanimously\non adopting the K8s envelope pattern ("},{"k":"code","text":"apiVersion + kind + metadata + spec"},{"k":"text","text":")\nwith multi-document YAML support. Evidence: every workflow DSL with >2 doc\ntypes (Argo, Tekton, Flux, Drone-1.x, Helm) ended up with this envelope after\nflat-form regret migrations."}]},{"k":"p","inline":[{"k":"text","text":"Nika has 9 user-facing doc kinds at v0.90: Workflow, Skill, Agent, Provider,\nMCP, Eval, Recipe, Shield, Lints (+ Memory v0.95, Plugin v0.100 reserved).\nWithout an envelope, every kind reimplements identity + version semantics."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Adopt the K8s envelope as the canonical shape for every Nika user-facing\nstructured config (YAML and TOML)"},{"k":"text","text":":"}]},{"k":"code","lang":"yaml","text":"apiVersion: nika.sh/v1\nkind: Workflow                # closed enum: Workflow|Skill|Agent|Provider|\n                              #              Mcp|Eval|Recipe|Shield|Lints|\n                              #              Memory(reserved)|Plugin(reserved)\nmetadata:\n  name: my-workflow\n  description: ...\n  labels: { ... }             # optional\n  annotations: { ... }        # optional\nspec:\n  defaults: { model: openai/gpt-4o }\n  tasks: [...]                # for kind: Workflow"},{"k":"p","inline":[{"k":"strong","text":"Multi-document YAML"},{"k":"text","text":" (--- separator) supported: one file may declare\nmultiple kinds (Workflow + Skill + Agent), parsed into "},{"k":"code","text":"Vec<RawDocument>"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"strong","text":"Model identifier"},{"k":"text","text":": single string "},{"k":"code","text":"provider/model"},{"k":"text","text":" (LiteLLM format), e.g.\n"},{"k":"code","text":"openai/gpt-4o"},{"k":"text","text":", "},{"k":"code","text":"anthropic/claude-sonnet-4.5"},{"k":"text","text":". Drop separate "},{"k":"code","text":"provider:"},{"k":"text","text":" +\n"},{"k":"code","text":"model:"},{"k":"text","text":" fields."}]},{"k":"p","inline":[{"k":"strong","text":"Drop workflow-level `goal:`"},{"k":"text","text":" — CrewAI agent-specific concept, not a\nworkflow concept (0 of 8 surveyed workflow DSLs have it). If goal-driven\nagentic workflows need it, place in "},{"k":"code","text":"spec.orchestrate.goal:"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"strong","text":"Format support"},{"k":"text","text":":"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"YAML: workflows (DSL, user-authored)"}],[{"k":"text","text":"TOML: catalog data, agent presets, lint rules (config-as-data)"}],[{"k":"text","text":"Markdown + YAML frontmatter: skills/agents (prose-heavy, Cursor/Claude\nconvention)"}]]},{"k":"p","inline":[{"k":"text","text":"All three formats use the same envelope keys (apiVersion + kind + metadata +\nspec)."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ Single envelope shape across 9 doc kinds = LLM-friendly (Nika-brain\ngenerates correct shape on first try)"}],[{"k":"text","text":"✅ Forward-compat: adding a kind (e.g., Memory at v0.95) requires only\nadding a variant to the closed "},{"k":"code","text":"Kind"},{"k":"text","text":" enum"}],[{"k":"text","text":"✅ K8s envelope is in 100% of LLM training data — Nika-brain pattern-matches\nwithout prompting tax"}],[{"k":"text","text":"❌ Diverges from typical \"Rust workspace\" convention (TOML flat) — but\nworkflow engines diverge from compilers (the relevant comparison set)"}],[{"k":"text","text":"❌ Existing nika-schema parser (Round 2c-2e, 38 tests) needs full rewrite\nin Phase D — explicit cost accepted (v0.1, 0 users, break freely)"}],[{"k":"text","text":"⚠️ Hygiene vector 23 (check-workflow-envelope.sh) MUST land in Phase B\nbefore any envelope code is written — guards against regression"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Flat top-level"},{"k":"text","text":" (current Round 2c shape) — dies at ~8 fields per\nGitLab/Drone/Dify post-mortems"}],[{"k":"strong","text":"Hybrid (Dify-style: version + kind + nested app block)"},{"k":"text","text":" — half-step that\nloses metadata uniformity"}],[{"k":"strong","text":"URL-path discrimination (apiVersion: nika.sh/v1/Workflow)"},{"k":"text","text":" — breaks YAML\neditor schema hints"}],[{"k":"strong","text":"Filename convention only"},{"k":"text","text":" — moves truth out of doc, hurts multi-doc"}]]},{"k":"p","inline":[{"k":"text","text":"See "},{"k":"code","text":"~/.claude/.../memory/project_foundation_v081_constellation.md"},{"k":"text","text":" for the\n4-agent research synthesis."}]}]

ADR-021

YAML envelope convention: apiVersion + kind + metadata + spec, multi-doc, 9 doc kinds

superseded · 2026-04-16 · L0 L0.5 · cites 6

Superseded by ADR-082. This decision is kept because its successor cites it.

ADR-021: YAML envelope convention #

⚠️ SUPERSEDED 2026-05-25 · The K8s envelope decided here (apiVersion: nika.sh/v1 + kind + metadata + spec) is superseded by the public `nika-spec`, which adopts a single version marker · nika: v1 + workflow: <id> + tasks:. The spec explicitly rejects the apiVersion:/schema: two-field form as Kubernetes-ceremony a workflow file does not need (cf nika-spec spec/01-envelope.md · "Why one field, not apiVersion + schema"). The engine's internal canonical URI stays https://nika.sh/spec/v1 for RDF/conformance tooling, but the author never types it. Decision below preserved as audit trail per cross-source-validation.md §2.7. The kind discriminator + multi-doc rationale (9 doc kinds) is the part that survives — only the version-field shape changed (apiVersion: nika.sh/v1 → nika: v1).

Context #

Phase D Round 2c-2e shipped a parser for top-level workflow scalars (name, description, goal, provider, model, schema) and tasks: sequence. Background research (4 web-research agents, 2026-04-16) converged unanimously on adopting the K8s envelope pattern (apiVersion + kind + metadata + spec) with multi-document YAML support. Evidence: every workflow DSL with >2 doc types (Argo, Tekton, Flux, Drone-1.x, Helm) ended up with this envelope after flat-form regret migrations.

Nika has 9 user-facing doc kinds at v0.90: Workflow, Skill, Agent, Provider, MCP, Eval, Recipe, Shield, Lints (+ Memory v0.95, Plugin v0.100 reserved). Without an envelope, every kind reimplements identity + version semantics.

Decision #

Adopt the K8s envelope as the canonical shape for every Nika user-facing structured config (YAML and TOML):

yaml

1apiVersion: nika.sh/v12kind: Workflow                # closed enum: Workflow|Skill|Agent|Provider|3                              #              Mcp|Eval|Recipe|Shield|Lints|4                              #              Memory(reserved)|Plugin(reserved)5metadata:6  name: my-workflow7  description: ...8  labels: { ... }             # optional9  annotations: { ... }        # optional10spec:11  defaults: { model: openai/gpt-4o }12  tasks: [...]                # for kind: Workflow

Multi-document YAML (--- separator) supported: one file may declare multiple kinds (Workflow + Skill + Agent), parsed into Vec<RawDocument>.

Model identifier: single string provider/model (LiteLLM format), e.g. openai/gpt-4o, anthropic/claude-sonnet-4.5. Drop separate provider: + model: fields.

Drop workflow-level `goal:` — CrewAI agent-specific concept, not a workflow concept (0 of 8 surveyed workflow DSLs have it). If goal-driven agentic workflows need it, place in spec.orchestrate.goal:.

Format support:

YAML: workflows (DSL, user-authored)
TOML: catalog data, agent presets, lint rules (config-as-data)
Markdown + YAML frontmatter: skills/agents (prose-heavy, Cursor/Claude convention)

All three formats use the same envelope keys (apiVersion + kind + metadata + spec).

Consequences #

✅ Single envelope shape across 9 doc kinds = LLM-friendly (Nika-brain generates correct shape on first try)
✅ Forward-compat: adding a kind (e.g., Memory at v0.95) requires only adding a variant to the closed Kind enum
✅ K8s envelope is in 100% of LLM training data — Nika-brain pattern-matches without prompting tax
❌ Diverges from typical "Rust workspace" convention (TOML flat) — but workflow engines diverge from compilers (the relevant comparison set)
❌ Existing nika-schema parser (Round 2c-2e, 38 tests) needs full rewrite in Phase D — explicit cost accepted (v0.1, 0 users, break freely)
⚠️ Hygiene vector 23 (check-workflow-envelope.sh) MUST land in Phase B before any envelope code is written — guards against regression

Alternatives considered #

Flat top-level (current Round 2c shape) — dies at ~8 fields per GitLab/Drone/Dify post-mortems
Hybrid (Dify-style: version + kind + nested app block) — half-step that loses metadata uniformity
URL-path discrimination (apiVersion: nika.sh/v1/Workflow) — breaks YAML editor schema hints
Filename convention only — moves truth out of doc, hurts multi-doc

See ~/.claude/.../memory/project_foundation_v081_constellation.md for the 4-agent research synthesis.

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo