/governance-encoder

name: governance-encoder
description: "Turn written governance rules into enforcement that runs: ESLint, Stylelint, dependency-cruiser and CODEOWNERS config traced to sources, plus GOVERNANCE.md for rules with no executable form. Triggers: governance as code, enforce our rules, lint our rules. Pipeline files: cicd-integration."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(npx eslint:*), Bash(npx stylelint:*), Bash(npx depcruise:*)
references:
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/output-discipline.md

Governance encoder

A skill for turning the governance rules a team has written down into enforcement that actually runs: linter rules, dependency boundaries, code ownership and CI checks, each traced to the document it came from. Rules with no executable form are written to a short governance page that says who checks them and when, so nothing is presented as automated when it isn't.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

Most design system governance lives in documents: contribution guidelines in a wiki, naming conventions in a README, token rules in a Slack thread from a year ago. They are enforced by review, when a senior reviewer happens to notice. That model breaks at scale, and it breaks completely for coding agents, which never read the wiki.

The tools that enforce rules already exist. ESLint has a naming-convention rule. Stylelint can forbid raw values in colour properties. dependency-cruiser can stop an atom importing an organism. CODEOWNERS can require the system team's review on token files. A design system's governance-as-code is not a new rule engine; it is those tools, configured to the team's rules, with each rule pointing back at the sentence that justifies it. This skill writes that configuration. An earlier version wrote JSON rules that nothing executed and called them "enforced automatically"; that is exactly the gap this version closes.

Boundaries

This skill encodes rules that exist. It doesn't decide what the rules should be (`decision-record` records that), write the CI workflow that runs the linters (`cicd-integration`), or audit compliance (`token-compliance`, `naming-audit`, `component-api-validator` do that). If the team has no written rules and can't state any, there is nothing to encode; say so and suggest `contribution-workflow`.

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`). This skill reads:

• `system.framework`, `system.styling`, `system.component_paths`, `system.tokens`
• `governance.severity_model` — how the team maps rule weight to linter levels (default: block-on-merge rules are `error`, review-prompting rules are `warn`)
• `governance.categories` — which rule categories to look for (default: all below)

Step 1: Inventory the rules and the enforcement that already exists

Read before asking. Sources, in order:

• `CONTRIBUTING.md`, PR and issue templates, review checklists
• READMEs in the token and component directories, a style guide, decision records
• Existing lint config: `eslint.config.*` or `.eslintrc*`, `.stylelintrc*`, `.dependency-cruiser.*`, `CODEOWNERS`, `commitlint`, Changesets config
• `package.json` scripts and the CI workflow, for what already runs

For each rule found, one row:

| Rule (one sentence) | Source (path or URL) | Enforced today by | Executable form | |---|---|---|---| | Component export names are PascalCase | `CONTRIBUTING.md#naming` | PR review | ESLint `@typescript-eslint/naming-convention` | | Component styles use semantic tokens, never primitives | `tokens/README.md` | nobody | Stylelint `declaration-property-value-disallowed-list` | | Token file changes need the system team's review | `CONTRIBUTING.md#tokens` | habit | `CODEOWNERS` | | New components need a design review before merge | wiki | nobody | none: GOVERNANCE.md |

Then ask only for what the files don't say: rules that live in the team's heads (each becomes a row with source `team`), rules that are written but nobody wants enforced, and how strict the team wants to be at first.

Step 2: Map each rule to a tool

Use the executable form that already exists in the ecosystem. The table is the menu; pick per rule, per stack.

| Rule kind | Tool and rule | Notes | |---|---|---| | Component or file naming | ESLint `@typescript-eslint/naming-convention`; `unicorn/filename-case` for files | Vue: `vue/component-definition-name-casing` | | Boolean prop prefixes, handler names | `@typescript-eslint/naming-convention` with a `typeProperty` selector and `prefix` | Partial: it can't tell a boolean prop from a boolean local. Mark it `warn` and say so | | No raw colour, spacing or type values in styles | Stylelint `stylelint-declaration-strict-value` on the token-backed properties | Tailwind: `eslint-plugin-tailwindcss` `no-arbitrary-value` | | No primitive tokens in component styles | Stylelint `declaration-property-value-disallowed-list` matching the primitive prefix (`/var\(--color-(blue|gray|red)-/`) | Take the prefix from the real token names | | No local re-implementations or deep imports | ESLint `no-restricted-imports` (block `@system/*/src/*`, block copied-in paths) | | | Layer boundaries (atoms don't import organisms) | `dependency-cruiser` rules,