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:

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.

Step 3: Write the configuration

• Edit the config files that exist; don't replace them. Add rules to the existing ESLint or Stylelint config and keep the team's other settings. If no config exists for a tool, write one and say it's new; don't add a tool the team hasn't chosen without asking.
• Trace every rule. Above each added rule, a comment: // GOV: <rule sentence> — source: CONTRIBUTING.md#naming. In JSON configs that can't carry comments, put the trace in GOVERNANCE.md next to the rule id.
• Real names. The primitive-token pattern, the package name in no-restricted-imports, the paths in CODEOWNERS all come from the repository, not from the example in Step 2.
• Severity from the team's model. First encoding usually ships as warn; Step 5 says when a rule is ready to become error.
• GOVERNANCE.md (in docs/ or beside CONTRIBUTING.md): one table of every rule from Step 1 with its source, its tool and rule id or "manual", who checks it and at which point (PR review, release, quarterly), and the exception route the team stated. Then a "Proposed, not yet policy" list for anything you suggested that no source supports, each with a one-line reason, for the team to accept or delete. An exception process is written only if the team has one; don't invent approval levels.

Step 4: Calibrate against the codebase

Run each tool in report mode against the repository (npx eslint . --format json, npx stylelint "**/*.css" --formatter json, npx depcruise src) and count current violations per added rule. Report the counts. A rule that fires four hundred times on day one ships as warn with a note that it needs a cleanup pass (a token-compliance run gives the list); a rule that fires zero times may be misconfigured, so confirm it fires on a known-bad line before trusting the zero, per the empty-result rule in the output-discipline note. Don't fix violations in this run.

Step 5: Summarise in chat

• Headline: rules encoded (by tool), rules written to GOVERNANCE.md as manual, rules proposed
• Files: every config written or edited, with the rule count added to each
• Calibration: violations per rule today, and which rules are safe to promote to error
• Next: cicd-integration to run these in CI and document branch protection; token-compliance for the cleanup list; decision-record for any rule the team argued about
• Scope: the block from the output-discipline note: sources inspected, sources not reached (wikis, Slack, people), and the note that the encoded set is what was found, not everything the team believes

Quality checks

• Every added lint rule carries a trace comment with a source path or team; no rule exists in the config that isn't in the Step 1 table
• No rule is described as automated unless a tool in the config runs it; process gates live in GOVERNANCE.md with a human checkpoint
• Token prefixes, package names and paths in the config are the repository's, not the examples'
• Existing config files were edited, not overwritten, and the summary says what was added to each
• Every rule was run in report mode and its current violation count is in the summary, with a known-bad probe confirming any zero
• Proposed rules are in their own list with a reason each, and none is in a config file
• The output ends with a Scope block