# Archgate - Complete Reference

> Enterprise-grade linting and guardrails for AI work. Write an ADR once. Enforce it everywhere.

Archgate is a free, open-source CLI tool that makes Architecture Decision Records (ADRs) executable. It provides linting and guardrails that AI coding agents and humans follow alike, bridging the gap between documentation (which gets ignored) and automated enforcement (which actually works).

## The Problem Archgate Solves

AI coding agents (Claude Code, Cursor, GitHub Copilot) generate code fast, but without guardrails they produce working-but-non-conforming code. Every team has conventions (API patterns, error handling, file structure), but AI agents don't know about them unless explicitly told.

Traditional documentation doesn't work because:
- Documents are passive. They inform but don't enforce
- AI agents can't read your wiki. They need decisions inside the codebase
- Knowledge fades over time. The engineer who wrote the doc leaves, context disappears

Archgate solves this by making architecture decisions executable: decisions are documented in Markdown, enforcement rules are written in TypeScript, and both AI agents and CI pipelines use them as the single source of truth.

## How Archgate Works

### The Learning Loop

Archgate implements a self-improving governance cycle:

1. **ADRs loaded as context**: AI agents read your Architecture Decision Records before writing code. They know your patterns, constraints, and conventions.
2. **`archgate check` in CI**: TypeScript rules validate every change in milliseconds. Free, deterministic, and catches ~80% of violations automatically.
3. **AI reviews the rest**: The architect skill reviews what automated rules can't catch: subjective quality, architectural fit, and design intent.
4. **System learns**: Every violation found during review becomes a new automated rule. Over time, governance gets cheaper and faster.

This creates a ratchet effect: every mistake becomes a permanent rule. Governance gets cheaper over time, not more expensive.

### What Makes an ADR "Executable"

An Architecture Decision Record becomes executable when it has:

1. **Decision documented**: Written in a structured Markdown format (the context, the decision, and the consequences). This is the single source of truth.
2. **Rules defined**: Alongside each decision, automated TypeScript rules encode the "do this, don't do that" into checks that run in milliseconds.
3. **Dual enforcement**: AI coding agents read the decisions before writing code. CI pipelines run the rules on every pull request. One source of truth, two enforcement points.

### ADR Structure

An Archgate ADR is a Markdown file in `.archgate/adrs/` with YAML frontmatter:

```markdown
---
id: ADR-001
title: API Error Handling
status: accepted
domain: backend
files:
  - "src/api/**/*.ts"
rules: true
---

## Context
Our API needs consistent error handling...

## Decision
All API endpoints must use the `ApiError` class...

## Do's and Don'ts
- DO: Use `ApiError` for all error responses
- DON'T: Throw raw Error objects from API handlers
- DO: Include error codes from the ErrorCode enum
```

When `rules: true`, a companion `.rules.ts` file provides automated checks.

## Installation & Quick Start

```bash
# macOS / Linux
curl -fsSL https://cli.archgate.dev/install-unix | sh

# Windows (PowerShell)
irm https://cli.archgate.dev/install-windows | iex
```

```bash
# Initialize Archgate in your project
archgate init

# Run compliance checks
archgate check

# Check only staged files
archgate check --staged
```

## Integrations

### Claude Code
Complete guardrails plugin with skills:
- **Developer agent**: Reads ADRs before coding, validates after, captures learnings
- **Architect skill**: Validates structural ADR compliance beyond automated rules
- **Quality-manager skill**: Captures session learnings and codifies them into new ADRs
- **ADR-author skill**: Creates and edits ADRs following project conventions
- **Onboard skill**: Sets up Archgate governance for a new project

### Cursor
Developer agent and guardrail skills for Cursor's AI assistant. ADRs become Cursor's rulebook, guiding code generation toward architectural standards.

### VS Code
Extension that distributes Archgate's skills directly to GitHub Copilot. Install from the VS Code marketplace or via `archgate plugin install --editor vscode`. Your ADRs become Copilot's architectural guardrails.

### GitHub Copilot
GitHub Copilot reads your ADRs through the VS Code extension. Architecture decisions guide Copilot's suggestions without extra configuration.

### CI/CD
Works with any CI system:
- GitHub Actions
- GitLab CI
- Any system that can run `archgate check` (exit code 1 = violations found)

## Archgate vs. Linters

Archgate does NOT replace linters. It complements them:

| Capability | Linters (ESLint, Biome, Ruff) | Type Checkers (tsc, pyright) | Archgate |
|---|---|---|---|
| Code style & formatting | Yes | No | Delegates |
| Type safety | No | Yes | Delegates |
| File & folder structure | No | No | Yes |
| Architecture boundaries | No | No | Yes |
| Cross-file conventions | No | No | Yes |
| AI agent alignment | No | No | Yes |
| Self-improving rules | No | No | Yes |
| Decision documentation | No | No | Yes |
| Language-agnostic | No | No | Yes |

Linters enforce code style (per-file, per-language). Archgate enforces architecture (cross-file, language-agnostic).

### AI Agent Token Efficiency

Without Archgate, AI agents spend ~67% more tokens discovering conventions through trial and error (grepping, reading files, guessing patterns). With Archgate, agents read structured ADRs upfront and produce conforming code on the first try.

## For Engineering Leaders

Archgate helps engineering leaders with:
- **Visibility**: See which decisions are being followed and which are drifting
- **Scalability**: Whether your org has 3 teams or 30, every codebase follows the same patterns
- **Zero overhead**: Guardrails run in the background. 0 manual overhead per commit
- **Fast setup**: From writing a decision to automated enforcement in ~5 minutes
- **ROI**: ~80% of violations caught by deterministic rules (free, fast)

## For Teams

Archgate helps every role:
- **Engineering Managers**: Replace subjective code review debates with objective, automated checks
- **Product Managers**: Reduced rework, fewer production surprises, predictable velocity
- **QA & Analysts**: Architecture rules catch structural issues before testing
- **New Team Members**: Onboard in hours. Decisions are documented, searchable, and enforced
- **Architects & Tech Leads**: Turn decisions into living, enforceable rules

## Technical Details

- **License**: Apache-2.0 (free and open source, forever)
- **Platforms**: macOS (ARM), Linux (x64), Windows (x64)
- **Language**: TypeScript
- **Rules engine**: TypeScript-based, runs in milliseconds, deterministic
- **Self-governance**: Archgate runs on its own rules. The CLI is checked against its own ADRs on every commit
- **Website**: https://archgate.dev
- **Documentation**: https://docs.archgate.dev
- **Source code**: https://github.com/archgate/cli
- **Contact**: hello@archgate.dev