The Governance Loop

AI coding agents are fast but ungoverned. Without explicit constraints, they produce code that works but does not conform to your architecture, security policies, or conventions — turning every generated file into a review burden. The governance loop is Archgate’s answer: a continuous cycle that makes correctness happen by construction where possible, and by detection everywhere else.

Prevention

ADRs encode architectural decisions as executable rules that guide humans and AI agents before code is written.

→

Detection

Rules run in the editor, on pre-commit, and in CI — surfacing violations the moment they appear.

→

Learning

Lessons from reviews and incidents are codified back into ADRs, closing the loop and hardening the system.

↻ continuous

The three movements

The loop has three movements. Each one catches what the previous one missed, and the last one feeds back into the first — so the system gets stronger over time rather than drifting.

Prevention

Architecture Decision Records (ADRs) encode your team’s decisions as durable, versioned documents — and, where the rule is mechanically verifiable, as executable rules. Before an AI agent writes a line of code, it reads the applicable ADRs as context. The Decision and Do’s and Don’ts sections shape what the agent generates, so a large share of compliance is achieved before the first keystroke. This is correctness by construction.

The same documents serve humans. An ADR explains why a decision was made and what trade-offs it carries, so prevention is not a black box — it is a shared, auditable record of intent.

Detection

Prevention is never perfect. The detection layer validates the output: the rules attached to each ADR run automatically and report violations with file paths and line numbers. Detection runs in three places:

• In the editor, after the AI agent makes a change, via the editor plugins.
• On pre-commit, as a fast local gate before code is staged.
• In CI, as the hard gate that blocks non-conforming code from merging.

Detection is deterministic, free, and runs in milliseconds. It catches roughly 70–80% of ADR rules without spending a single token. For the subjective remainder — architectural fit, judgment calls a linter cannot make — the reviewer skill applies AI review against the same ADRs.

Learning

Every violation that detection catches — and every issue a human reviewer flags — is a signal that the governance base has a gap. The lessons-learned skill reads the session, identifies the pattern, and proposes a new ADR or an extension to an existing one (always delegating the actual writing to the adr-author skill).

The new rule flows back into prevention. The loop closes.

A ratchet, not a treadmill

The system is a ratchet: every mistake becomes a permanent rule. Over time, more governance shifts from expensive AI review (detection’s slow path) to free, deterministic automated checks. Token costs go down while compliance goes up — the opposite of the usual quality/cost trade-off.

Two enforcement layers

Underneath the loop sit two distinct enforcement mechanisms. They differ in cost, speed, and what they can evaluate:

Layer	Mechanism	Cost	Speed	Best for
Automated checks	Lint rules, file assertions, import analysis	Free	Milliseconds	The 70–80% of rules a machine can verify
AI review	The reviewer skill checks code against ADRs	Tokens	Seconds	Subjective quality, architectural fit

The strategic goal is to maximize the first layer over time, reserving AI review for what machines genuinely cannot evaluate. The learning movement is what makes that shift happen — it continuously converts judgment calls into deterministic rules.

Two modes drive the loop

The loop describes what happens; two operating modes describe who drives it.

1. Deterministic mode (CI and pre-commit). No AI involved. archgate check runs in pre-commit hooks and CI pipelines and blocks non-compliant code. This is the hard gate — the same check runs identically on every machine and in every pipeline.

2. AI-assisted mode (editor plugins). The editor plugins wire the loop into your AI coding agent. The developer agent orchestrates the workflow — read ADRs, write code, validate, capture — invoking the skills at each step.

The critical insight: the CLI commands and the plugin’s tools are passive capabilities. The workflow — the ordering, the gates, the roles — lives in the plugin’s agent and skills. The CLI runs the deterministic checks anywhere, fully offline; the plugins add the AI-assisted half of the loop on top.

The CLI is the engine

Archgate’s deterministic enforcement is implemented entirely in the archgate CLI. The command syntax, flags, JSON output, and rule API are documented authoritatively at cli.archgate.dev — this site explains the concepts; the CLI docs are the reference.

Where to go next

ADRs The documents and rules that power prevention.

Rules The executable side of an ADR that powers detection.

Skills How the five skills orchestrate the loop.

Plugins How editors plug the loop into your AI agent.