Overview

Archgate is a governance layer for AI-assisted development. It sits between your AI coding agents and your codebase, ensuring that whatever gets generated follows your rules.

The problem

AI coding agents are powerful but ungoverned. When teams adopt tools like Claude Code, Cursor, or Copilot, they hit a tension:

• Developers want speed — AI agents unblock them from boilerplate and repetitive work.
• Organizations need consistency — code must follow architectural standards, security policies, naming conventions, and domain patterns.
• AI agents have no guardrails — without explicit constraints, they produce code that works but does not conform. Every generated file becomes a review burden.

The result: teams either slow down AI adoption (losing productivity) or accept inconsistent code (accumulating debt). Archgate exists to remove that trade-off.

The insight: ADRs as executable governance

Architecture Decision Records (ADRs) are a well-established practice — teams document decisions like “we use this layering” or “API routes must have OpenAPI schemas.” Traditionally these are passive documents that developers read sometimes and follow hopefully.

Archgate makes ADRs active. Each ADR has two expressions:

1. A human-readable document — so developers and AI agents understand the intent, context, and rationale.
2. Machine-checkable rules — lint rules, file-structure assertions, import-boundary checks, config validators — that verify compliance automatically.

When an AI agent writes code in an Archgate-governed project, two things happen: the agent reads the ADR documents as context, shaping what it generates (prevention), and the automated checks validate the output, catching what the agent missed (detection).

This is governed AI development: correctness by construction where possible, correctness by detection everywhere else.

The governance loop

The system runs as a continuous loop with three stages.

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

• Prevention — ADRs are loaded as agent context, so the AI writes compliant code from the start.
• Detection — archgate check runs in the editor, on pre-commit, and in CI: fast, free, deterministic validation. The @reviewer skill adds AI judgment for the calls a linter cannot make.
• Learning — the @lessons-learned skill turns violations and review findings into new ADR rules, which flow back into prevention.

The loop is a ratchet: every mistake becomes a permanent rule. Over time, more governance shifts from expensive AI review to free automated checks — token costs decrease while compliance increases.

Two enforcement layers

Archgate enforces governance in two complementary layers:

Layer	Mechanism	Cost	Speed	Use case
Automated checks	Lint rules, file assertions, import analysis	Free	Milliseconds	The bulk of ADR rules
AI review	Plugin reviews code against ADRs	Tokens	Seconds	Subjective quality, architectural fit

The strategic goal is to maximize the first layer over time, using AI review only for what machines genuinely cannot evaluate.

What drives the loop

The loop describes what happens; the plugins describe who drives it. There are two enforcement modes:

• CI / pre-commit (deterministic, no AI) — archgate check --staged in hooks and archgate check in CI block non-compliant code. This is the hard gate.
• Editor plugin (AI-assisted development) — plugins ship skills (@reviewer, @lessons-learned, @adr-author, @onboard, @cli-reference) and a developer agent that orchestrate the full workflow. MCP tools connect the AI tool to the CLI.

The CLI commands and MCP tools are passive capabilities. The workflow — the ordering, the gates, the roles — lives in the plugin. Without a plugin the tools exist, but nothing tells the AI when and how to use them.

What Archgate is — and is not

Archgate is a governance layer that works with any AI tool, any stack, any CI system, and any team size. The ADR format is stack-agnostic; ADR packs provide stack-specific rules.

Archgate is not a framework (it does not dictate your stack), not a linter (it orchestrates linting as one mechanism among many), and not an AI coding tool (it governs the AI coding tools you already use).

Next steps

Installation Install the Archgate CLI with a one-line script, proto, or npm.

Quick Start Run the full loop end to end: init, check, add a plugin, run the reviewer.

Editor Plugins See which editors are supported and what each plugin adds.

CLI Reference The authoritative reference for every command, the rule API, and the ADR schema.