convention-governance

Deterministic governance engine for coding agent convention files. Validates convention changes against rules before they reach origin/main.

Quick Start

# Install globally
npm install -g convention-governance

# Initialize in your repo (scans for coding agents, enforces one scheme)
cd your-project
convention-governance init

# Validate convention changes on a branch
convention-governance validate --base-ref main --format table

What It Does

When multiple developers use different coding agents (Cursor, Claude Code, Copilot, Codex, Gemini, Windsurf, Amp) on the same repo, their convention files can conflict. This engine:

1. Detects which coding agents the team uses (by scanning convention files)
2. Enforces a single primary convention scheme (AGENTS.md for mixed teams, native scheme for single-agent teams)
3. Validates convention file changes against 4 built-in rules
4. Reports findings as a PR comment via GitHub Action

Built-in Rules

| Rule | What it checks | Severity | | ---------------------- | --------------------------------------------------------- | -------- | | format-valid | File is parseable for its scheme (frontmatter, structure) | gate | | syntax-integrity | Valid frontmatter, balanced markdown headers | gate | | convention-inventory | Primary convention file exists, shim files correct | gate | | duplicate-heading | No duplicate section headings across files | advisory |

CLI Commands

convention-governance init [--override-primary <schemeId>]
convention-governance validate --base-ref <ref> [--config <path>] [--format json|table|markdown]

Exit Codes

| Code | Meaning | | ---- | ----------------------------------------- | | 0 | Passed — no gate violations | | 1 | Blocked — gate violations found | | 2 | Engine error — structured error in output |

Supported Agents

agents-md, Cursor, Claude Code, GitHub Copilot, Codex, Gemini, Windsurf, Amp. New agents can be added via scheme definition files (zero code changes for markdown/mdc/json formats).

License

MIT