/governance-encoder

name: governance-encoder
description: "Convert governance policies into machine-executable JSON constraint files that AI agents and CI pipelines validate against automatically. This produces rule engine files in .ai/governance/, NOT narrative decision records or documentation. Trigger when someone says: encode governance rules, governance as code, automate governance, rule engine, machine-executable constraints, enforce rules automatically, constraint definitions, or anything about converting human-readable policies into structured rules that tools check programmatically. Do NOT trigger for documenting why a decision was made or recording the reasoning behind a choice — use decision-record for those."
references:
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/human-oversight-framework.md
  - ../../knowledge-notes/agent-orchestration-guide.md

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

Auto-pull integrations

If integrations are configured in `.ds-ops-config.yml`, pull data automatically:

**GitHub** (`integrations.github.enabled: true`):

• Pull CONTRIBUTING.md, PR templates, and issue templates for existing governance documentation
• Scan ESLint/Stylelint configs for existing code-level rules that overlap with governance
• Pull branch protection rules and CI configuration for release governance context

**Figma MCP** (`integrations.figma.enabled: true`):

• Read library publishing rules and component organisation structure
• Extract naming patterns from existing component names
• Identify variant naming conventions

If an integration fails, log it and proceed with manual input.

---

Step 1: Inventory existing governance rules

Before encoding, catalogue what governance rules already exist and where they live.

Scan for governance sources:

• Contribution guidelines (CONTRIBUTING.md, wiki pages)
• Code style guides (ESLint configs, Prettier configs, Stylelint configs)
• Design guidelines (Figma file organisation rules, naming conventions)
• Release processes (CHANGELOG conventions, versioning rules)
• Token usage rules (documentation, code comments, linter configs)
• PR review checklists
• Decision records

For each rule found, classify:

| Rule | Source | Currently enforced by | Machine-encodable? | |---|---|---|---| | Component names must be PascalCase | CONTRIBUTING.md | PR review | Yes — regex pattern | | Props must have TypeScript types | ESLint config | CI pipeline | Yes — already encoded | | New components need design review | Wiki | Manual process | Partially — gate check | | Tokens must use semantic tier | Style guide | PR review | Yes — import pattern |

Ask for or confirm:

• Are there governance rules that exist only in team knowledge (not documented anywhere)?
• Are there rules that are documented but not enforced (aspirational rules)?
• Are there rules that are currently enforced by linters that should be promoted to governance rules?
• What severity model does the team use? (Default: error blocks merge, warning flags for review, info provides guidance)

---

Step 2: Define the rule schema

Every governance rule follows the same schema, regardless of what it governs:

{
  "id": "GOV-001",
  "category": "naming",
  "rule": "component_export_name",
  "description": "Component export names must be PascalCase",
  "intent": "Consistent naming enables predictable imports and tooling integration",
  "scope": {
    "applies_to": "component_files",
    "file_pattern": "src/components/**/*.{tsx,vue,svelte}"
  },
  "constraint": {
    "type": "pattern",
    "pattern": "^[A-Z][a-zA-Z]+$",
    "target": "default_expo