Repository Governance

repository-governance

The repository is the control plane. Freeze the architecture spine; let feature architecture evolve under usage pressure. Prefer narrow capability with strong boundaries. Architecture reduces the blast radius of future change — it does not predict or eliminate future change.

Highest-priority rule: existing governance takes precedence

When the repository already has an explicit governance/control system, this skill is a consumer of that system, not a parallel source of project policy.

1. Run control-plane discovery (below) before choosing a branch.
2. Treat repository-specific architecture rules, invariant registries, ADRs, tests, schemas, ownership rules, and enforcement scripts as authoritative project policy.
3. Use this skill to navigate, apply, and report against those mechanisms.
4. Add or replace governance infrastructure only in the bootstrap branch, and only when the user explicitly asked for it and a concrete gap is observed.
5. Reuse the repository's existing invariant registry, ADR system, architecture checker, change-control template, golden test, or documentation hierarchy; duplicate none of them.
6. If repository policy conflicts with this skill, preserve repository-specific policy unless a higher-level instruction says otherwise, and report the tension.

Branch state machine

repository-governance
        │
        ▼
Discover repository control plane
        │
        ├── governance exists ────────────▶ GOVERN CHANGE (consumer mode)
        │
        └── governance materially absent ──▶ do NOT bootstrap automatically
                │
                ▼
        bootstrap only if the user explicitly requested it

• Govern a change — planning, implementing, refactoring, or reviewing a substantial repository change. Follow GOVERN-CHANGE.md.
• Bootstrap / harden governance — only when the user's task explicitly asks to create, bootstrap, audit, harden, redesign, or modify repository governance itself. Follow BOOTSTRAP-GOVERNANCE.md.

This skill governs; the calling workflow still does the work. Apply the chosen branch alongside it and return with its report.

Control-plane discovery

Run this before applying either branch. Discover progressively; do not read documents broadly.

1. Start from always-loaded agent guidance (AGENTS.md, CLAUDE.md) and the repository entry points those files name. Read only what is authoritative for this change.
2. Follow pointers one hop at a time. Mark each source normative ("must be true") or descriptive ("currently implemented this way"). A descriptive source never overrides a normative one.
3. Inspect actual code, config, and tests for facts they encode directly (package manifests, schemas, CI gates, boundary checks, test names). Treat these as authoritative where they encode reality; do not copy them into prose.
4. When sources conflict, flag the conflict and name the narrower authoritative source. Never silently choose whichever was read last.

Completion criterion: you can name, each with a repository pointer: the architecture spine as this repository defines it (or state that it is undefined), the ownership boundaries relevant to the change, the affected invariants and their executable checks, and the source of truth for any new fact this change introduces or depends on.

Architecture spine vs feature architecture

The spine is the set of decisions whose mistakes contaminate many future changes. Feature architecture implements one capability within those rules.

Test: does this decision change the rules by which many future changes will be made, or implement one capability inside existing rules?

The repository determines which concerns are spine. When it names them, use its list. When it does not, infer them from what executable checks, ADRs, and CI gates actually protect, and ask the human before freezing new spine concerns. Example spine concerns some repositories protect: authority/source of truth, canonical domain contracts, identity, trust/security boundaries, dependency ownership, deterministic vs probabilistic/LLM responsibility, persistence ownership, provenance/versioning, failure semantics. This is an example set, not a universal list.

Six control dimensions

Govern every change through these.

1. Locality — a conceptual change has a bounded blast radius.
2. Invariants — critical truths are machine-checkable; prose is not enforcement.
3. Traceability — new facts, decisions, derived data, and user-visible conclusions have authority and provenance where the repository requires it.
4. Replaceability — important boundaries do not bind generic downstream logic to one concrete provider or implementation.
5. Recoverability — incorrect changes fail close to the violated boundary and reproduce deterministically where practical.
6. Semantic load — the architectural concepts a maintainer must remember are scarce.

Abstraction admission gate

A new architecture-level abstraction requires admission. Answer all four:

1. What concrete failure or ambiguity does this abstraction prevent?
2. What independent axis of change does it isolate?
3. Why is the nearest existing abstraction not the correct owner?
4. What would concretely become worse if this responsibility were folded into that abstraction?

Generic claims — cleaner architecture, separation of concerns, extensibility, scalability, future-proofing — do not pass. If any answer lacks a concrete mechanism, fold the responsibility into the nearest existing abstraction.