FR-033 — Provider definitions as declarative data + metamodel docs for LLMs #23

Status: designed. Design: docs/superpowers/specs/2026-06-13-metamodel-self-description-design.md.

Problem

The declarative metamodel definition is hand-coded five times (per-port field-schema.* etc.) and kept in sync by registry-conformance — duplication metaobjects exists to eliminate. As a result, type/subtype purpose, attribute meaning, and rules of use are undocumented and inconsistent, so an LLM authoring metadata has no accurate, consistent source for "what is field.currency for, what attrs does it take, what are the rules."

Decision

A provider's declarative definition becomes JSON data the provider reads to register itself — vocabulary + attr constraints + descriptions + rule prose + examples — single-sourced.

• Data/code boundary: the file owns the declarative definition + rule prose; imperative validation and codegen stay per-port code (no rules DSL — the project explicitly avoids one).
• File layering: global/core files in the centralized specs area (spec/metamodel/<provider>.json, neutral, identical cross-port); language-specific overlays in each port's local repo; a provider reads ≥1 file, overlay/last-writer-wins merge (the loader's existing semantics).
• One artifact, two consumers: each port dumps "registry-with-descriptions" (built from its embedded files) → it is both the registry-conformance gate target AND the doc-gen input.
• Docs: one neutral Tier-2 engine renders tiered markdown — metamodel/INDEX.md (one-liners + links) + metamodel/providers/<id>.md (full detail) — wired into the metaobjects-authoring skill (index always-on, provider pages on-demand).
• Consistency by construction (single source), accurate-by-construction docs (derived from the live registry), embed-at-build (AOT-safe, ADR-0001), strict-provenance preserved + every entry must be described (ADR-0023).

Sequencing

Stand up the file-driven mechanism on one core provider (TS reference) → prove the gate + doc-gen → convert remaining core providers → fan out the read-the-file mechanism to Java/C#/Python/Kotlin. Gate green at each step.

🤖 Generated with Claude Code