Archgate

How it works

Archgate has two layers that work together:

1. ADRs as documents — Markdown files with YAML frontmatter that describe architectural decisions in plain language. Humans read them. AI agents read them. Everyone stays aligned.

2. ADRs as rules — Companion .rules.ts files with automated checks written in TypeScript. They run against your codebase and report violations with file paths and line numbers.

ADRs that enforce themselves

Write a decision in Markdown. Add rules in TypeScript. The CLI checks compliance automatically.

ARCH-003-api-routes.md

---
id: ARCH-003
title: API Route Conventions
domain: backend
rules: true
files:
  - "src/api/**/*.ts"
---

## Decision

All API route handlers must use the
createRoute() factory function.
Direct export default is prohibited.

## Do's and Don'ts

DO:  Use createRoute({ handler })
DON'T: Use export default function

ARCH-003-api-routes.rules.ts

import { defineRules } from "archgate/rules";

export default defineRules((ctx) => [
  {
    name: "require-createRoute",
    severity: "error",
    async run() {
      const files = await ctx.glob("src/api/**/*.ts");

      for (const file of files) {
        const hits = await ctx.grep(
          file, /export\s+default\s+function/
        );
        for (const hit of hits) {
          ctx.report({
            file, line: hit.line,
            message: "Use createRoute() factory",
          });
        }
      }
    },
  },
]);

Terminal

$ archgate check

ARCH-003 API Route Conventions

error require-createRoute: Use createRoute() factory

src/api/users/list.ts:14

1 violation found across 1 ADR

When you run archgate check, the CLI loads every ADR that has rules: true in its frontmatter, executes the companion rules file, and reports any violations. Exit code 0 means your code complies. Exit code 1 means it does not.

Key Features

Executable Rules

Write rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers. Rules live next to the decisions they enforce.

CI Integration

Wire archgate check into your pipeline. Exit code 1 blocks merges when rules are violated. Works with GitHub Actions, GitLab CI, or any CI system that respects exit codes.

AI-Aware Governance

The MCP server gives AI agents live access to your ADRs. They read decisions before writing code and validate after. No copy-pasting rules into prompts.

Self-Governance

Archgate governs its own development. The same tool that checks your code checks ours. Six ADRs enforce command structure, error handling, output formatting, testing, and more.

Editor plugins

The Archgate CLI works standalone, but editor plugins unlock a full AI governance workflow. Plugins give AI agents role-based skills so they read your ADRs before coding, validate after, and capture new patterns for your team — automatically.

Claude Code

The Claude Code plugin adds five skills: developer, architect, quality-manager, adr-author, and onboard. Agents follow a structured read-validate-capture loop on every task.

Cursor

The Cursor plugin provides pre-built agent rules and skills that give Cursor’s AI agent the same governance workflow as Claude Code.

Beta access

Editor plugins are currently in beta. Sign up at plugins.archgate.dev to get access, then install with archgate login and archgate init --install-plugin.

Claude Code plugin guide Full setup and usage guide for the Claude Code plugin.

Cursor integration guide Set up Archgate with Cursor IDE.

Learn more

What are ADRs? Understand Architecture Decision Records and how Archgate uses them.

Writing Rules Write TypeScript rules that enforce your decisions automatically.

CI Integration Block merges when rules are violated in GitHub Actions, GitLab CI, or any pipeline.

CLI Commands Complete reference for all Archgate CLI commands and options.