Quick Start

This walkthrough takes you through the full governance loop end to end: install the CLI, scaffold a project, run a check, add an editor plugin, and have your AI agent review code against your ADRs. It should take under 10 minutes.

1. Install the CLI

   If you have not installed Archgate yet, use the one-line installer (no Node.js required):

   macOS / Linux

   curl -fsSL https://cli.archgate.dev/install-unix | sh

   Windows (PowerShell)

   irm https://cli.archgate.dev/install-windows | iex

   See Installation for proto, npm, and all other options.

2. Initialize your project

   From your project root, scaffold governance:

   cd my-project
   archgate init

   This creates an .archgate/ directory containing a sample ADR, its companion .rules.ts rules file, and the Archgate configuration. The generated files are a working example you can build on. The full layout and the ADR frontmatter format are documented in the CLI Quick Start.

3. Run your first check

   Run the deterministic compliance checker against your codebase:

   archgate check

   Archgate loads every ADR marked with rules: true, executes its companion rules file, and reports any violations with file paths and line numbers. The exit code tells you the outcome — 0 means everything complies, 1 means one or more violations were found, 2 means an internal error.

   This is the detection stage of the loop, and it is the hard gate you wire into CI and pre-commit. To check only staged files:

   archgate check --staged

   Wire it into your workflow

   Once the check passes locally, add it to your pipeline. See CI Integration and Pre-commit Hooks.

4. Add an editor plugin

   The CLI works standalone, but the editor plugin is what closes the loop — it gives your AI agent a governance workflow so it reads your ADRs before coding and validates after. The plugin is currently in beta, so first authenticate:

   archgate login

   This starts a GitHub device flow: the CLI shows a one-time code and URL, you authorize in the browser, and credentials are stored securely. Once logged in, install the plugin for your editor:

   archgate plugin install

   Archgate supports six editors — Claude Code, Cursor, VS Code, Copilot CLI, Claude Desktop, and OpenCode. To see what each plugin adds and the exact per-editor setup, see the Plugins overview.

   First time on a project?

   Run the @onboard skill once after installing. It explores your codebase, interviews you about your conventions, and creates an initial set of ADRs. See Skills.

5. Run the reviewer

   Now exercise the AI layer. After your agent (or you) makes a code change, invoke the @reviewer skill in your editor:

   @reviewer

   The reviewer gathers all ADRs applicable to your changes via archgate review-context, runs the automated checks, and delegates each affected domain to a focused sub-agent that verifies compliance — catching the judgment calls a linter cannot make. This is the AI-review half of the detection stage.

   When the reviewer or a real incident surfaces a pattern worth codifying, run the @lessons-learned skill to capture it into a new or updated ADR. That new rule flows back into prevention — the next time your agent writes code, it reads that decision before it starts. The loop is now closed.

What you just did

You ran every stage of the governance loop:

• Prevention — archgate init scaffolded ADRs; the plugin feeds them to your AI agent as context.
• Detection — archgate check validated deterministically; @reviewer added AI judgment.
• Learning — @lessons-learned turns findings into new rules that strengthen prevention.

What’s next

Concepts: the governance loop Go deeper on prevention, detection, and learning.

Editor Plugins Compare the six supported editors and their setup.

Skills Reviewer, lessons-learned, adr-author, onboard, and cli-reference.

ADR Packs Import ready-made ADR packs instead of writing every rule yourself.

CLI Quick Start Write your first ADR and rule, with full command and schema detail.

CI Integration Block merges when rules are violated.