# YAML as CSS

June 9, 2026. The day the harness found its metaphor.

## The Insight

The problem was configuration sprawl. The system had grown, over fourteen months, into a collection of registries — files that defined what models to use, what voices to use, what tools were available, what agents existed, what permissions they held. Each registry was a YAML file. Each YAML file was read by code at runtime. And the YAML files were scattered across the codebase, referenced by different packages, maintained by different sessions, updated independently, drifting slowly out of sync.

The problem was old. It was the same problem that CSS solves in web design: if you hard-code styling in every component, you get inconsistency. Change the font in one place, forget it in another, and the interface drifts. The CSS solution is separation: define the styles once, in one place, and let the components reference them. Change the style in the stylesheet, and it streams through every component automatically.

On June 9, I realized the registries were styles. The model definitions were styles. The voice profiles were styles. The agent definitions were styles. The permission policies were styles. Every YAML file in the system was a style sheet for a different dimension of the harness — the layer that connected the models to the tools to the agents to the user. And the harness, like a web interface, needed a single source of truth for each dimension, so that a change in one place streamed through the whole system.

I wrote it in the consilience production program:

Every domain gets exactly one YAML source of truth, plus codegen, plus a CI drift check, plus a grep audit. YAML is to roles and models what CSS is to the UI: change once, it streams through the piping.

And in the originating plan:

One source of truth. The registry is the only place model names live. Every file consumes roles, never model strings. The YAML is treated like the design system's CSS for models — extend it, never bypass it.

## The Method

The method was four layers, each enforcing the single-source principle from a different angle.

The source of truth: one YAML file per domain. sovereign-models.yaml was the only place model names lived. family.yaml was the only place the family roster lived. bodies.yaml was the only place model bodies were defined. council-invocation.yaml was the only place the council seats were configured. One file, one domain, one truth.

The codegen: TypeScript types and constants generated from the YAML files. The code did not read the YAML at runtime. The code read the generated types. This meant that if you changed a model name in the YAML, the codegen would update the TypeScript, and every file that consumed the type would see the change at compile time. A typo in a model name was a compile error, not a runtime bug.

The drift check: a CI step that compared the YAML files to the generated TypeScript. If someone edited the TypeScript directly — bypassing the YAML, the way a developer might hard-code a style instead of using the stylesheet — the drift check would fail. The build would break. The developer would be forced to change the YAML and regenerate.

The grep audit: a script that searched the codebase for hard-coded model names, hard-coded role strings, hard-coded anything that should have come from a registry. If the grep found a model name in a .ts file that was not the codegen output, the audit flagged it. The model name belonged in the YAML. The code consumed roles. Always roles, never strings.

This was the generator principle applied to configuration. Small, perfectly-made components — the YAML files — arranged with care, each one the single source of truth for its domain, each one streaming its changes through the codegen and the drift check and the grep audit into every file that depended on it. One change, fully propagated. One source, fully enforced.

The insight connected the design system to the harness system. The same principle that made the visual interface consistent — one stylesheet, many components, change once and it propagates — made the agent system consistent. The models were styles. The roles were styles. The permissions were styles. The harness was a rendering engine for agent configurations, and the YAML files were its stylesheets.

This was the moment the system became cohesive. Before YAML-as-CSS, the configuration was a collection of files that happened to work together. After YAML-as-CSS, the configuration was an architecture — a principled, enforced, audited system in which every dimension of the harness had exactly one source of truth, and every change propagated fully, and every violation was caught.

The generator runs on principles like this. Simple rules, enforced consistently, producing a system that is more durable than the sum of its parts. CSS made the web interface maintainable. YAML-as-CSS made the agent system maintainable. And maintainability — the quality of being understandable and changeable by one person, over years — was the quality the generator demanded.

The YAML-as-CSS insight was formalized on 2026-06-09 in the consilience-production-program handoff. The originating plan (sovereignchatspeed+identity+yaml-as-css-for-models) contains the exact formulation. The four-layer method (source of truth, codegen, drift check, grep audit) is documented in the handoff and implemented across the sovereign_broker registries. The principle connects directly to the design system's CSS variable architecture, where tokens flow from packages/kaos-sovereign/styles into components at runtime.