governance-encoder

Governance encoder

A skill for converting design system governance policies — the rules about how the system should be used, contributed to, and evolved — from human-readable documentation into machine-executable constraint definitions that AI agents validate against in real time.

Context

Most design system governance lives in documents that humans read and (sometimes) follow. Contribution guidelines in a wiki. Naming conventions in a README. Token usage rules in a Slack thread from eighteen months ago. These rules are enforced by review — a senior team member spots a violation during a PR review or a design crit and asks for a correction.

This enforcement model breaks down at scale, and it breaks down entirely with AI agents. An agent generating a component cannot read a wiki page and decide to follow the naming convention. It cannot recall a Slack conversation about token usage. It needs rules expressed as structured data with explicit conditions, constraints, and consequences that it can evaluate programmatically.

Governance encoding is the process of taking every governance rule that currently lives in a human-readable document and expressing it as a machine-checkable constraint. The output is not a better document — it is a rule engine that agents (and CI pipelines and linters) consume directly.

The distinction between governance documentation and governance encoding:

• Documentation says: "Components should follow our naming convention."
• Encoding says: { "rule": "component_naming", "pattern": "^[A-Z][a-zA-Z]+$", "scope": "component_export_name", "severity": "error", "message": "Component names must be PascalCase with no special characters" }

Both are necessary. Documentation explains the intent. Encoding enforces the constraint.

---

Configuration

Before producing output, check for a .ds-ops-config.yml file in the project root. If present, load:

• governance.rule_format — output format preference (JSON or YAML, default: JSON)
• governance.severity_model — custom severity levels (default: error/warning/info)
• governance.categories — override default rule categories
• system.framework — framework-specific rules (React, Vue, Svelte)
• system.tokens — identifies token files for token governance rules
• integrations.* — enables auto-pull for existing governance context